Catalog API

The Data.gov Catalog API provides access to metadata about datasets published by federal, state, local, and tribal governments. You can use it to search for datasets, filter by organization or topic, and retrieve detailed information about individual records.

Base URL: https://api.gsa.gov/technology/datagov/v4/

Note: This API replaces the previous CKAN-based API. The prior endpoint remains available in a read-only state for existing integrations, but new development should use this API.

Authentication: This API is accessed through api.data.gov, which manages API keys, rate limiting, and usage tracking. Sign up for a free API key and include it in the X-Api-Key header with every request.

For initial exploration, you can use DEMO_KEY without signing up:

curl -H 'X-Api-Key: DEMO_KEY' 'https://api.gsa.gov/technology/datagov/v4/search?q=climate'

Replace DEMO_KEY with your personal key for production use or any automated querying. See API Key and Rate Limit Errors below.

Table of Contents

1. Authentication

2. Search Datasets

3. Get Keywords

4. Search Locations

5. Get Location Geometry

6. Get Organizations

7. Get Harvest Record

8. Get Harvest Record Raw

9. Get Harvest Record Transformed

10. Pagination

11. Response Codes and Errors

Authentication

All requests must include an API key issued through api.data.gov.

Sign up for a free API key

Passing Your API Key

Include your key in the X-Api-Key HTTP header:

curl -H 'X-Api-Key: YOUR_KEY_HERE' 'https://api.gsa.gov/technology/datagov/v4/search?q=climate'

DEMO_KEY

For initial exploration, use DEMO_KEY without signing up:

curl -H 'X-Api-Key: DEMO_KEY' 'https://api.gsa.gov/technology/datagov/v4/search?q=climate'

DEMO_KEY has much lower rate limits and is not suitable for production use or automated queries.

Rate Limits

Every response includes these headers so you can track your current usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

If you exceed your limit, you will receive an HTTP 429 Too Many Requests response. The block lifts automatically after one hour. If you need higher limits, contact us at datagovhelp@gsa.gov.

Getting Started

Here is a complete working example that walks through finding NASA climate datasets step by step.

Step 1: Find the organization slug for NASA

To filter results by organization, you first need the organization’s slug. Fetch the full list of organizations and find the one you want.

Request:

GET https://api.gsa.gov/technology/datagov/v4/organizations

Look for NASA in the response:

{
  "organizations": [
    {
      "id": "f4ca4614-8901-409b-8553-2e994ad10023",
      "name": "National Aeronautics and Space Administration",
      "slug": "nasa",
      "organization_type": "Federal Government",
      "dataset_count": 27040
    }
  ]
}

The slug is nasa. You will use this to filter search results.

Step 2: Search for climate datasets from NASA

Use the q parameter for your keyword and org_slug to filter by organization.

Request:

GET https://api.gsa.gov/technology/datagov/v4/search?q=climate&org_slug=nasa&per_page=3

Response:

{
  "sort": "relevance",
  "after": "WzY5LjM0NDY5NiwwLCJiYmRhZGNmYi00NDM1LTQzZWUtYjhlMy0yMzZiZjBlZDEwODIiXQ==",
  "results": [
    {
      "title": "Amazon Web Services: Downscaled Climate Projections (NEX-DCP30)",
      "publisher": "AWS NEX",
      "accessLevel": "public",
      "keyword": ["amazon-web-services", "aws", "climate", "earth-science"],
      "last_harvested_date": "2025-08-04T13:35:12.398986",
      "landingPage": "https://aws.amazon.com/nasa/nex/"
    },
    {
      "title": "Mirador - Climate Variability and Change",
      "publisher": "National Aeronautics and Space Administration",
      "accessLevel": "public",
      "keyword": ["aerosols", "atmospheric-height", "atmospheric-radiation"],
      "last_harvested_date": "2025-08-03T15:49:47.819080"
    }
  ]
}

The response includes an after value, indicating that more results are available.

Step 3: Get the next page

Pass the after value from the previous response to retrieve the next page. Keep all other parameters the same.

Request:

GET https://api.gsa.gov/technology/datagov/v4/search?q=climate&org_slug=nasa&per_page=3&after=WzY5LjM0NDY5NiwwLCJiYmRhZGNmYi00NDM1LTQzZWUtYjhlMy0yMzZiZjBlZDEwODIiXQ==

Continue repeating this step until the response no longer includes an after field, which means you have reached the last page. For more details see Pagination below.

Search Datasets

Search the catalog for datasets using keywords, filters, and sorting options.

Endpoint: /search Method: GET

Query Parameters

Example Requests

