Get the value of a statistical variable at a given place and time
Given a list of DCIDs representing Place objects, a StatisticalVariable, and optionally a date, get the measurements of the specified variable in the specified places with a date (if specified).
General information about this formula
Formula: =DCGET(dcids, variable, date)
Required arguments:
-
dcids
: A list ofPlace
nodes, identified by their DCIDs. -
variable
- The StatisticalVariable whose measurement is sought.
Optional arguments:
date
- The date or dates of interest. If this argument is not specified, the API will return the latest observation of the variable.
Assembling the information you will need to use this formula
This endpoint requires the arguments dcids
and variable
. DCIDs are unique node identifiers defined by Data Commons. Your query will need to specify the DCIDs for the parent places of interest. You are also required to specify the statistical variable whose measurement you seek. Statistical variables are the metrics tracked by Data Commons.
You may choose to specify the date
argument. You may specify this argument as a single value, a row, or a column. All dates must be in ISO 8601 format (e.g. 2017, “2017”, “2017-12”) or as a Google sheets date value.
Returns
The value of the variable at those places on the specified date (or on the latest available date, if no date is specified).
NOTE:
It’s best to minimize the number of function calls to
DCGET
by using a single call to get a variable for a row/column of places and/or a column/row of times. This is because a spreadsheet will make one call to a Google server per custom function call. If your sheet contains thousands of separate calls toDCGET
, expect it to be slow.
You can find a list of StatisticalVariables with human-readable names here.
Examples
Before trying this method out, make sure to follow the setup directions in the main section for Sheets docs.
Get the total population of Hawaii in 2017.
=DCGET("geoId/15", "Count_Person", 2017)
Get the population of multiple places with a single function call.
Input
Output
Get the population of a single place in multiple years.
Input
Output
Get the median age of multiple places in multiple years.
With places as a column and dates as a row:
Input
Output
With places as a row and dates as a column:
Input
Output
Error outputs
If you provide an invalid DCID, the API returns an error:
If you provide a nonexistent statistical variable, the API returns a blank value:
If you provide an invalidly formatted date, the API returns a blank value:
If you fail to provide all required arguments, you will receive an error: