Official Python Library

DataSetIQ for Python

Access millions of economic time series with just pip install datasetiq

View on PyPI View on GitHub

📦 Installation

pip install datasetiq

Requires Python 3.9+. Automatically installs pandas and requests.

🚀 Quick Start

1. Get Your API Key

Get Free API Key →

2. Use the Library

import datasetiq as iq

# Set your API key (one-time setup)
iq.set_api_key("your_api_key_here")

# Get data as pandas DataFrame
df = iq.get("FRED/CPIAUCSL")

# Display first few rows
print(df.head())

# Basic analysis
latest = df.iloc[-1]
print(f"Latest CPI: {latest['value']} on {latest['date']}")

# Calculate year-over-year inflation
df['yoy_inflation'] = df['value'].pct_change(12) * 100
print(df.tail())

✅ Free Tier Includes:

• 25 requests per minute
• Unlimited observations per request
• Full date range filtering
• 10 AI insights per month

📖 Complete API Reference

`iq.get()`

Fetch time series data as a pandas DataFrame.

Parameters:

Parameter	Type	Description
`series_id`	str	Series ID (e.g., "FRED/CPIAUCSL", "WB/USA/GDP")
`start`	str (optional)	Start date (YYYY-MM-DD) - Requires API key
`end`	str (optional)	End date (YYYY-MM-DD) - Requires API key

Examples:

Basic usage:

import datasetiq as iq

# Get all available data
df = iq.get("FRED/CPIAUCSL")
print(df.shape)  # (100, 2) in anonymous mode, full history with API key

Date range filtering (requires API key):

# Get data for specific date range
df = iq.get("FRED/CPIAUCSL", start="2020-01-01", end="2023-12-31")
print(df.shape)  # (~48, 2) - monthly data for 4 years

Recent data only:

# Get data from 2020 onwards
df = iq.get("FRED/CPIAUCSL", start="2020-01-01")
print(df.tail())

`iq.set_api_key()`

Set your DataSetIQ API key for authenticated requests.

import datasetiq as iq

# Set API key (one-time per session)
iq.set_api_key("dsiq_1234567890abcdef")

# Or use environment variable
import os
iq.set_api_key(os.getenv("DATASETIQ_API_KEY"))

`iq.search()`

Search for datasets (keyword or semantic mode).

Keyword search (default):

import datasetiq as iq

# Works with or without API key (limit 10)
results = iq.search("unemployment rate", limit=5)
print(results[["id", "title", "provider"]])

Semantic search (when supported by your plan/API):

semantic = iq.search("housing affordability in Texas", mode="semantic")
print(semantic[["id", "title", "provider"]].head())

`iq.add_features()`

Generate lags, rolling stats, MoM/YoY %, and z-scores for a single series.

import datasetiq as iq

iq.set_api_key("your_api_key")

df = iq.add_features("fred-cpi", lags=[1, 3, 12], windows=[3, 12])
print(df[["value", "value_yoy_pct", "value_mom_pct", "value_lag_1"]].tail())

`iq.get_insight()`

Lightweight summary with latest value, MoM/YoY change, volatility, and trend.

import datasetiq as iq

iq.set_api_key("your_api_key")

insight = iq.get_insight("fred-cpi", window="1y")
print(insight["summary"])
# fred-cpi: latest 311.17 on 2023-12-01 | +0.24% vs prior | +3.12% YoY | trend upward | volatility (std) 1.23

`iq.get_ml_ready()`

Fetch multiple series, align dates, impute gaps, and add per-series features. Requires API key on a paid plan.

import datasetiq as iq

iq.set_api_key("your_api_key")

df = iq.get_ml_ready(
    ["fred-cpi", "fred-gdp"],
    align="inner",             # or "outer"
    impute="ffill+median",     # ffill, median, bfill supported
    features="default",        # set to None to skip features
    lags=[1, 3, 12],
    windows=[3, 12],
)
print(df.tail())

💡 Common Use Cases

Feature Engineer a Single Series

import datasetiq as iq

iq.set_api_key("your_api_key")

df = iq.add_features("fred-cpi", lags=[1, 3, 12], windows=[3, 12])
print(df[["value", "value_yoy_pct", "value_mom_pct", "value_lag_1"]].tail())

Build an ML-Ready Panel

import datasetiq as iq

iq.set_api_key("your_api_key")

df = iq.get_ml_ready(
    ["fred-cpi", "fred-gdp", "fred-unrate"],
    align="inner",
    impute="ffill+median",
    features="default",
)
print(df.tail())

Quick Insight Summary

import datasetiq as iq

iq.set_api_key("your_api_key")

insight = iq.get_insight("fred-cpi", window="1y")
print(insight["summary"])

Build a Dataset from Search

import datasetiq as iq
import pandas as pd

iq.set_api_key("your_api_key")

# Search for GDP indicators
results = iq.search("gdp growth quarterly", limit=5)

# Fetch all series and combine
all_data = {}
for _, row in results.iterrows():
    series_id = row['id']
    title = row['title']
    
    try:
        df = iq.get(series_id, start="2020-01-01")
        all_data[title] = df["value"]
    except Exception as e:
        print(f"Failed to fetch {series_id}: {e}")

# Combine into one DataFrame
combined = pd.DataFrame(all_data)
print(combined.head())
combined.to_csv("gdp_indicators.csv")

Flag Anomalies with Z-Scores

import datasetiq as iq

iq.set_api_key("your_api_key")

df = iq.add_features("fred-cpi", windows=[6])
df["anomaly"] = df["value_zscore"].abs() > 3

print(df[df["anomaly"]].tail())

Export Panel to Excel/CSV

import datasetiq as iq

iq.set_api_key("your_api_key")

panel = iq.get_ml_ready(
    ["fred-cpi", "fred-gdp", "fred-unrate"],
    align="outer",
    impute="ffill+median",
)

panel.to_csv("macro_panel.csv")
panel.to_excel("macro_panel.xlsx", sheet_name="macro")
print("Saved panel:", panel.shape)

🛡️ Error Handling

import datasetiq as iq

iq.set_api_key("your_api_key")

try:
    df = iq.get("FRED/INVALID_SERIES")
except iq.NotFoundError as e:
    print(f"Series not found: {e}")
except iq.RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    print("Try upgrading your plan or wait a moment")
except iq.AuthenticationError as e:
    print(f"Invalid API key: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Common Errors:

SeriesNotFoundError: Series ID doesn't exist
RateLimitError: Exceeded requests per minute (5 anonymous, 25 free, 100+ paid)
AuthenticationError: Invalid or missing API key