Get statistical time series for a place
Returns a time series of statistical values for a place based on a
StatisticalVariable
.
See the full list of StatisticalVariables.
When there are multiple sources for the same statistical variable, a prefered source with more recent or more authorative data is selected.
General information about this endpoint
URL: /stat/series
Methods available: GET
Required arguments:
place
: Thedcid
of thePlace
to query for.stat_var
: Thedcid
of theStatisticalVariable
.
Optional arguments:
measurement_method
: Thedcid
of the preferredmeasurementMethod
value.observation_period
: The preferredobservationPeriod
value.unit
: The dcid of the preferredunit
value.scaling_factor
: The preferredscalingFactor
value.
How to construct a request to the place statistics time series endpoint
Step 1: Assembling the information you will need
NOTE:
Specifying arguments that do not exist for the target place and variable will result in an empty response.
Going into more detail on how to assemble the values for the required arguments:
place
: For this parameter, you will need to specify the DCID (the unique ID assigned by Data Commons to each node in the graph) of the place you are interested in.stat_var
: The statistical variable whose value you are interested in.
In addition to these required properties, this endpoint also allows for other, optional arguments. Here are helpful arguments in regular use by Data Commons developers:
-
measurement_method
: The technique used for measuring a statistical variable. -
observation_period
: The time period over which an observation is made. -
unit
: The unit of measurement. -
scaling_factor
: Property of statistical variables indicating factor by which a measurement is multiplied to fit a certain format.
Step 2: Creating the request
Since only the GET method is available for this endpoint, you will need to assemble the request via query parameters in the URL.
What to expect in the response
Your response will always look like this:
{
"value": <number>
}
Example requests and responses
Example 1: Retrieve the count of men in the state of California.
-
curl --request GET \ --url 'https://api.datacommons.org/stat/series?place=geoId%2F06&stat_var=Count_Person_Male'
-
This endpoint does not support POST requests.
Example 2: Retrieve the number of people in Bosnia and Herzegovina as counted by the Bosnian census.
-
curl --request GET \ --url 'https://api.datacommons.org/stat/series?place=country%2FBIH&stat_var=Count_Person&measurement_method=BosniaCensus'
-
This endpoint does not support POST requests.
Example 3: Retrieve the death count in Miami-Dade County over a period of one year.
-
curl --request GET \ --url 'https://api.datacommons.org/stat/series?place=geoId%2F12086&stat_var=Count_Death&observation_period=P1Y'
-
This endpoint does not support POST requests.
Example 4: Retrieve the distribution of the drug naloxone in Miami-Dade County in grams.
-
curl --request GET \ --url 'https://api.datacommons.org/stat/series?place=geoId%2F12086&stat_var=RetailDrugDistribution_DrugDistribution_Naloxone&unit=Grams'
-
This endpoint does not support POST requests.
Example 5: Retrieve the percentage of nominal GDP spent by the government of the Gambia on education.
-
curl --request GET \ --url 'https://api.datacommons.org/stat/series?place=country%2FGMB&stat_var=Amount_EconomicActivity_ExpenditureActivity_EducationExpenditure_Government_AsFractionOf_Amount_EconomicActivity_GrossDomesticProduction_Nominal&scalingFactor=100.0000000000'
-
This endpoint does not support POST requests.
Error Responses
If your request does not include a required argument, you will receive a 400 status code and an error message like the following:
{
"code": 3,
"message": "Missing required argument: stat_var",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"stackEntries": [],
"detail": "internal"
}
]
}
If your request includes a bad argument, you will receive a 404 status code and an error message like the following:
{
"code": 5,
"message": "No statistical variable found for CountPerson_Male",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"stackEntries": [],
"detail": "internal"
}
]
}
Page last updated: November 27, 2024 • Send feedback about this page