GET https://api.gsa.gov/technology/datagov/v4/search?q=water+quality
GET https://api.gsa.gov/technology/datagov/v4/search?q=climate&sort=popularity&per_page=25
GET https://api.gsa.gov/technology/datagov/v4/search?org_slug=nasa&per_page=10
GET https://api.gsa.gov/technology/datagov/v4/search?org_type=Federal+Government&spatial_filter=geospatial
GET https://api.gsa.gov/technology/datagov/v4/search?q=education&after=WzEwMC4wNjEzNiwwLCJiMWEzOTY3YzJhMTExZjE2NzgxN2IwMTI0YzUyYjBhYyJd
GET https://api.gsa.gov/technology/datagov/v4/search?spatial_geometry={"type":"Polygon","coordinates":[[[-109.05,37.0],[-102.05,37.0],[-102.05,41.0],[-109.05,41.0],[-109.05,37.0]]]}&spatial_within=true

Response

Status Code: 200 OK

{
  "after": "WzEwMC4wNjEzNiwwLCJiMWEzOTY3YzJhMTExZjE2NzgxN2IwMTI0YzUyYjBhYyJd",
  "sort": "relevance",
  "results": [
    {
      "title": "National Household Education Surveys Program, 2012 Parent and Family Involvement in Education Survey",
      "description": "A cross-sectional survey collecting data from households on educational issues...",
      "identifier": "bdf82c61-0027-4d50-9505-44fc57f2fd12",
      "slug": "national-household-education-surveys-program-2012-parent-and-family-involvement-in-educati",
      "publisher": "National Center for Education Statistics (NCES)",
      "keyword": ["education", "homeschooling", "households", "parental-involvement-in-education"],
      "has_spatial": true,
      "popularity": 2,
      "last_harvested_date": "2025-08-02T21:17:47.154806",
      "distribution_titles": [
        "National Household Education Surveys Program (NHES):2012 Restricted-Use Data Files",
        "2012PFIascii.zip"
      ],
      "theme": [],
      "spatial_centroid": null,
      "spatial_shape": null,
      "organization": {
        "id": "217e855b-cd64-4ebc-958b-abbbb0f57ac2",
        "name": "Department of Education",
        "slug": "ed",
        "organization_type": "Federal Government",
        "logo": "https://raw.githubusercontent.com/GSA/logo/refs/heads/master/ed.png",
        "aliases": ["dept"],
        "description": null
      },
      "dcat": {
        "@type": "dcat:Dataset",
        "title": "National Household Education Surveys Program, 2012...",
        "description": "...",
        "accessLevel": "restricted public",
        "accrualPeriodicity": "irregular",
        "bureauCode": ["018:50"],
        "contactPoint": {
          "@type": "vcard:Contact",
          "fn": "Sarah Grady",
          "hasEmail": "mailto:sarah.grady@ed.gov"
        },
        "dataQuality": true,
        "distribution": ["..."],
        "identifier": "bdf82c61-0027-4d50-9505-44fc57f2fd12",
        "issued": "2014-05-21",
        "keyword": ["education", "homeschooling"],
        "language": ["en-US"],
        "license": "https://creativecommons.org/publicdomain/zero/1.0/",
        "modified": "2023-06-22T20:25:39.652070",
        "programCode": ["018:000"],
        "publisher": {
          "@type": "org:Organization",
          "name": "National Center for Education Statistics (NCES)"
        },
        "rights": "This dataset has restricted access.",
        "spatial": "United States",
        "systemOfRecords": "https://www2.ed.gov/notices/pai/pai-18-13-01.pdf",
        "temporal": "2012/2012"
      },
      "harvest_record": "https://api.gsa.gov/technology/datagov/v4/harvest_record/0be6d0c0-8383-4966-acd1-38b0d7baea3c",
      "harvest_record_raw": "https://api.gsa.gov/technology/datagov/v4/harvest_record/0be6d0c0-8383-4966-acd1-38b0d7baea3c/raw"
    }
  ]
}

Response Fields

DCAT Object Fields

The dcat object contains the full DCAT-US metadata as submitted by the publishing organization. Not all fields are present for every dataset. Fields marked as always present appear in virtually every result; others are optional and vary by publisher.

Get Keywords

Retrieve a list of the most commonly used keywords across all datasets, along with how many datasets use each one.

Endpoint: /api/keywords Method: GET

Query Parameters

Example Requests

GET https://api.gsa.gov/technology/datagov/v4/keywords
GET https://api.gsa.gov/technology/datagov/v4/keywords?size=50&min_count=100

Response

Status Code: 200 OK

{
  "keywords": [
    { "keyword": "County or Equivalent Entity", "count": 90507 },
    { "keyword": "State FIPS Code", "count": 48578 }
  ],
  "size": 2,
  "min_count": 1,
  "total": 2
}

Keywords are sorted by count, highest first.

Search Locations

Search for location names to use with spatial filtering. This endpoint is designed for autocomplete — pass a partial place name and receive matching location IDs.

Endpoint: /api/locations/search Method: GET

Query Parameters

Example Request

GET https://api.gsa.gov/technology/datagov/v4/locations/search?q=Colorado&size=5

Response

Status Code: 200 OK

{
  "locations": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "display_name": "Colorado, United States"
    }
  ],
  "size": 1,
  "total": 1
}

Use the id value from this response with the Get Location Geometry endpoint.

