Get Statistics Value for a Place

datacommons.get_stat_value(place, stat_var, date=None, measurement_method=None,observation_period=None, unit=None, scaling_factor=None)

Returns a value for place based on the stat_var, with optional filter parameters.

See the full list of StatisticalVariables.


  • place (str): The dcid of the Place to query for.

  • stats_var (str): The dcid of the StatisticalVariable.

  • date (str): (Optional) The preferred observationDate. This is an ISO-8601 date, e.g. “YYYY”, “YYYY-MM” or “YYYY-MM-DD”. If not specified, returns the latest observation.

  • measurement_method (str): (Optional) The dcid of the preferred [measurementMethod]( for the stat_var.

  • observation_period (str): (Optional) The preferred observationPeriod for the stat_var. This is an ISO 8601 duration such as P1M (one month).

  • unit (str): (Optional) The dcid of the preferred unit for the stat_var.

  • scaling_factor (str): (Optional) The preferred scalingFactor for the stat_var.


A float value of the stat_var for place, filtered by the optional parameters.


  • ValueError - If no statistical value found for the place with the given parameters.

Be sure to initialize the library. Check the Python library setup guide for more details.

You can find a list of StatisticalVariables with human-readable names here.


We would like to get the male population in Arkansas

>>> import datacommons as dc
>>> dc.get_stat_value("geoId/05", "Count_Person_Male", date="2012")

In next example, the parameter “observation=P3Y” overly constrains the request so the API throws ValueError:

>>> dc.get_stat_value('geoId/06085', 'Count_Person', observation_period='P3Y')
>>> Traceback (most recent call last):
    raise ValueError('No data in response.')