/v2/observation

The Observation API fetches statistical observations. An observation is associated with an entity and variable at a particular date: for example, “population of USA in 2020”, “GDP of California in 2010”, and so on.

Request

https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=DATE_EXPRESSION&variable.dcids=DCID_LIST&entity.dcids|expression=DCID_LIST_OR_RELATION_EXPRESSION&filter.facet_ids=FACET_ID_LIST&filter.domains=DOMAIN_NAME_LIST&select=variable&select=entity[&select=value][&select=date]
URL: https://api.datacommons.org/v2/observation Header: X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI JSON data: { "date": "DATE_EXPRESSION", "variable": { "dcids": [ "VARIABLE_DCID_1", "VARIABLE_DCID_2", ... ] }, "entity": { "dcids":[ "ENTITY_DCID_1", "ENTITY_DCID_2", ... ] "expression": "ENTITY_EXPRESSION" }, "filter": { "facet_ids": [ "FACET_ID_1", "FACET_ID_2", ... ] "domains": [ "DOMAIN_NAME_1", "DOMAIN_NAME_2", ... ] }, "select": ["date", "entity", "variable", "value"] }

Query parameters

Name Type Description
key
Required		 string Your API key. See the section on authentication for details.
date
Required		 string See below for allowable values.
variable.dcids
Required		 list of strings List of DCIDs for the statistical variable to be queried.
entity.dcids list of strings Comma-separated list of DCIDs of entities to query. One of entity.dcids or entity.expression is required. Multiple entity.dcids parameters are allowed.
entity.expression string Relation expression that represents the entities to query. One of entity.dcids or entity.expression is required.
select
Required		 string literal select=variable and select=entity are required. If specifed without select=date and select=value, no observations are returned. You can use this to first check the existence of variable-entity pairs in the data and fetch all the variables that have data for given entities.
select
Optional		 string literal If used, you must specify both select=date and select=value. Returns actual observations, with the date and value for each variable and entity queried.
filter.facet_domains
Optional		 list of strings Comma-separated list of domain names. You can use this to filter results by provenance.
filter.facet_ids
Optional		 list of strings Comma-separated list of existing facet IDs that you have obtained from previous observation API calls. You can use this to filter results by several properties, including dataset name, provenance, measurement method, etc.

Date-time string formats

Here are the possible values for specifying dates/times:

  • LATEST: Fetch the latest observations only.
  • DATE_STRING: Fetch observations matching the specified date(s) and time(s). The value must be in the ISO-8601 format used by the target variable; for example, 2020 or 2010-12. To look up the format of a statistical variable, see below.
  • "": Return observations for all dates.

Find the date format for a statistical variable

Statistical variable dates are defined as yearly, monthly, weekly, or daily. For most variables, you can find out the correct date format by searching for the variable in the Statistical Variable Explorer and looking for the Date range. For example, for the variable Gini Index of Economic Activity, the date-time format is yearly, i.e. in YYYY format:

date time example 1

For other cases, you may need to drill down further to a timeline graph to view specific observations. For example, Mean Wind Direction, is measured at the sub-daily level, but the frequency is not clear (hourly or every two hours, etc.)

date time example 2

In these cases, do the following:

  1. In the Statistical Variable Explorer, click on an example place to link to the variable’s page in the Knowledge Graph Browser.
  2. Scroll to the Observations section and click Show Table to get a list of observations.

For example, in the case of Mean Wind Direction for Ibrahimpur, India, the observations table shows that the variable is measured every four hours, starting at midnight.

date time example 3

Response

Without select=date and select=value specified, the response looks like:

