Aggregation endpoint: GET /api/data/aggregate/find
Part 1: Login Endpoint
Part 2: Aggregate Endpoint
Part 3: Detailed Endpoint
Request to the aggregate endpoint return aggregations (sum or average) based on user specified groupings. This is accomplished via additional request parameters to specify the type of aggregation, the temporal window to aggregate by, and the metadata field name to group by.
Unlike the detailed endpoint, which is updated on a rolling basis, the aggregate endpoint is updated once per week, Thursdays at 14:00 UTC, which is the associated reportTime for data being published in that reporting week.
This is a two-dimensional aggregation, both spatial and temporal options are available.
Request format (aggregate endpoint)
The basic form for the aggregate request is:
https://platform.ursaspace.com/api/data/aggregate/find?qry_<FieldName>=<Value>& qry_ReportTime_start=<timestamp>&qry_ReportTime_end=<timestamp>&grp_<Time window>=ReportTime&grp_ValueOf=<Group by field>&agg_<aggregation type>
Again, this request should include an Authorization key in the header with the value Bearer <Your unique token>.
Some useful aggregations may be to query at one aggregation level, such as Country (qry_Country=<some country>) and group at a more granular level (grp_ValueOf=LocationName). This allows your application to identify valid Locations within <some country>, in this example.
Queries across multiple axes will attempt to AND the qry. For example, qry_LocationName=Cushing&qry_Country=China would look for tanks with location name of Cushing AND country name of China.
Requests within the multiple values in the same axis will OR the values. So qry_LocationName=Cushing&qry_LocationName=Dalian would look for Cushing OR Dalian.
If the request had multiple axes each with multiple values, the API will look for multiple combinations (an OR of ORs).
For example, qry_LocationName=Cushing&qry_Country=China&qry_Country=United States&qry_LocationName=Dalian the API would look for multiple combinations. In this case tanks with location Cushing and country United States and the tanks with location Dalian and Country China would be included in the response. Tanks with location Cushing and country China would be returned too, but that combination of location and country is not present in the data and so no results will be returned for it.
Response format (aggregate endpoint)
This example shows a single result. More items would be appended to the groupAggregates array if more results are returned.
{
“queryRequestId”: “<GUID>”,
“queryTime”: “<ISO 8601 Timestamp>”,
“queryUrl”: “aggregate/find”,
“queryParameters”: {
“agg_<Aggregation type>”: [
“”
],
“grp_<Time window>”: [
“ReportTime”
],
“qry_ReportTime_end”: [
“<ISO 8601 Timestamp>”
],
“qry_ReportTime_start”: [
“<ISO 8601 Timestamp>”
],
“qry_<Field>”: [
“<Value>”
]
},
“links”: {},
“queryResult”: {
“appliedGroupByFunctions”: {
“ReportTime”: “<Time window>_ReportTime”
},
“appliedAggregateFunctions”: [
“<Aggregation type>”
],
“groupAggregates”: [
{
“coordinates”: {
“<Time window>_ReportTime”: “<ISO 8601>”
},
“values”: {
“capacityBarrels_<Agg type>”: <value>,
“fillBarrels_<Agg type>”: <value>
}
}
]
}
}