Link

Get Observations for Populations.

Given a list of StatisticalPopulation DCIDs, return the DCID of Observation’s for these statistical populations, constrained by the given observation’s property values.

URL : /node/observations

Method : POST

Auth required : YES

To get an API key, check API Key section.

Required Arguments:

  • key: Your API key.

  • dcids: A list of statistical populations to query, identified by their DCIDs. These DCIDs are treated as the property value associated with returned Observation’s by the property observedNode

  • statsType: The statistical type of the Observation. This is commonly set to measuredValue.

  • measurementMethod: The property value associated with returned Observation’s by the property measurementMethod of the observation. If the Observation does not have this property specified, set this to an empty string.

  • measuredProperty: The property value associated with returned Observation’s by the property measuredProperty

  • observationDate: The property value associated with returned Observation’s by the property observationDate. This is specified in ISO8601 format.

  • observationPeriod: The property value associated with returned Observation’s by the property observationPeriod of the observation. If the Observation does not have this property specified, set this to an empty string.

POST Request

Example

curl -X POST 'https://api.datacommons.org/node/observations?key=API_KEY' \
-d '{"dcids": ["dc/p/x6t44d8jd95rd", "dc/p/lr52m1yr46r44"], \
     "measuredProperty": "count", \
     "statsType": "measuredValue", \
     "observationDate": "2018-12", \
     "observationPeriod": "P1M", \
     "measurementMethod": "BLSSeasonallyAdjusted"}'

Success Response

Code : 200 OK

Response content example

{
    "payload": "<payload string>",
}

The “payload string” is a string encoding of JSON object that is a list of objects with fields dcid for the statistical population and observation for the corresponding observation DCID.

[
  {
    "dcid": "dc/p/lr52m1yr46r44",
    "observation": "3075662.000000"
  },
  {
    "dcid": "dc/p/x6t44d8jd95rd",
    "observation": "18704962.000000"
  }
]

NOTE: Please run JSON.parse() on the payload field to retrieve the data. For example, in JavaScript: var data = JSON.parse(response['payload']).

Error Response

Code: 500 Internal Server Error

Request example: (observationDate not specified)

curl -X POST 'https://api.datacommons.org/node/observations?key=API_KEY' \
-d '{"dcids": ["dc/p/x6t44d8jd95rd", "dc/p/lr52m1yr46r44"], \
     "measuredProperty": "count", \
     "statsType": "measuredValue"}'

Response content example

{
  "code": 2,
  "message": "missing required arguments"
}

Code: 401 Unauthorized

Request example: (API key not specified)

curl -X POST 'https://api.datacommons.org/node/observations'

Response content example

{
  "code": 16,
  "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API."
}