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 of Place 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 to DCGET, 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: