Google Data Commons API

Base URL

https://api.datacommons.org

Authentication

API key required. Obtain through https://apikeys.datacommons.org/.

Pass as query parameter: &key=YOUR_KEY

Or as header: X-API-Key: YOUR_KEY

All access to the base Data Commons requires a key. Custom Data Commons instances have their own base URL and do not accept the base-service key.

Key Endpoints

1. Get Statistical Value (single observation)

GET /v2/observation

Example:

https://api.datacommons.org/v2/observation?key=YOUR_KEY&entity.dcids=country/USA&variable.dcids=Count_Person&date=LATEST&select=entity&select=variable&select=date&select=value

2. Get Statistical Time Series

GET /v2/observation

Use same endpoint but omit date parameter (or set date='') to get the full time series.

Example (population time series for USA):

https://api.datacommons.org/v2/observation?key=YOUR_KEY&entity.dcids=country/USA&variable.dcids=Count_Person&select=entity&select=variable&select=date&select=value

3. Node Info (property values of an entity)

GET /v2/node

Example (get properties of California):

https://api.datacommons.org/v2/node?key=YOUR_KEY&nodes=geoId/06&property=->*

Example (get name of a place):

https://api.datacommons.org/v2/node?key=YOUR_KEY&nodes=geoId/06&property=->name

4. Supported V2 operations

V2 provides /observation, /node and /resolve, each supporting GET and POST. It does not expose /v2/sparql. For graph queries outside these operations, consult the documented Data Commons BigQuery access.

5. Resolve Entities (map names/coords to DCIDs)

GET /v2/resolve

Example (resolve by name):

https://api.datacommons.org/v2/resolve?key=YOUR_KEY&nodes=California&property=<-description->dcid

6. Search for statistical variables

Use /v2/resolve with resolver=indicator and nodes containing a natural-language description. Resolve returns candidate DCIDs and match metadata; inspect the candidates and variable definitions before retrieving observations.

# Illustrative authenticated request
curl --fail-with-body --get 'https://api.datacommons.org/v2/resolve' \
  -H "X-API-Key: $DATACOMMONS_API_KEY" \
  --data-urlencode 'nodes=unemployment rate' --data-urlencode 'resolver=indicator'

Common DCIDs

Places

Statistical Variables

Response Format

Observation response

{
  "byVariable": {
    "Count_Person": {
      "byEntity": {
        "country/USA": {
          "orderedFacets": [
            {
              "facetId": "2176550201",
              "observations": [
                {
                  "date": "2020",
                  "value": 331449281
                },
                {
                  "date": "2021",
                  "value": 331893745
                }
              ]
            }
          ]
        }
      }
    }
  },
  "facets": {
    "2176550201": {
      "importName": "CensusACS5YearSurvey",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS5yrSurvey"
    }
  }
}

Node response

{
  "data": {
    "geoId/06": {
      "arcs": {
        "name": {
          "nodes": [
            {
              "value": "California"
            }
          ]
        }
      }
    }
  }
}

Resolve and pagination

Resolve responses contain entities, each with the input node and a list of candidates. For any paginated V2 response, repeat the same request with its nextToken until no continuation token remains. Keep facet provenance with observations; dates, units and measurement methods can differ across facets.

Rate Limits

• Base-service requests require an API key; quota depends on the issued key.
• With API key: not formally published, but generally generous for normal use.
• Implement client-side throttling (1-2 requests/second recommended).
• Bulk data available via the Data Commons data download for large-scale analysis.

Notes

• The V2 API (paths starting with /v2/) is the current recommended version.
• Older V1 endpoints (/v1/bulk/observations/series, /stat/value, etc.) still work but are deprecated.
• DCID = Data Commons Identifier. Every entity, statistical variable, and concept has a unique DCID.
• The knowledge graph includes data from US Census, World Bank, CDC, BLS, FBI, and many other sources.

Official contracts: V2, resolve.