/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
Query parameters
Name | Type | Description |
---|---|---|
key |
string | Your API key. See the section on authentication for details. |
date |
string | See below for allowable values. |
variable.dcids |
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 |
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 |
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
or2010-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:
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.)
In these cases, do the following:
- In the Statistical Variable Explorer, click on an example place to link to the variable’s page in the Knowledge Graph Browser.
- 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.
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"
},
...
}
}
Page last updated: November 27, 2024 • Send feedback about this page