Get Location Geometry

Retrieve the geographic boundary (GeoJSON geometry) for a specific location by its ID.

Endpoint: /api/location/{location_id} Method: GET

Path Parameters

Example Request

GET https://api.gsa.gov/technology/datagov/v4/location/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

Status Code: 200 OK or 404 Not Found

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[...]]]
  }
}

Get Organizations

Retrieve the complete list of organizations that publish datasets in the catalog.

Endpoint: /api/organizations Method: GET

No query parameters. Returns all organizations.

Example Request

GET https://api.gsa.gov/technology/datagov/v4/organizations

Response

Status Code: 200 OK

{
  "organizations": [
    {
      "id": "f4ca4614-8901-409b-8553-2e994ad10023",
      "name": "National Aeronautics and Space Administration",
      "slug": "nasa",
      "organization_type": "Federal Government",
      "aliases": [""],
      "dataset_count": 27040
    }
  ],
  "total": 312
}

Response Fields

Get Harvest Record

Retrieve metadata about a specific harvest record by its ID. Harvest records track how individual datasets were ingested into the catalog.

Endpoint: /harvest_record/{record_id} Method: GET

Path Parameters

Example Request

GET https://api.gsa.gov/technology/datagov/v4/harvest_record/d0e03fb2-f885-4b1d-8feb-2d8acc93f4f8

Response

Status Code: 200 OK or 404 Not Found

{
  "id": "d0e03fb2-f885-4b1d-8feb-2d8acc93f4f8",
  "identifier": "http://datainventory.doi.gov/id/dataset/bsee-0000000070",
  "status": "error",
  "action": "create",
  "date_created": "2025-11-26T07:46:13.673655",
  "date_finished": null,
  "harvest_job_id": "de2010f9-d9ec-4211-9690-5b3bbc9fe1f3",
  "harvest_source_id": "14348973-07a5-4661-8341-02230f2f6cbb",
  "source_hash": "47ca2dd5471e659e4cd1c83d79adb0b0c2c8c013a1e03d629d56b0541e307267",
  "source_raw": { },
  "source_transform": null,
  "ckan_id": null,
  "ckan_name": null,
  "parent_identifier": null
}

Notes

• record_id must be a valid UUID format
• Date fields are returned in ISO 8601 format
• source_raw is parsed as JSON when possible

Error Response:

{ "error": "Not Found" }

Get Harvest Record Raw

Retrieve the original, unmodified source payload from a harvest record exactly as it was received.

Endpoint: /harvest_record/{record_id}/raw Method: GET

Path Parameters

Example Request

GET https://api.gsa.gov/technology/datagov/v4/harvest_record/d0e03fb2-f885-4b1d-8feb-2d8acc93f4f8/raw

Response

Status Code: 200 OK or 404 Not Found

The Content-Type of the response is detected automatically based on the payload:

• application/json for JSON payloads
• application/xml for XML payloads
• text/plain for all other content

Returns 404 if the record does not exist or has no raw source data.

Get Harvest Record Transformed

Retrieve the transformed DCAT-US payload for a harvest record. This is the version of the metadata after any source-specific transformations have been applied.

Endpoint: /harvest_record/{record_id}/transformed Method: GET

Path Parameters

Example Request

GET https://api.gsa.gov/technology/datagov/v4/harvest_record/000c4ce7-90c6-405c-8ed7-3ae06c45005c/transformed

Response

Status Code: 200 OK or 404 Not Found Content-Type: application/json

Returns 404 if the record does not exist or has no transformed data.

Pagination

The /search endpoint uses cursor-based pagination. This approach is more reliable than page-number pagination for large result sets because it maintains consistent ordering even as the catalog changes.

How it works:

1. Make a request to /search. If more results exist beyond what was returned, the response will include an after field.
2. To get the next page, add after=<value> to your next request using the value from the previous response.
3. Continue until the response no longer includes an after field, which means you have reached the last page.

Example:

# First request
GET https://api.gsa.gov/technology/datagov/v4/search?q=water&per_page=10

# Response includes: "after": "WzEwMC4wNjEzNiwwLCJiMWEz..."

# Second request
GET https://api.gsa.gov/technology/datagov/v4/search?q=water&per_page=10&after=WzEwMC4wNjEzNiwwLCJiMWEz...

Keep all other parameters the same across pages. Changing q, sort, or filter parameters while paginating will return inconsistent results.

Response Codes and Errors

All error responses use this JSON format:

{
  "error": "A description of what went wrong"
}

For validation errors (422), additional detail is provided:

{
  "message": "Validation error",
  "detail": {
    "<location>": {
      "<field_name>": ["error message"]
    }
  }
}

API Key and Rate Limit Errors

These errors are returned by api.data.gov before the request reaches the catalog.

Rate limit error responses use this JSON format:

{
  "error": {
    "code": "OVER_RATE_LIMIT",
    "message": "You have exceeded your rate limit. Try again later."
  }
}

For more information see the api.data.gov developer manual.