fa-inrdata-api 0.1.0

Python API for historical INR valuations of US-listed stocks, designed for Indian Income Tax Schedule FA reporting.

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

pip install fa-inrdata-api

Requires Python 3.10+

---

Quick Example

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

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

import fa_inrdata_api as fa

print(fa.supported_tickers())

---

Supported Years

import fa_inrdata_api as fa

print(fa.supported_years_for_ticker("AAPL"))

Example

[2025]

---

Get Company Metadata

import fa_inrdata_api as fa

info = fa.ticker_metadata("AAPL")

print(info)

Returns

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

---

Complete Daily Price History

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

print(rows[0])

Returns

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

---

Value on a Specific Date

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

fa.value_at_year_start("AAPL", 2025)

---

Closing Value

fa.value_at_year_end("AAPL", 2025)

---

Maximum Value

Entire year

fa.max_value("AAPL", 2025)

Custom period

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

---

Minimum Value

fa.min_value("AAPL", 2025)

---

Schedule FA Summary

This convenience function returns everything typically required for Schedule FA.

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

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

Returns

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.

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.