/v1/bulk/observations/series
Retrieve a series of observations for multiple variables and entities.
See Also:
To retrieve a single observation within a series, use /v1/bulk/observations/point.
For single queries with a simpler output, see the simple version of this endpoint.
To retrieve a single observation within a series, use /v1/bulk/observations/point.
For single queries with a simpler output, see the simple version of this endpoint.
Request
https://api.datacommons.org/v1/bulk/observations/series?entities={entity_dcid_1}&entities={entity_dcid_2}&variables={variable_dcid_1}&variables={variable_dcid_2}&key={your_api_key}
URL:
https://api.datacommons.org/v1/bulk/observations/series
Header:
X-API-Key: {your_api_key}
JSON Data:
{
"entities": [
"{entity_dcid_1}",
"{entity_dcid_2}",
...
],
"variables": [
"{variable_dcid_1}",
"{variable_dcid_2}",
...
]
}
Path Parameters
There are no path parameters for this endpoint.
Query Parameters
| Name | Type | Description |
|---|---|---|
| key |
string | Your API key. See the page on authentication for a demo key, as well as instructions on how to get your own key. |
| entities |
Repeated string | DCIDs of the entities the variables describe. |
| variables |
Repeated string | DCIDs of the variables to query observations for. |
| all_facets |
Boolean | Whether to return data from all facets available. If true, data from all facets available will be returned. If false, only data from the preferred facet will be returned. Defaults to false. |
Response
The response looks like:
{
"observationsByVariable": [
{
"variable": "variable1_dcid",
"observationsByEntity": [
{
"entity": "entity1_dcid",
"seriesByFacet": [
{
"series": [
{
"date": "YYYY-MM-DD",
"value": 1234
}, ...
],
"facet": 1234567890
}
]
},
{
"entity": "entity2_dcid",
"seriesByFacet": [
{
"series": [
{
"date": "YYYY-MM-DD",
"value": 1234
}, ...
],
"facet": 1234567890
}
]
}
]
}, ...
{
"variable": "variable2_dcid",
"observationsByEntity": [
{
"entity": "entity1_dcid",
"seriesByFacet": [
{
"series": [
{
"date": "YYYY-MM-DD",
"value": 1234
}, ...
],
"facet": 1234567890
}
]
},
{
"entity": "entity2_dcid",
"seriesByFacet": [
{
"series": [
{
"date": "YYYY-MM-DD",
"value": 1234
}, ...
],
"facet": 1234567890
}
]
}
]
}
]
}
Response fields
| Name | Type | Description |
|---|---|---|
| observationsByVariable | list | List of observations organized by variable. These are further organized by entity, and then by facet. Observations are returned in chronological order. |
| facets | object | Metadata on the facet(s) the data came from. Can include things like provenance, measurement method, and units. |
Examples
Example 1: Get time series for multiple variables and entities
Get total annual electric power consumption (DCID: Annual_Consumption_Coal_ElectricPower ) and water withdrawal rates (DCID: WithdrawalRate_Water ) for both Virginia (DCID: geoId/51 ) and Texas (DCID: geoId/48 )
-
Request:
$ curl --request GET --url \ 'https://api.datacommons.org/v1/bulk/observations/series?entities=geoId/51&entities=geoId/48&variables=Annual_Consumption_Coal_ElectricPower&variables=WithdrawalRate_Water&key=AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' -
Request:
$ curl --request POST \ --url https://api.datacommons.org/v1/bulk/observations/series \ --header 'X-API-Key: AIzaSyCTI4Xz-UW_G2Q2RfknhcfdAnTHq5X5XuI' \ --data '{"entities":["geoId/51", "geoId/48"], "variables":["Annual_Consumption_Coal_ElectricPower", "WithdrawalRate_Water"]}'
Response:
{
"observationsByVariable": [
{
"variable": "Annual_Consumption_Coal_ElectricPower",
"observationsByEntity": [
{
"entity": "geoId/48",
"seriesByFacet": [
{
"series": [
{
"date": "2001",
"value": 92437807
},
{
"date": "2002",
"value": 95672686
},
<...output truncated for brevity...>
{
"date": "2019",
"value": 63310631
},
{
"date": "2020",
"value": 56068974
}
],
"facet": 3743503335
}
]
},
{
"entity": "geoId/51",
"seriesByFacet": [
{
"series": [
{
"date": "2001",
"value": 15427618
},
{
"date": "2002",
"value": 15416555
},
<...output truncated for brevity...>
{
"date": "2019",
"value": 1972956
},
{
"date": "2020",
"value": 1814436
}
],
"facet": 3743503335
}
]
}
]
},
{
"variable": "WithdrawalRate_Water",
"observationsByEntity": [
{
"entity": "geoId/48",
"seriesByFacet": [
{
"series": [
{
"date": "1985",
"value": 25185.230000000014
},
{
"date": "1990",
"value": 26321.259999999987
},
<...output truncated for brevity...>
{
"date": "2010",
"value": 33382.35999999998
},
{
"date": "2015",
"value": 30029.560000000005
}
],
"facet": 2157651424
}
]
},
{
"entity": "geoId/51",
"seriesByFacet": [
{
"series": [
{
"date": "1985",
"value": 2158.1
},
{
"date": "1990",
"value": 2367.2300000000005
},
<...output truncated for brevity...>
{
"date": "2010",
"value": 8800.439999999995
},
{
"date": "2015",
"value": 7720.680000000003
}
],
"facet": 2157651424
}
]
}
]
}
]
}