Retrieve a statistical value for a place

Returns a statistical value for a place based on the StatisticalVariable. See the full list of StatisticalVariables.

When there are multiple sources for the same statistical variable, a prefered source with more recent data or more authority is selected.

General information about this endpoint

URL: /stat/value

Methods available: GET

Required arguments:

• place: The DCID of the Place to query for.
• stat_var: The DCID of the StatisticalVariable. More information is available in the glossary.

You can find a list of StatisticalVariables with human-readable names within this documentation.

Optional arguments:

• date: The preferred date of observation in ISO 8601 format. If not specified, returns the latest observation.
• measurement_method: The DCID of the preferred measurementMethod value.
• observation_period: The preferred observationPeriod value.
• unit: The DCID of the preferred unit value.
• scaling_factor: The preferred scalingFactor value.

How to construct a request to the place statistics value endpoint

Step 1: Assembling the information you will need

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:

• date: Specified in ISO 8601 format. Examples include 2011 (the year 2011), 2019-06 (the month of June in the year 2019), and 2019-06-05T17:21:00-06:00 (5:17PM on June 5, 2019, in CST).

• 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": integer
}

Example requests and responses

Example 1: Retrieve the count of men in the state of California.

Example 2: Retrieve the count of robberies in the state of Georgia in the year 2011.

Example 3: Retrieve the number of people in Bosnia and Herzegovina as counted by the Bosnian census.

Example 4: Retrieve the death count in Miami-Dade County over a period of one year.

Example 5: Retrieve the distrubtion of the drug naloxone in Miami-Dade County in grams.

Example 6: Retrieve the percentage of nominal GDP spent by the government of the Gambia on education.

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