/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&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" }, "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.

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 observation for given entities

Specify date=LATEST to get the latest observations and values. In this example, we select the entity by its DCID using entity.dcids.

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" : "2022",
              "facetId" : "2176550201",
              "latestDate" : "2022",
              "obsCount" : 1,
              "observations" : [
                {
                  "date" : "2022",
                  "value" : 333287557
                }
              ]
            },
            {
              "earliestDate" : "2022",
              "facetId" : "1273233945",
              "latestDate" : "2022",
              "obsCount" : 1,
              "observations" : [
               {
                  "date" : "2022",
                  "value" : 334369975
                }
                ]
            },
            ...
          ]
        }
      }
    }
  },
  "facets": {
    "2176550201" : {
      "importName" : "USCensusPEP_Annual_Population",
      "measurementMethod" : "CensusPEPSurvey",
      "observationPeriod" : "P1Y",
      "provenanceUrl" : "https://www2.census.gov/programs-surveys/popest/tables"
    },
    "1273233945": {
      "importName": "CensusACS5YearSurvey_AggCountry",
      "provenanceUrl": "https://www.census.gov/",
      "measurementMethod": "CensusACS5yrSurvey"
    },
    ...
  }
}

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

This queries for observations in 2015 for the variable Count_Person for two specified entities: country/USA and geoId/06.

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 3: Get the latest 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 request actual observations with date and value for each 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"
    },
    ...
  }
}