Metadata-Version: 2.4
Name: fa-inrdata-api
Version: 0.1.0
Summary: Python API for historical INR valuations of US-listed stocks, designed for Indian Income Tax Schedule FA reporting.
Project-URL: Homepage, https://github.com/jdecodes/fa-inrdata
Project-URL: Repository, https://github.com/jdecodes/fa-inrdata
Project-URL: Issues, https://github.com/jdecodes/fa-inrdata/issues
Author-email: jdecodes <jaideep_sharma@live.com>
License-Expression: MIT
License-File: LICENSE
Keywords: exchange-rate,finance,foreign-assets,forex,income-tax,india,itr,sbi,schedule-fa,stocks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# fa-inrdata-api

> A lightweight Python API for historical INR-adjusted stock prices, built specifically for Indian Income Tax **Schedule FA** reporting.

`fa-inrdata-api` provides historical daily stock prices already converted to INR using the corresponding **State Bank of India (SBI) TT Buying Rate** for that date. Instead of downloading Yahoo Finance prices, searching SBI TT rates, and performing currency conversion yourself, this package gives you the final INR value in one API call.

The data is powered by the **fa-inrdata** dataset.

---

## Why?

While filing **Schedule FA (Foreign Assets)** in the Indian Income Tax Return, taxpayers are required to report values such as:

- Initial value of investment
- Peak value during the year
- Closing balance
- Value on a specific acquisition date

Obtaining these values is surprisingly tedious.

Typically you need to

- download historical stock prices
- obtain historical SBI TT buying rates
- convert every day's closing price into INR
- determine the maximum INR value for the required period

This package performs those steps for you.

---

## Features

- Historical daily close prices
- Historical SBI TT Buying rates
- Daily INR converted prices
- Initial value for a year
- Closing value for a year
- Peak INR value for a year
- Peak INR value within a custom date range
- Value on any date (with automatic previous trading day fallback)
- Ticker metadata
- Local caching
- Zero third-party dependencies

---

## Installation

```bash
pip install fa-inrdata-api
```

Requires Python **3.10+**

---

## Quick Example

```python
import fa_inrdata_api as fa

summary = fa.schedule_fa_summary("AAPL", 2025)

print(summary.initial)
print(summary.peak)
print(summary.closing)
```

---

## Using the Object-Oriented API

```python
from fa_inrdata_api import Ticker

aapl = Ticker("AAPL", 2025)

print(aapl.schedule_fa_summary())
print(aapl.max_value())
print(aapl.value_at_start())
print(aapl.value_at_end())
```

---

## Supported Tickers

```python
import fa_inrdata_api as fa

print(fa.supported_tickers())
```

---

## Supported Years

```python
import fa_inrdata_api as fa

print(fa.supported_years_for_ticker("AAPL"))
```

Example

```python
[2025]
```

---

## Get Company Metadata

```python
import fa_inrdata_api as fa

info = fa.ticker_metadata("AAPL")

print(info)
```

Returns

```python
TickerInfo(
    ticker="AAPL",
    name="Apple Inc.",
    address="One Apple Park Way",
    zip="95014",
    country="United States",
)
```

---

## Complete Daily Price History

```python
rows = fa.price_action("AAPL", 2025)

print(rows[0])
```

Returns

```python
PriceRow(date="2025-01-02", close=243.85, sbi_tt=85.64, close_inr=20880.11)
```

---

## Value on a Specific Date

```python
import fa_inrdata_api as fa

row = fa.value_on_date("AAPL", "2025-05-17")

print(row)
```

If the supplied date falls on a weekend or market holiday, the package automatically returns the nearest previous trading day.

---

## Initial Value

```python
fa.value_at_year_start("AAPL", 2025)
```

---

## Closing Value

```python
fa.value_at_year_end("AAPL", 2025)
```

---

## Maximum Value

Entire year

```python
fa.max_value("AAPL", 2025)
```

Custom period

```python
fa.max_value(
    "AAPL",
    2025,
    start_date="2025-03-15",
    end_date="2025-08-31",
)
```

---

## Minimum Value

```python
fa.min_value("AAPL", 2025)
```

---

## Schedule FA Summary

This convenience function returns everything typically required for Schedule FA.

```python
summary = fa.schedule_fa_summary("AAPL", 2025)

print(summary.initial)
print(summary.peak)
print(summary.closing)
```

Returns

```python
ScheduleFASummary(ticker="AAPL", year=2025, initial=..., peak=..., closing=...)
```

---

## Warm the Cache

The package downloads data lazily and stores it locally.

If desired, you can warm the cache beforehand.

```python
import fa_inrdata_api as fa

fa.warm_cache()
```

---

## Caching

Downloaded files are cached locally under

```
~/.cache/fa_inrdata_api/
```

Subsequent requests are served directly from the cache.

---

## Data Source

This package reads data from

https://github.com/jdecodes/fa-inrdata

Each ticker has one CSV per calendar year.

```
data/
    AAPL/
        2023.csv
        2024.csv
        2025.csv

    MSFT/
        ...
```

Each CSV contains

| Column | Description |
|---------|-------------|
| date | Trading date |
| close | Yahoo Finance closing price |
| sbi_tt | SBI TT Buying Rate |
| close_inr | close × sbi_tt |

---

## Why SBI TT Buying Rate?

Indian Income Tax guidance for Schedule FA generally requires foreign asset values to be converted into INR using the **State Bank of India Telegraphic Transfer (TT) Buying Rate**.

This package performs that conversion in advance.

---

## Disclaimer

This is an **unofficial**, community-maintained package.

It is **not affiliated with**

- State Bank of India (SBI)
- Yahoo Finance
- Indian Income Tax Department

Although every effort is made to ensure accuracy, the data may contain errors or omissions.

Always verify important values against official sources before filing taxes or making financial decisions.

---

## License

MIT License

---

## Related Project

This package is powered by the underlying dataset:

**fa-inrdata**

https://github.com/jdecodes/fa-inrdata

---

## Author

Built by **jdecodes** : https://github.com/jdecodes


Contributions, bug reports, feature requests, and pull requests are always welcome.