Using OpenData in Google Colab

Google Colab runs Python notebooks in your browser with nothing to install. This is the fastest way to start working with OpenData.

What's Google Colab?

Google Colab is a free, hosted notebook environment from Google. Python is already installed, and you get a VM with CPU, RAM, and optional GPU access. You write code in cells, run each one individually, and see results inline. No local setup required.

Open the Starter Notebook

The fastest path is to open our pre-built notebook. It installs the SDK, loads a dataset, filters it, and plots a chart. Just hit Runtime → Run all and watch it go.

Open starter notebook in Google Colab →

Start from Scratch

If you want a blank slate: go to colab.research.google.com and create a new notebook, then follow the steps below.

Step 1: Install the SDK

In the first cell, install the OpenData Python package. The ! prefix tells Colab to run this as a shell command.

!pip install tryopendata[pandas]

Wait for the install output to finish before running the next cell.

If you see "Cannot install pip dependencies without Python installed in the environment", click Runtime → Change runtime type and make sure "Python 3" is selected.

Step 2: Load a Dataset

from opendata_sdk import OpenData


# No API key required for public datasets.
# Create a free account for higher limits (no credit card):
# https://tryopendata.ai/settings/api-keys
client = OpenData()  # or: OpenData(api_key="od_live_...")
df = client.load("fred/unemployment-rate").to_pandas()
df.head()

Run it. You should see a table with monthly US unemployment rate data. That's the core loop: create a client, load a dataset, call .to_pandas(), and preview with .head().

Complete Working Example

Copy this into a single cell to load, filter, and chart US unemployment data. You'll see the COVID-19 spike in 2020.

# ── Install (skip if you already ran the install cell above) ──
!pip install -q tryopendata[pandas] matplotlib


# ── Setup ──
from opendata_sdk import OpenData, Query


# No key needed for public data. Create a free account for higher limits:
# https://tryopendata.ai/settings/api-keys (no credit card required)
client = OpenData()  # or: OpenData(api_key="od_live_...")


# ── Inspect the dataset before loading ──
meta = client.meta("fred/unemployment-rate")
print(f"Dataset:  {meta.name}")
print(f"Rows:     {meta.rows:,}")
print(f"Columns:  {[c.name for c in meta.columns]}")
print()


# ── Load with server-side filters ──
# Only matching rows are downloaded, so this is fast even for big datasets
q = (
    Query()
    .gte("date", "2010-01-01")              # 2010 onward
    .fields("date", "unemployment_rate")     # just these two columns
    .sort("date")                            # oldest first
)
df = client.load("fred/unemployment-rate", q).to_pandas()
print(f"Loaded {len(df)} rows\n")


# ── Preview the data ──
print(df.head(10))
print()


# ── Plot a chart ──
ax = df.assign(date=df["date"].astype(str)).plot(
    x="date",
    y="unemployment_rate",
    title="US Unemployment Rate (2010 - Present)",
    xlabel="Date",
    ylabel="Unemployment Rate (%)",
    figsize=(12, 5),
    legend=False,
)
ax.figure.tight_layout()


# ── Summary stats ──
print(f"Range: {df['unemployment_rate'].min():.1f}% to {df['unemployment_rate'].max():.1f}%")
print(f"Latest: {df['unemployment_rate'].iloc[-1]:.1f}%")

Finding Datasets

Search the catalog directly from Colab. No need to open a browser tab.

results = client.search("consumer price index")
for ds in results.results:
    print(f"{ds.provider}/{ds.slug}: {ds.name}")
    print(f"  {(ds.description or '')[:80]}...")
    print()

Each dataset has a path like fred/unemployment-rate or fred/cpi. Pass that to client.load(). You can also browse the full catalog at tryopendata.ai/explore.

Using Views

Some datasets have pre-built "views" that reshape the raw data. A monthly dataset might have a timeseries view that normalizes dates, or an annual view that aggregates by year.

from opendata_sdk import Query


# Load the annual average instead of monthly data points
df = client.load("fred/unemployment-rate", Query().view("annual")).to_pandas()
df.head()

Every dataset page on tryopendata.ai has a Notebook tab in the API Examples section with a ready-to-paste snippet.

Storing Your API Key Securely

Public datasets work without any key. For higher rate limits, use Colab Secrets so your key isn't visible to anyone you share the notebook with:

from google.colab import userdata
client = OpenData(api_key=userdata.get("OPENDATA_API_KEY"))

To set this up: click the key icon in the left sidebar, add a secret named OPENDATA_API_KEY with your key value, and toggle "Notebook access" on. Get your key at tryopendata.ai/settings/api-keys (free, no credit card).

SQL Queries

You can run DuckDB-compatible SQL directly against any dataset using client.sql.execute(). It handles JOINs across datasets, window functions, GROUP BY, and anything the Query Builder can't express. SQL queries require an API key -- store it in Colab Secrets as shown in the section above.

from opendata_sdk import OpenData
from google.colab import userdata


client = OpenData(api_key=userdata.get("OPENDATA_API_KEY"))


# Single dataset query
result = client.sql.execute("SELECT year, value FROM fred/gdp WHERE year > 2020 ORDER BY year")
df = result.to_pandas()
df.head()
# Cross-dataset JOIN -- reference datasets by provider/slug in SQL
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()
df.head()

For the full SQL reference -- bind parameters, options, result metadata, and async usage -- see the Python SDK docs.

Colab Tips

  • Runtime disconnects: Colab VMs shut down after ~90 minutes of inactivity. You'll need to re-run the install cell when reconnecting.
  • Large datasets: Colab gives you ~12GB of RAM on the free tier. For datasets that don't fit, process in chunks:
for page in client.datasets.query_iter("census/acs5", page_size=5000):
    chunk = page.to_pandas()
    print(f"Processing {len(chunk)} rows...")
    # do something with each chunk
  • Saving notebooks: Colab auto-saves to Google Drive. You can also download as .ipynb via File → Download.

What's Next

  • Python SDK Reference -- full SDK docs including async usage, error handling, and all available methods
  • Querying Guide -- all filter operators, sorting, aggregation, and advanced queries
  • Views -- how dataset views work
  • Authentication -- API key management and rate limits

Search datasets

Search for datasets or run quick actions