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

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"
   }
 }
}