/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.

info See Also:
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 Required	DCID of the variable to query a value for.
ENTITY_DCID Required	DCID of the entity that the variable describes.

Query Parameters

Name	Type	Description
key Required	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 Optional	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: December 17, 2024 • Send feedback about this page