Global Oil Storage data is available via API.
Ursa's Global Oil Storage RESTful API helps to retrieve insights from the global oil inventory collection. On a weekly cadence, Ursa measures the oil storage capacities in different global locations and outputs the data into a database for easy consumption.
The API is split into three different endpoints: Login, Aggregates, and Detailed. All interactions with this API are through HTTP requests and must include a request header. Note that this overview will assume at least a basic understanding of a RESTful API. There are many available web resources to learn about RESTful web interfaces. For example, refer to Red Hat's overview of a RESTful API as a starting point.
Each Global Oil Storage endpoint can take a number of different query fields and values as inputs. The following documentation supplies the basic format for queries, lists of the available query fields, and valid values for each. These are split into groups by the endpoint name.
In general, the Oil data API requests take this form:
https://platform.ursaspace.com/api/data/<endpoint name>/find?<params>
Please note the above URL has annotations in angle brackets (<>). These portions indicate user-defined data points. You will need to replace the whole <text> with your data. Example: <endpoint name> becomes aggregate when you want to reach the aggregate endpoint. Also note that in some of Ursa's URL-based requests in other documents, there are quotation marks in some of the JSON responses, but are not actually used in the input values.
To use this API with Python, a library like Requests is needed to interact with the REST service and jq to parse the JSON response object.
Login Endpoint
The first endpoint of using the RESTful API is logging into the system. This is critical to accessing the rest of the API. For more insight, please visit the Global Oil Storage Authentication page.
Each request must include a bearer token in the request header. The following two details will need to be provided in the header:
- The Field should be set to
Authorization
- The Value needs to be set to
Bearer <YOUR_UNIQUE_JSON_WEB_TOKEN>
The JSON Web Token can be retrieved by sending a POST request to the login endpoint with the credentials.
A tool like Postman is recommended for testing the API. This application has documentation to walk through the process of making an API request.
Detailed Endpoint
This endpoint is responsible for returning tank-by-tank results that are organized by user-defined groupings. When the database is updated with the latest results from the global inventory, this endpoint reflects those changes.
Possible groupings include, but aren't limited to, location (e.g., region, country) and oil company metadata (e.g., company name, terminal name).
For more information, navigate to the Detailed Endpoint page in the documentation.
Aggregate Endpoint
This endpoint is responsible for returning aggregations (i.e., the sums or averages) based on user-defined groupings. Unlike the Detailed endpoint, the aggregates are updated on a weekly basis (Thursdays at 14:00 UTC).
Possible groupings include, but aren't limited to, report metadata (e.g., report publish date) and temporal cadences (e.g., weekly, monthly).
For additional information, refer to the Aggregate Endpoint page in the documentation.