finsdk

Python SDK for financial data and visualization.

Get economic indicators, stock prices, and create beautiful charts with just a few lines of code.

Installation

pip install finsdk

Quick Start

import finsdk

# Set your API key (or use SAVVY_API_KEY environment variable)
finsdk.configure(api_key="sk_...")

# Fetch economic data (returns pandas DataFrame)
df = finsdk.economic_data.fetch("UNRATE", start="2020-01-01")
print(df.head())
#         date  value
# 0 2020-01-01    3.6
# 1 2020-02-01    3.5
# 2 2020-03-01    4.4

# Fetch stock data
df = finsdk.stock_data.fetch("AAPL", period="1y")

# Create a visualization
chart = finsdk.visualize(df, "Stock price over time")
print(chart.url)  # https://savvy-mcp.com/c/abc123

Features

Economic Data

Access data from 20+ sources including FRED, World Bank, IMF, ECB, and more:

# US unemployment rate
df = finsdk.economic_data.fetch("UNRATE")

# GDP growth with date range
df = finsdk.economic_data.fetch("GDP", start="2010-01-01", end="2023-12-31")

# Search for data series
results = finsdk.economic_data.search("inflation")
for r in results:
    print(f"{r['provider']}: {r['series_id']} - {r['name']}")

# Compare across countries
df = finsdk.economic_data.compare("unemployment", ["US", "Germany", "Japan"])

Stock Data

Get stock prices from Yahoo Finance:

# Historical data
df = finsdk.stock_data.fetch("AAPL", period="1y")
df = finsdk.stock_data.fetch("MSFT", period="5y", interval="1wk")

# Current quote
quote = finsdk.stock_data.quote("AAPL")
print(f"AAPL: ${quote['price']:.2f} ({quote['change_percent']:+.2f}%)")

Cryptocurrency Data

# Bitcoin price history
df = finsdk.crypto_data.fetch("BTC-USD", period="1y")

# Ethereum quote
quote = finsdk.crypto_data.quote("ETH")

Visualization

Create charts with natural language:

# Simple visualization
chart = finsdk.visualize(df, "Line chart of stock price over time")

# With options
chart = finsdk.visualize(
    df,
    "Show closing prices with a trendline",
    title="AAPL Stock Price",
    theme="executive",
)

# Access chart URLs
print(chart.url)     # Interactive HTML
print(chart.png)     # PNG image
print(chart.svg)     # SVG image
print(chart.python)  # Python code

Configuration

import finsdk

# Option 1: Use configure()
finsdk.configure(api_key="sk_...")

# Option 2: Environment variable (recommended for production)
# export SAVVY_API_KEY=sk_...

# Option 3: Custom API URL (for development)
finsdk.configure(api_key="sk_...", api_url="https://custom.api.com")

# Read current config
print(finsdk.api_key)  # Returns configured key

Error Handling

from finsdk import SavvyError, AuthenticationError, DataNotFoundError

try:
    df = finsdk.economic_data.fetch("INVALID_SERIES")
except DataNotFoundError as e:
    print(f"Series not found: {e.series_id}")
except AuthenticationError:
    print("Invalid API key")
except SavvyError as e:
    print(f"API error: {e}")

Data Sources

Requirements

• Python 3.9+
• pandas
• httpx

Links

• Documentation
• API Reference
• Get an API Key

License

MIT