/v1/observations/point
Retrieve a specific observation at a set date from a variable for an entity from the preferred facet. If no date is provided, the latest observation is returned.
To retrieve the entire series of observations, use /v1/observations/series
For querying multiple variables or entities, see the bulk version of this endpoint.
Request
GET Request
https://api.datacommons.org/v1/observations/point/{ENTITY_DCID}/{VARIABLE_DCID}?key={your_api_key}
Path Parameters
Name | Description |
---|---|
VARIABLE_DCID |
DCID of the variable to query a value for. |
ENTITY_DCID |
DCID of the entity that the variable describes. |
Query Parameters
Name | Type | Description |
---|---|---|
key |
string | Your API key. See the page on authentication for a demo key, as well as instructions on how to get your own key. |
date |
type | Datetime of measurement of the value requested in ISO 8601 format. To see the dates available, look up the variable in the Statistical Variable Explorer. If date is not provided, the latest available datapoint is returned. |
Response
The response looks like:
{
"date": "YYYY-MM-DD",
"value": 1234,
"facet": {...},
}
Response fields
Name | Type | Description |
---|---|---|
value | type | Value of the variable queried for the queried entity. |
date | string | Datetime the value returned was measured. |
facet | dict | Metadata on the facet the data came from. Can include things like provenance, measurement method, and units. |
Examples
Example 1: Get latest observation for given variable and entity
Get the population count (DCID: Count_Person
) for the United States of America (DCID: country/USA
). Note that the latest entry available will be returned.
Request:
$ curl --request GET --url \
'https://api.datacommons.org/v1/observations/point/country/USA/Count_Person?key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'
Response:
{
"date": "2020",
"value": 331449281,
"facet": {
"importName": "USDecennialCensus_RedistrictingRelease",
"provenanceUrl": "https://www.census.gov/programs-surveys/decennial-census/about/rdo/summary-files.html",
"measurementMethod": "USDecennialCensus"
}
}
Example 2: Get single observation at a specific date, for given variable and entity
Get the annual electricity generation (DCID: Annual_Generation_Electricity
) of California (DCID: geoId/06
) in 2018.
Request:
$ curl --request GET --url \
'https://api.datacommons.org/v1/observations/point/geoId/06/Annual_Generation_Electricity?date=2018&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI'
Response:
{
{
"date": "2018",
"value": 195465638180,
"facet": {
"importName": "EIA_Electricity",
"provenanceUrl": "https://www.eia.gov/opendata/qb.php?category=0",
"unit": "KilowattHour"
}
}
}
Page last updated: November 27, 2024 • Send feedback about this page