Detailed endpoint: GET /api/data/detailed/find
Part 1: Login Endpoint
Part 2: Aggregate Endpoint
Part 3: Detailed Endpoint
Requests directed at the detailed endpoint will return tank by tank data.
Request format (detailed endpoint)
The basic form for the detailed request is:
https://platform.ursaspace.com/api/data/detailed/find?qry_<FieldName>=<Value>&qry_<TimeField>_start=<timestamp>&qry_<TimeField>_end=<timestamp>
Timestamp should take the form YYYY-MM-DDThh:mm:ssZ based on ISO 8601 standard. No quotes, single or double, are used around any values.
Multiple qry_<FieldName>=<Value> pairs can be utilized by appending with an ampersand. A list of queryable fields and valid values is available later in this document.
There are multiple time range options: ReportTime, PublishTime and ResultTime. Only once time range type can be queried on at a time, and the start date must be before the end date. See the data dictionary for time parameter definitions.
To find the queryable values for a field with the API itself, try sending a request to the aggregate endpoint and grouping by the axis you are interested in. E.g., qry_SubscriptionType=China and grp_ValueOf=LocationName would show you all the valid LocationName values in China.
Examples
Query for all tank measurements with April report dates:
https://platform.ursaspace.com/api/data/detailed/find?qry_ReportTime_start=2020-04-01T14:00:00.000Z&qry_ReportTime_end=2020-04-30T14:00:00.000Z
Query for China tank measurements published between May 22, 2020 and May 23, 2020
https://platform.ursaspace.com/api/data/detailed/find?qry_PublishTime_start=2020-05-22T00:00:00.000Z&qry_PublishTime_end=2020-05-24T00:00:00.000Z&qry_Country=China
Query for refinery tanks in Nigeria from Jan 1, 2020 to Feb 1, 2020
https://platform.ursaspace.com/api/data/detailed/find?qry_ReportTime_start=2020-01-01T00:00:00.000Z&qry_ReportTime_end=2020-02-01T00:00:00.000Z&qry_Country=Nigeria&qry_StorageType=Refinery
Response format (detailed endpoint)
{
“queryRequestId”: “<GUID>”,
“queryTime”: “<ISO 8601 Timestamp>”,
“queryUrl”: “detailed/find”,
“queryParameters”: {
“qry_Country”: [
“<Country>”
],
“qry_ReportTime_end”: [
“<ISO 8601 Timestamp>”
],
“qry_ReportTime_start”: [
“<ISO 8601 Timestamp>”
]},
“links”: {},
“queryResult”: {
“records”: [{
“tankEntityId”: null,
“reportTime”: “2020-02-13T14:00:00.000Z”,
“resultTime”: “2020-02-07T03:43:21.000Z”,
“record”: {
“coordinates”: {
“axis_Algorithm”:”V3 Auto Sentinel”,
“axis_Company”: “Baniyas Refining Company”,
“axis_Country”: “Syria”,
“axis_CrudeConfidence”: “Yes”,
“axis_IsOecd”: “false”,
“axis_LocationName”: “Baniyas”,
“axis_Region”: “Middle East”,
“axis_ReportTime”: “2020-02-13T14:00:00.000Z”,
“axis_StorageType”: “Refinery”,
“axis_SubscriptionType”: “All Regions,MENA”,
“axis_TankEntity”: “BAN001”,
“axis_TerminalName”: “SCOT (Baniyas)”,
“axis_Territory”: “Tartus”,
“axis_Sensor”: “HIMIAGE”,
},
“values”: {
“capacityBarrels”: 218594,
“cylinderHeightM”: 17.7,
“errorBarrels”: 832,
“fillBarrels”: 66851,
“heightDropM”: 12.287,
“latitude”: 35.2189,
“longitude”: 35.9657,
“radiusAverageM”: 25
}
}
},}]}