Python SDK

# With pandas (recommended for most users)
pip install tryopendata[pandas]

# With polars
pip install tryopendata[polars]

# Base install (works without any DataFrame library)
pip install tryopendata

from opendata_sdk import OpenData

client = OpenData()

# Load everything into a DataFrame -- the simplest path
df = client.load("bls/cpi-u").to_pandas()

# Sample the first 1,000 rows for quick exploration
sample = client.query("bls/cpi-u").to_pandas()

# Process a huge dataset without loading it all at once
for page in client.datasets.query_iter("census/acs5", page_size=5000):
    df = page.to_pandas()
    process(df)  # handle each chunk

from opendata_sdk import OpenData, Query

client = OpenData()

q = (
    Query()
    .fields("date", "value", "series_id")  # select only these columns
    .eq("series_id", "CUUR0000SA0")        # exact match
    .gte("year", 2020)                     # range filter
    .sort("date", desc=True)               # newest first
    .limit(500)
)

df = client.load("bls/cpi-u", q).to_pandas()
print(df.head())

# Base query you'll reuse
base = Query().fields("year", "state", "value").gte("year", 2000)

# Branch for different states -- base stays untouched
ca = client.load("census/population", base.eq("state", "CA")).to_pandas()
tx = client.load("census/population", base.eq("state", "TX")).to_pandas()

from opendata_sdk import OpenData, Query

client = OpenData()

# Total population and year count, grouped by state
q = (
    Query()
    .group_by("state")
    .aggregate("sum:population", "count:year")
)

df = client.load("census/population", q).to_pandas()
print(df.head())

# Full metadata (renders as HTML in Jupyter)
meta = client.meta("bls/cpi-u")
print(meta.name)             # dataset name
print(meta.description)      # what it contains
print(meta.rows)             # total rows
print(meta.available_views)  # alternate views like 'timeseries', 'by_state'

# Column stats -- types, distinct values, nulls, sample values
columns = client.datasets.columns("bls/cpi-u")
for col in columns:
    print(f"{col.name} ({col.type}): {col.distinct_count} distinct")

# Result schema -- works without fetching all data
result = client.query("bls/cpi-u")
print(result.dtypes)   # {'year': 'BIGINT', 'value': 'DOUBLE', ...}
print(result.schema)   # [{'name': 'year', 'type': 'BIGINT'}, ...]

# See what views are available
views = client.datasets.views("bls/cpi-u")
for v in views:
    print(f"{v.name}: {v.description}")

# Use a specific view
df = client.load("bls/cpi-u", Query().view("timeseries")).to_pandas()

from opendata_sdk import OpenData

client = OpenData(api_key="od_live_...")

result = client.sql.execute("SELECT year, value FROM fred/gdp WHERE year > 2020 ORDER BY year")
df = result.to_pandas()
print(df)

result = client.sql.execute("""
    SELECT a.year, a.value AS gdp, b.population
    FROM fred/gdp a
    JOIN census/population b ON a.year = b.year
    WHERE a.year > 2015
""")

df = result.to_pandas()
print(df.head())

result = client.sql.execute(
    "SELECT * FROM fred/gdp WHERE year > ? AND value < ?",
    params=[2020, 100.0],
)

df = result.to_pandas()

# Limit execution time and cap the number of rows returned
result = client.sql.execute(
    "SELECT * FROM fred/gdp",
    timeout_ms=3000,
    row_limit=500,
)

# Result metadata
print(result.execution_time_ms)  # 125.0
print(result.truncated)          # False -- True if row_limit was hit
print(result.row_count)          # 5

# Convert to DataFrame the same way as load() / query()
df = result.to_pandas()
df = result.to_polars()  # if you installed tryopendata[polars]

# Full-text search -- returns rich metadata for each match
results = client.search("inflation")
for ds in results.results:
    print(f"{ds.provider}/{ds.slug}: {ds.name}")
    print(f"  {(ds.description or '')[:80]}...")
    print()

# Autocomplete -- fast, minimal results, good for search-as-you-type
suggestions = client.suggest("inf")
for s in suggestions:
    print(s.slug)

# Option 1: pass directly
client = OpenData(api_key="od_live_...")

# Option 2: environment variable (SDK reads it automatically)
# export OPENDATA_API_KEY=od_live_...
client = OpenData()

from opendata_sdk.aio import OpenData as AsyncOpenData

async with AsyncOpenData(api_key="od_live_...") as client:
    # Load a dataset
    df = await client.load("bls/cpi-u")
    df = df.to_pandas()

    # Search the catalog
    results = await client.search("unemployment rate")

    # Run a SQL query
    result = await client.sql.execute("SELECT * FROM fred/gdp LIMIT 10")
    df = result.to_pandas()

from opendata_sdk import (
    OpenData,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    InvalidRequestError,
    APIConnectionError,
)

client = OpenData()

try:
    df = client.load("bls/cpi-u", Query().eq("bad_column", "x")).to_pandas()
except AuthenticationError:
    # Your API key is missing or invalid.
    # The error message includes instructions for setting OPENDATA_API_KEY.
    raise
except NotFoundError as e:
    # Dataset path doesn't exist. The error suggests how to search for the right path.
    print(f"Not found: {e.message}")
    results = client.search("cpi")  # find what you were looking for
except InvalidRequestError as e:
    # Bad filter, wrong column name, etc.
    # The error message names the column naming rules and points to client.meta().
    print(e)  # prints the API message + guidance on valid column names
except RateLimitError as e:
    # The SDK retries automatically, but if retries are exhausted:
    print(f"Still rate limited after retries. Wait {e.retry_after}s")
except APIConnectionError:
    # Network issue or timeout. Increase timeout if needed:
    slow_client = OpenData(timeout=60.0)
    df = slow_client.load("bls/cpi-u").to_pandas()

client = OpenData(
    api_key="od_live_...",                  # or OPENDATA_API_KEY env var
    base_url="https://custom.api/v1",  # default: https://api.tryopendata.ai/v1
    timeout=60.0,                      # request timeout in seconds (default: 30)
    max_retries=5,                     # retry count for GET requests (default: 3)
)

# Use as a context manager to clean up connections automatically
with OpenData() as client:
    df = client.load("census/state-populations").to_pandas()