Get Time Series for a Place

datacommons_pandas.build_time_series(place, stat_var, measurement_method=None,observation_period=None, unit=None, scaling_factor=None)

Returns a pandas.Series representing a time series for the place and stat_var satisfying any optional parameters.

See the full list of StatisticalVariables.


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

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

  • 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 (int): (Optional) The preferred scalingFactor for the stat_var.


A pandas.Series with dates (str) as index for observed values (float) for the stat_var and place.


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

Be sure to initialize the library. Check the datacommons_pandas 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_pandas as dcpd
>>> dcpd.build_time_series("geoId/05", "Count_Person_Male")
2015    1451913
2016    1456694
2017    1461651
2018    1468412
2011    1421287
2012    1431252
2013    1439862
2014    1447235
dtype: int64

In the next example, the parameter observation_period='P3Y' overly constrains the request so the API throws ValueError:

>>> import datacommons_pandas as dcpd
>>> dcpd.build_time_series('geoId/06085', 'Count_Person', observation_period='P3Y')
ValueError    Traceback (most recent call last)
-->          raise ValueError('No data in response.')

ValueError: No data in response.