{
  "byVariable": {
    "VARIABLE_DCID_1": {
      "byEntity": {
        "ENTITY_DCID_1": {},
        "ENTITY_DCID_2": {},
        ...
      }
    "VARIABLE_DCID_2": {
      ...
  }
}

With select=date and select=value specified, the response looks like:

{
  "byVariable": {
    "VARIABLE_DCID_1": {
      "byEntity": {
        "ENTITY_DCID_1": {
          "orderedFacets": [
            {
              "facetId": "FACET_ID",
              "earliestDate" : "DATE_STRING", 
              "latestDate" : "DATE_STRING", 
              "obsCount" : "NUMBER_OF_OBSERVATIONS",
              "observations": [
                {
                  "date": "OBSERVATION_DATE",
                  "value": "OBSERVATION_VALUE"
                },
                ...
              ]
            },
            ...
        },
        ...
      },
      ...
    }
  "facets" {
    "FACET_ID": {
      "importName": "...",
      "provenanceUrl": "...",
      "measurementMethod": "...",
      "observationPeriod": "..."
    },
    ...
  }

Response fields

Name Type Description
orderedFacets list of objects Metadata about the observations returned, keyed first by variable, and then by entity, such as the date range, the number of observations included in the facet etc.
observations list of objects Date and value pairs for the observations made in the time period
facets object Various properties of reported facets, where available, including the provenance of the data, etc.

Examples

Example 1: Get the latest observations for a single entity

In this example, we get all the latest observations for the variable Count_Person, specifying date=LATEST, and selecting the entity, the U.S.A. by its DCID using entity.dcids. Note that in the response, there are multiple facets returned, because this variable (representing a simple population count) is used in several datasets.

Parameters:

date: "LATEST"
variable.dcids: "Count_Person"
entity.dcids: "country/USA"
select: "entity"
select: "variable"
select: "value"
select: "date"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=LATEST&variable.dcids=Count_Person&entity.dcids=country%2FUSA&select=entity&select=variable&select=value&select=date'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/observation \
  -d '{"date": "LATEST", "variable": { "dcids": ["Count_Person"] }, "entity": { "dcids": ["country/USA"] }, "select": ["entity", "variable", "value", "date"] }'

Response:

{
{
   "byVariable" : {
      "Count_Person" : {
         "byEntity" : {
            "country/USA" : {
               "orderedFacets" : [
                  {
                     "earliestDate" : "2024",
                     "facetId" : "2176550201",
                     "latestDate" : "2024",
                     "obsCount" : 1,
                     "observations" : [
                        {
                           "date" : "2024",
                           "value" : 340110988
                        }
                     ]
                  },
                  {
                     "earliestDate" : "2023",
                     "facetId" : "2645850372",
                     "latestDate" : "2023",
                     "obsCount" : 1,
                     "observations" : [
                        {
                           "date" : "2023",
                           "value" : 335642425
                        }
                     ]
                  }
               ]
            }
         }
      }
   },
  "facets": {
    ...
    "2176550201" : {
      "importName" : "USCensusPEP_Annual_Population",
      "measurementMethod" : "CensusPEPSurvey",
      "observationPeriod" : "P1Y",
      "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
    },
    ...
   "2645850372" : {
         "importName" : "CensusACS5YearSurvey_AggCountry",
         "isDcAggregate" : true,
         "measurementMethod" : "CensusACS5yrSurvey",
         "provenanceUrl" : "https://www.census.gov/"
      },
    ...
  }
}

Example 2: Get the observations at a particular date for given entities

This gets observations for the populations of the U.S.A. and California in 2015. It uses the same parameters as the previous response, with an additional entity, and a specific date.

Parameters:

date: "2015"
variable.dcids: "Count_Person"
entity.dcids: "country/USA"
entity.dcids: "geoId/06"
select: "date"
select: "entity"
select: "value"
select: "variable"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=2015&variable.dcids=Count_Person&entity.dcids=country%2FUSA&entity.dcids=geoId%2F06&select=date&select=entity&select=value&select=variable'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/observation \
  -d '{"date": "2015", "variable": { "dcids": ["Count_Person"] }, "entity": { "dcids": ["country/USA", "geoId/06"] }, "select": ["entity", "variable", "value", "date"] }'

Response:

{
  "byVariable": {
    "Count_Person": {
      "byEntity": {
        "country/USA": {
          "orderedFacets": [
             {
              "earliestDate" : "2015",
              "facetId" : "2176550201",
              "latestDate" : "2015",
              "obsCount" : 1,
              "observations" : [
                {
                  "date" : "2015",
                  "value" : 320738994
                }
              ]
            },
            ...
          ]
        },
        "geoId/06": {
          "orderedFacets": [
            "earliestDate" : "2015",
            "facetId" : "2176550201",
            "latestDate" : "2015",
            "obsCount" : 1,
            "observations" : [
              {
                "date" : "2015",
                "value" : 38904296
              }
            ]
          },
          ...
          ]
        }
      }
    }
  },
  "facets" {
      "2176550201" : {
         "importName" : "USCensusPEP_Annual_Population",
         "measurementMethod" : "CensusPEPSurvey",
         "observationPeriod" : "P1Y",
         "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
      },
    ...
  }
}

Example 4: Get the latest population observations for all California counties

In this example, we use the chained expression (+) to specify “all contained places in California (dcid: geoId/06) of type County”. Then we specify the select fields to fetch the latest observations for the variable (Count_Person) and entity (all counties in California).

Parameters:

date: "LATEST"
variable.dcids: "Count_Person"
entity.expression: "geoId/06<-containedInPlace+{typeOf:County}"
select: "date"
select: "entity"
select: "value"
select: "variable"

GET Request:

curl --request GET --url \
'https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=2015&date=LATEST&variable.dcids=Count_Person&entity.expression=geoId%2F06%3C-containedInPlace%2B%7BtypeOf%3ACounty%7D&select=date&select=entity&select=value&select=variable'

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
  https://api.datacommons.org/v2/observation \
  -d '{"date": "LATEST", "variable": { "dcids": ["Count_Person"] }, "entity": { "expression": "geoId/06<-containedInPlace+{typeOf:County}"}, "select": ["entity", "variable", "value", "date"] }'

Response:

{
  "byVariable": {
    "Count_Person": {
      "byEntity": {
        "geoId/06003": {
          "orderedFacets": [
            {
              "facetId": "2176550201",
              "observations": [
                {
                  "date": "2021",
                  "value": 1235
                }
              ]
            },
            ...
          ]
        },
        "geoId/06009": {
          "orderedFacets": [
            {
              "facetId": "2176550201",
              "observations": [
                {
                  "date": "2021",
                  "value": 46221
                }
              ]
            },
            ...
          ]
        },
        ...
      }
    }
  },
  "facets": {
    "2176550201": {
      "importName": "USCensusPEP_Annual_Population",
      "measurementMethod" : "CensusPEPSurvey",
      "observationPeriod" : "P1Y",
      "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
    },
    ...
  }
}

Example 5: Get the latest observations for a single entity, filtering by provenance

This example is the same as example #1, except it filters for a single data source, namely the U.S. government census, represented by its domain name, www2.census.gov.

Parameters:

date: "LATEST"
variable.dcids: "Count_Person"
entity.dcids: "country/USA"
filter.domains: "www2.census.gov"
select: "entity"
select: "variable"
select: "value"
select: "date"

GET Request:

https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=LATEST&variable.dcids=Count_Person&entity.dcids=country%2FUSA&filter.domains=www2.census.gov&select=entity&select=variable&select=value&select=date

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \  
https://api.datacommons.org/v2/observation  \ 
-d '{"date": "LATEST", "variable": { "dcids": ["Count_Person"] }, "entity": { "dcids": ["country/USA"] }, "select": ["entity", "variable", "value", "date"], "filter": {"domains": ["www2.census.gov"]}}'

Response:

{
   "byVariable" : {
      "Count_Person" : {
         "byEntity" : {
            "country/USA" : {
               "orderedFacets" : [
                  {
                     "earliestDate" : "2024",
                     "facetId" : "2176550201",
                     "latestDate" : "2024",
                     "obsCount" : 1,
                     "observations" : [
                        {
                           "date" : "2024",
                           "value" : 340110988
                        }
                     ]
                  }
               ]
            }
         }
      }
   },
   "facets" : {
      "2176550201" : {
         "importName" : "USCensusPEP_Annual_Population",
         "measurementMethod" : "CensusPEPSurvey",
         "observationPeriod" : "P1Y",
         "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
      }
   }
}

Example 6: Get the latest observations for a single entity, filtering for specific dataset

This example gets the latest population count of Brazil. It filters for a single dataset from the World Bank, using the facet ID 3981252704.

Parameters:

date: "LATEST"
variable.dcids: "Count_Person"
entity.dcids: "country/BRA"
filter.facet_ids: "3981252704"
select: "entity"
select: "variable"
select: "value"
select: "date"

GET Request:

https://api.datacommons.org/v2/observation?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI&date=LATEST&variable.dcids=Count_Person&entity.dcids=country%2FBRA&filter.facet_ids=3981252704&select=entity&select=variable&select=value&select=date

POST Request:

curl -X POST -H "X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI" \
https://api.datacommons.org/v2/observation  \ 
-d '{"date": "LATEST", "variable": { "dcids": ["Count_Person"] }, "entity": { "dcids": ["country/BRA"] }, "select": ["entity", "variable", "value", "date"], "filter": {"facet_ids": ["3981252704"]} }'

Response:

{
   "byVariable" : {
      "Count_Person" : {
         "byEntity" : {
            "country/BRA" : {
               "orderedFacets" : [
                  {
                     "earliestDate" : "2023",
                     "facetId" : "3981252704",
                     "latestDate" : "2023",
                     "obsCount" : 1,
                     "observations" : [
                        {
                           "date" : "2023",
                           "value" : 211140729
                        }
                     ]
                  }
               ]
            }
         }
      }
   },
   "facets" : {
      "3981252704" : {
         "importName" : "WorldDevelopmentIndicators",
         "observationPeriod" : "P1Y",
         "provenanceUrl" : "https://datacatalog.worldbank.org/dataset/world-development-indicators/"
      }
   }
}

Page last updated: March 11, 2025 • Send feedback about this page