Getting Started with the Data.gov Catalog API — Data.gov

When to use this API

When a user needs to find U.S. government open datasets — environmental monitoring, economic statistics, public health records, local government figures — the Data.gov CKAN API is the catalog index. It returns metadata: titles, descriptions, publisher names, and download links for datasets, not the underlying data files themselves. Reach for it when the question is "does the government have data on X?" rather than "give me the actual data." If the user already has a specific dataset in hand, this API won't help — they need the dataset's own API or download URL.

Discovering what thematic groups organize the catalog

"What broad topics does data.gov cover?" group_list returns the catalog's editorial groupings — a quick structural map before committing to a search query.

curl "https://catalog.data.gov/api/3/action/group_list" | head -c 10000

{
  "success": true,
  "result": [
    "agriculture8571",
    "climate5434",
    "energy9485",
    "local",
    "maritime",
    "ocean9585",
    "older-adults-health-data"
  ]
}

Only seven groups exist — far fewer than the breadth of the catalog suggests. The numeric suffixes on some slugs (climate5434, ocean9585) but not others (local, maritime) reflect CKAN's internal ID-collision handling: when a group name was already taken during a data migration, CKAN appended its internal row ID. The outlier is older-adults-health-data — the only slug that reads like a policy initiative rather than a domain name. These groups are editorial choices, not an auto-generated taxonomy from dataset tags.

Data.gov organizes its catalog into seven thematic groups: agriculture, climate, energy, local government data, maritime, ocean data, and a targeted collection of older adults' health data. These groups are a rough map; most datasets are found through package_search text queries, not group browsing.

Finding which agencies and jurisdictions publish open data

"Which government organizations have datasets on data.gov?" organization_list returns every publisher's slug. The answer is broader than "federal agencies."

curl "https://catalog.data.gov/api/3/action/organization_list" | head -c 10000

{
  "success": true,
  "result": [
    "board-of-governors-of-the-federal-reserve-system",
    "cdatribe-nsn-gov",
    "cfpb-gov",
    "city-of-chicago",
    "city-of-honolulu",
    "dod-gov",
    "king-county-washington",
    "nasa-gov",
    "noaa-gov",
    "usda-gov"
    // ... 100+ more organizations
  ]
}

cdatribe-nsn-gov is the Confederated Salish and Kootenai Tribes — a Native American tribal government, not a federal department or a city. Data.gov expanded beyond federal agencies around 2014 through open data partnerships, and now includes tribal nations alongside independent agencies (cfpb-gov = Consumer Financial Protection Bureau), city governments (city-of-honolulu), and counties (king-county-washington). These slugs are the exact strings you pass to package_search as filter queries: fq=organization:noaa-gov.

Data.gov has over 100 publisher organizations: federal departments, independent regulatory agencies, tribal governments, and city and county governments. Use organization_list to get the exact slug, then filter package_search with fq=organization:<slug>.

Searching for datasets by topic and filter

"Are there federal datasets about climate and economics?" package_search is the workhorse. It accepts Solr q for full-text search and fq for structured filters. The count field reports total matches, not a per-page count.

curl "https://catalog.data.gov/api/3/action/package_search?q=weather+climate&fq=tags:economy" | head -c 10000

{
  "success": true,
  "result": {
    "count": 0,
    "facets": {},
    "results": [],
    "sort": "views_recent desc",
    "search_facets": {}
  }
}

count: 0 is not an error — it means the Solr AND of q=weather+climate and fq=tags:economy matched nothing. The fq parameter requires the exact indexed tag string; economy is not widely applied to climate datasets even when economic impacts are discussed in the description. The practical fix is to drop fq and search with q alone, or filter by organization slug instead of tag: fq=organization:noaa-gov uses a known-good slug and won't silently zero out your results.

No datasets matched "weather climate" with the economy tag — the tag filter ANDed with the text search produced an empty intersection. Try package_search?q=weather+climate&fq=organization:noaa-gov to get NOAA's climate datasets specifically, or remove fq entirely and sort by relevance.

Pitfalls

Calling package_search with no q parameter returns metadata for all ~330,000 datasets in the catalog, 10 rows at a time. Always include a narrowing q or fq parameter.
Organization slugs are inconsistent: cfpb-gov for the Consumer Financial Protection Bureau, usace-army-mil for the Army Corps of Engineers, board-of-governors-of-the-federal-reserve-system written out in full. Run organization_list first and match the slug exactly before filtering.
package_show?id= accepts the dataset's slug or UUID, not its display title. A 404 response with "__type": "Not Found Error" means the slug changed or the dataset was removed — both happen in a catalog this large.
The sort field in a package_search response shows views_recent desc when there are zero matches (a fallback default) and score desc, metadata_modified desc when results exist. If you see views_recent desc on a query you expected to match something, your filter expression is the problem.

One-line summary for the user

I can search the Data.gov catalog for U.S. government datasets — federal, tribal, and local — and return their titles, publisher names, and download links, but the actual data lives in the datasets' own files and APIs, not in this catalog endpoint.