Retrieve all statistical variables available for a particular place
Given a list of Place
DCIDs,
(e.g. any State
, Country
, etc.), return a list of statistical variables available for the specified DCIDs.
General information about this endpoint
URL: /place/stat-vars
Methods available: GET
, POST
Required arguments:
dcids
: A list ofPlace
nodes, identified by their DCIDs.
How to construct a request to the place statistical variables endpoint
Step 1: assembling the information you will need
This endpoint requires the argument dcids
. DCIDs are unique node identifiers defined by Data Commons. Your query will need to specify the DCIDs for the parent places of interest.
Step 2: creating the request
When actually putting together your request, you can choose from two options. If you intend to query only a small number of DCIDs, you may want to use the simpler formatting offered by the GET method. For larger numbers of DCIDs, or if you prefer to utilize a static URL, a POST request likely makes more sense. To use it, make a POST request against the main endpoint while changing the fields of the JSON body it sends.
Examples of usage for both GET and POST can be found below.
What to expect in the response
Your response will always look like this:
{
"places": {
<dcid>: {
"statVars": [
<dcid>,
...
]
},
...
}
}
Example requests and responses
Example 1: Retrieve a list of the statistical variables available for the country of Palau.
-
curl --request GET \ --url 'https://api.datacommons.org/place/stat-vars?dcids=country%2FPLW'
-
curl --request POST \ --url https://api.datacommons.org/place/stat-vars \ --header 'content-type: application/json' \ --data '{ "dcids": [ "country/PLW" ] }'
Response
{
"places": {
"country/PLW": {
"statVars": [
"MortalityRate_Person_Upto4Years_AsFractionOf_Count_BirthEvent_LiveBirth",
"LifeExpectancy_Person_Male",
"LifeExpectancy_Person_Female",
"LifeExpectancy_Person",
...
]
}
}
}
Example 2: Retrieve a list of statistical variables available for the cities of Dodoma and Dar es Salaam, Tanzania.
-
curl --request GET \ --url 'https://api.datacommons.org/place/stat-var?dcids=wikidataId%2FQ1960&dcids=wikidataId%2FQ3866'
-
curl --request POST \ --url https://api.datacommons.org/place/stat-vars \ --header 'content-type: application/json' \ --data '{ "dcids": [ "wikidataId/Q1960", "wikidataId/Q3866" ] }'
Response
{
"places": {
"wikidataId/Q1960": {
"statsVars": [
"Count_Person"
]
},
"wikidataId/Q3866": {
"statsVars": [
"Count_Person"
]
}
}
}
Error Responses
If your request is malformed in some way, you will receive a 400 status code and an error message like the following:
{
"code": 3,
"message": "Missing required arguments: dcid",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"stackEntries": [],
"detail": "internal"
}
]
}