Link

Get Populations for Place.

Given a list of Place DCID’s, return the DCID of StatisticalPopulation’s for these places, constrained by the given property values.

URL : /node/populations

Method : POST

Auth required : YES

To get an API key, check API Key section.

Required Arguments:

  • key: Your API key.

  • dcids: A list of DCID’s identifying Place’s of populations to query for. These DCID’s are treated as the value associated by the property location for each returned StatisticalPopulation.

  • populationType: The populationType of each StatisticalPopulation, e.g. Person or Student.

Optional Arguments:

  • pvs: A list of objects with constraining property and value fields that the StatisticalPopulation should be constrained by.

POST Request

Example

curl -X POST 'https://api.datacommons.org/node/populations?key=API_KEY' \
-d '{ "dcids": ["geoId/05", "geoId/06"], \
      "populationType": "Person", \
      "pvs": [{"property":"gender", "value": "Male"}, \
               {"property":"age", "value": "Years85Onwards"}]}'

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 place and population for the corresponding population DCID.

[
  {
    "dcid": "geoId/05",
    "population": "dc/p/7j2me3p74sht1"
  },
  {
    "dcid": "geoId/06",
    "population": "dc/p/gpvt9t84mq3gg"
  }
]

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: (populationType not specified)

curl -X POST 'https://api.datacommons.org/node/populations?key=API_KEY' \
-d '{"dcids": ["geoId/05"], "pvs": [{"property":"gender","value": "Male"}]}'

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/populations'

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