/v1/bulk/observations/series
Retrieve a series of observations for multiple variables and entities.
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
}
]
}
]
}
]
}
Page last updated: November 27, 2024 • Send feedback about this page