jyapystock

A Python library to fetch live and historical prices for Indian, American, and European stocks.

Status Badges

Features

• Live price and historical price support with timestamp and % change data
• Indian (NSE/BSE), American (NYSE/NASDAQ), and European (Xetra/Euronext) stocks
• Multiple data sources: yfinance, NASDAQ, NSE (for India), Alpha Vantage (optional API key)
• Auto-fallback: tries available sources in order based on country and API key availability
• Country support: India, USA, and Europe with automatic symbol variant detection (e.g., .NS/.BO for Indian stocks, .DE/.PA/.AS/.BR/.LS for European stocks)

Installation

pip install jyapystock

Installation for Development

Dependencies are locked with Poetry (poetry.lock) for CI reproducibility:

pip install poetry
poetry install --extras dev

This installs the package in editable mode along with dev tools (pytest, pytest-cov, flake8). Run commands inside the managed environment with poetry run, e.g. poetry run pytest.

Usage

Basic Usage - USA Stocks

from jyapystock import StockPriceProvider

# Using yfinance (default)
provider = StockPriceProvider(country="USA")
result = provider.get_live_price("AAPL")
# Returns: {'timestamp': '2025-12-24T00:00:00-05:00', 'price': 273.81, 'change_percent': 0.53}

Indian Stocks with NSE

from jyapystock import StockPriceProvider

# Using NSE (National Stock Exchange)
provider = StockPriceProvider(country="India", source="nse")
result = provider.get_live_price("SBIN")
# Returns: {'timestamp': '24-Dec-2025 16:00:00', 'price': 968.85, 'change_percent': -0.31}

# Using yfinance for India (auto-tries .NS and .BO variants)
provider = StockPriceProvider(country="India")
result = provider.get_live_price("RELIANCE")

European Stocks with Xetra/Euronext

from jyapystock import StockPriceProvider

# Using yfinance for a specific exchange
provider = StockPriceProvider(country="europe", exchange="xetr")
result = provider.get_live_price("SAP")
# Resolves to SAP.DE

provider = StockPriceProvider(country="europe", exchange="xpar")
result = provider.get_live_price("MC")
# Resolves to MC.PA

# No exchange given -- tries every suffix (.DE, .PA, .AS, .BR, .LS) until one resolves
provider = StockPriceProvider(country="europe")
result = provider.get_live_price("SAP")

Historical Data

# Get historical prices
hist = provider.get_historical_price("AAPL", "2023-01-01", "2023-01-31")
# Returns list of records with date/open/high/low/close/volume

Using NASDAQ Provider

provider = StockPriceProvider(country="USA", source="nasdaq")
result = provider.get_live_price("AAPL")

Using Alpha Vantage (requires API key)

provider = StockPriceProvider(
    country="USA", 
    source="alphavantage", 
    alpha_vantage_api_key="YOUR_API_KEY"
)
result = provider.get_live_price("AAPL")

Multiple Providers with Fallback

You can specify multiple sources as a list. The provider will try them in order until one returns data:

# Try NSE first, then fall back to yfinance for Indian stocks
provider = StockPriceProvider(country="India", source=["nse", "yfinance"])
result = provider.get_live_price("RELIANCE")

# Try NASDAQ first, then NASDAQ, then yfinance for USA stocks
provider = StockPriceProvider(country="USA", source=["nasdaq", "yfinance"])
result = provider.get_live_price("AAPL")

# Try BSE for historical data, fall back to yfinance
provider = StockPriceProvider(country="India", source=["bse", "yfinance"])
hist = provider.get_historical_price("NSDL", "2025-12-01", "2025-12-31")

You can also pass a single provider as a string:

# Equivalent to source=["bse"]
provider = StockPriceProvider(country="India", source="bse")
result = provider.get_live_price("NSDL")

Supported Sources

• yfinance: Free, supports most global stocks (USA, India & Europe)
• NASDAQ: Free, USA stocks only
• NYSE: Free, USA stocks only
• NSE: Free, Indian stocks only (via National Stock Exchange)
• BSE: Free, Indian stocks only (via Bombay Stock Exchange)
• Alpha Vantage: Free tier with limits, requires API key, supports global stocks

Testing

Install dependencies (see Installation for Development)

poetry install --extras dev

Run tests

poetry run python -m unittest discover tests

# Run provider-specific tests
PROVIDER=yfinance poetry run python -m unittest discover tests
PROVIDER=nse poetry run python -m unittest discover tests
PROVIDER=bse poetry run python -m unittest discover tests
PROVIDER=nasdaq poetry run python -m unittest discover tests
PROVIDER=alphavantage poetry run python -m unittest discover tests

License

MIT