1. What is an API and what are the benefits?

In today’s data-driven world, information is power. Harnessing energy insights has never been more critical for businesses seeking to optimise trading operations and minimise costs. With the advent of technology, accessing energy data has become easier and more comprehensive than ever before, thanks to Application Programming Interfaces (APIs). These tools serve as gateways to a wealth of information, enabling businesses to harness data for better decision-making, cost optimisation, and profitability. 

Data APIs allow users to access, process, and integrate vast amounts of energy market data directly into their applications, software, or systems. Whether it’s real-time supply & demand data, historical trends, or forecasts, these APIs provide a direct link to the repositories of data maintained by energy market participants.

Why is it beneficial to use Data via API?

1. Data accessibility and transparency:

Energy Data APIs democratise access to critical information that was once restricted to a select few. By making data readily available, these APIs promote transparency within the energy sector, fostering competition and innovation.

2. Real-time monitoring and control:

With real-time & timely data streams provided by APIs, businesses can respond promptly to fluctuations or anomalies in the markets. This proactive approach enables better trading decisions and helps prevent costly disruptions.

3. Integration and automation:

Integrating energy data into existing systems and workflows through APIs streamlines trading operations and enhances automation of data and processes. Whether it’s incorporating fundamental data into trading and management systems or integrating it with predictive analytics tools, APIs enable seamless integration across platforms.

Why use Vortexa’s API?

Unparalleled speed, customisability, and scalability

Using the Vortexa’s API presents a myriad of benefits over traditional methods of accessing our energy and freight data. Its key features include unparalleled speed, customisability, and scalability. Enabling users to tailor every data request to suit their specific requirements. This level of customisation allows for personalised analytics that align precisely with your business needs, facilitating more informed decision-making.

Automated extraction, curation, and processing

Gone are the days of manual data extraction and processing. With Vortexa’s API, users can automate these tedious tasks, ensuring that the data they require is readily available at the click of a button. This not only saves valuable time and resources but also eliminates the potential for human error, resulting in more accurate and reliable insights. Based on Vortexa customer research, using data via API can save up to 20 hours per week on manual data processing.

Integration of other data sources & systems

The true power of using an API over a web app lies in its ability to integrate seamlessly with other relevant data sources, enhancing value for users. Whether you’re leveraging proprietary datasets or incorporating third-party sources, APIs enable you to consolidate disparate data streams within your platform of choice, providing a holistic view of the energy markets. 

Quick developer iterations and comprehensive documentation

For data scientists, market analysts, and software engineers alike, the API offers a robust and versatile toolkit for extracting actionable insights. Data scientists can leverage the Python SDK for rapid prototyping, harnessing the power and flexibility of Python to build data-driven applications with ease. Market analysts, on the other hand, can utilise the Snowflake or alternative cloud integration to access data in familiar database structures, streamlining their analytical workflows. Meanwhile, software engineers can build scalable data pipelines using the JSON endpoint, supported by comprehensive documentation, developer tools, and expert resources.

Conclusion: revolutionising energy insights

In conclusion, accessing energy data via Vortexa’s API represents a paradigm shift in managing energy market data. By offering unparalleled speed, customisability, and scalability, our API empowers businesses to make informed decisions and optimise commodities trading and operations. Whether you’re a data scientist, market analyst, or software engineer, our API provides the tools and resources you need to unlock the full potential of your energy insights.

Vortexa’s data sets are available via API

With Vortexa’s powerful API, users gain access to a variety of data sources that provide unparalleled insights into the global energy landscape. Let’s delve into the different data sources available via Vortexa’s API and explore how they can empower businesses to optimise energy and freight markets.

Cargo tracking: real-time insights into energy movements

Vortexa’s cargo tracking data offers near real-time and historical information on the movements of various energy commodities, including oil, refined products, LNG, and LPG, across the globe. This data provides detailed insights into cargo movements, from origins to destinations, including waypoints, vessels involved, and associated corporate entities. Whether it’s tracking floating storage, transit status, Vortexa’s cargo tracking data offers a comprehensive view of energy flows.

Vortexa flows track all oil & gas commodities as well as biofuels.

Voyage tracking: understanding vessel movements

Complementing cargo tracking, Vortexa’s voyages data provides a vessel-centric perspective of global energy movements. Users can track vessel visits, destinations, and activities from the first load to the final discharge, and the ballast legs in between. Gain insights into vessel movements and vessel transitions, including loading, discharging, congestion, and dry-dock, shipyard activities, or acting as an FSO somewhere; enabling a deeper understanding of global shipping dynamics.

Leveraging the power of the voyages’ dataset, Vortexa created the vessel availability dataset to help you understand the availability of vessels at a given port, for a given laycan. This data set helps to decide where to position your vessels by understanding the vessel supply and demand dynamics playing out in real time.

Onshore Inventories: granular insights into crude storage

Vortexa offers the most complete picture of global crude oil storage levels available on the market today. We offer granular, tank-level data on onshore crude storage worldwide, with a particular focus on key hubs like Cushing, Oklahoma, USA. With 2x per week readings, users gain visibility into crude storage levels, allowing for better inventory management and market analysis. Vortexa tracks 22,500 onshore crude tanks, and 6.8m barrels in 123 countries.

Vessel positions: real-time location data

Access accurate vessel location, speed, heading, declared destination, ETA, and draught data for the last two weeks at 15-minute granularity. Stay informed about vessel movements and market trends, enabling proactive decision-making and risk management.

Freight rates and market outlook: tracking Baltic Exchange routes and more

Vortexa’s freight pricing data allows users to track the price of Baltic routes in worldscale, $/t, and lump sum, with innovative price prediction capabilities. Stay ahead of freight market trends and optimise shipping strategies for cost efficiency and operational excellence. Vortexa Freight Market Outlook provides a unique future outlook based on physical market factors 4 days ahead based on market sentiment predictions of the Baltic Exchange freight assessments and data-driven insight into critical emerging trends.

Fixtures: comprehensive data repository

The Fixtures API draws from multiple independent data sources, offering a single comprehensive repository for fixture information. Gain insights into chartering activities, vessel availability, and market trends, empowering strategic decision-making in the energy shipping sector.

Conclusion: empowering energy insights with Vortexa’s API

In conclusion, Vortexa’s API unlocks a treasure trove of data sources that provide invaluable insights into energy movements, freight dynamics, and inventory levels. By leveraging these data sources, businesses can optimise operations, mitigate risks, and seize opportunities in the ever-evolving energy landscape. 

Whether you’re tracking cargo movements, monitoring vessel activities, or analysing freight pricing trends, Vortexa’s API offers the tools and resources needed to stay ahead of the competition and drive success in the energy sector.

2. Deploying Vortexa’s data across different systems

Vortexa offers powerful tools for analysing global energy flows, freight markets, and oil inventory data. Our API provides instant, scalable, and flexible access to the global industry data, enabling you to build custom models and conduct ad-hoc analyses.

Below is a detailed overview of the integration and deployment methods offered by Vortexa.

1. Direct integration with REST API (JSON)

This method is best for those who need fine-grained control over API interactions and do not require language-specific SDK knowledge.

Coding proficiency: High
Language skills: Any

REST API is an application programming interface that adheres to the constraints of REST architectural style. Vortexa’s REST API allows users to retrieve data in JSON format through our REST endpoints, such as Cargo Movements, Products, Vessel Positions, etc. Access the full list of endpoints here.

This method is most suitable for ingesting data into custom applications or dashboards. For example, if you’re a data engineer creating a dashboard for the trading team on market supply and demand.

Reason for choosing the method:

• Flexibility: Enable complete control over the requests and can use any HTTP client.
• Language agnostic: Usable with any programming language that can make HTTP requests.
• Granular control: Allows for fine-tuned control over the API requests and responses, enabling custom handling of HTTP status codes, headers, and other low-level details.

Potential considerations:

• More boilerplate code: Requires writing more code to handle HTTP requests, parse responses, manage authentication, etc.
• Steeper learning curve: Requires familiarity with HTTP methods, status codes, and error handling.

2. Python SDK

This method is best for analysts and data scientists who already use Python in their workflows, and data engineers looking for an alternative to REST API.

Coding proficiency: Medium
Language skills: Python

SDKs are designed to simplify the development process by providing a high-level interface and abstractions for interacting with a service or API. Typical use cases could be a data scientist looking to build a predictive model or export level forecasting, or a trading analyst monitoring day-to-day cargo flows.

Example:

In an interactive Python console, run:

from datetime import datetime
from vortexasdk import CargoMovements
df = CargoMovements()\
    .search(filter_activity='loading state',
        filter_time_min=datetime(2017, 8, 2),
        filter_time_max=datetime(2017, 8, 3))\
    .to.df()

Returns:

Reasons for choosing the method:

• Ease of use: Abstracts away the complexity of HTTP requests and responses. You interact with Python objects and methods.
• Less boilerplate code: Reduces the amount of code needed to make API calls, handle authentication, and parse responses.
• Built-in features: Often includes additional features like retries, error handling, and convenience functions for common tasks.

Potential considerations:

• Less control: It may abstract away some details, making it harder to handle specific edge cases or custom requirements.
• Language-specific: Tied to Python, so not suitable if you need to support multiple programming languages.

To learn more about these methods, please explore Vortexa’s API resources available to our users.

• Vortexa Python SDK docs
• List of Vortexa Python SDK endpoints
• Python Installation guide for Windows, Mac, or Linux
• Vortexa Python SDK virtual course on Vortexa Academy

3. Snowflake cloud integration

This method is best for developers looking to access the data in a normalised structure via SQL or those looking to integrate with other datasets in Snowflake.

Coding proficiency: Low
Language skills: SQL

Snowflake is a cloud-based data warehousing platform designed to handle large-scale data storage and analytics. Available on AWS, Azure, and Google Cloud, it’s a popular choice for those who prefer a traditional database approach.

For example, you’re an analyst looking to query data using SQL to build custom dashboards. Using data warehouses such as Snowflake reduces data query time and offers connectivity to dash boarding tools such as Power BI and Tableau.

Existing Snowflake users can access Vortexa’s cargo movements and voyages datasets at the click of a button. We provide all users with a set of example queries to help them understand the data structure and recreate every chart and table they can see in our analytics app. From there, updating and tailoring them to suit their own specific needs is just a matter of deciding how you want to display the data.

Reasons for choosing the method:

• Ease of use: Set up and query data within minutes of gaining access to Snowflake.
• No infrastructure requirements: Snowflake is a fully managed data warehouse, meaning that the infrastructure, maintenance, upgrades, and backups are handled by Snowflake. This reduces the burden on IT and DevOps teams.
• Flexibility and scalability: The ability to scale compute resources on-demand helps avoid over-provisioning and underutilization, optimising cost-efficiency.

Potential considerations:

• Computing costs: Snowflake users pay additional costs for using computing power from the cloud.
• No direct access to hosting & storage of the data: a Snowflake user doesn’t have direct access to the hosting & storage of the data. The hosting and storage of the data is managed by Snowflake.

3. Vortexa’s API data in action: explore the use cases

Learn from Vortexa’s data experts as they employ Python SDK to analyse freight fundamentals and onshore crude inventories data.

4. How to get started with Vortexa’s API

Installation and setup

Vortexa’s API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses (for successful and unsuccessful requests), and uses standard HTTP response codes, authentication, and verbs.

All requests are authenticated with an API key. You can start querying the API once you’ve obtained an API key. 

1. After receiving your Vortexa credentials, you will receive an API key from the Vortexa support team.
2. Install required libraries: Depending on your preferred programming language, you’ll need to install the appropriate libraries. For Python, Vortexa provides a dedicated notebooks library. You can install it pip install vortexasdk. 
3. Set up your development environment: Ensure you have a suitable environment for development. This may include setting up a virtual environment for Python projects to manage dependencies effectively.

Authentication methods

Vortexa’s API requires authentication to access data. Here’s how you can authenticate:

1. Obtain API keys/tokens: After signing up, you will need an API key or token. This can typically be found in Vortexa API reference documentation. Keep this key secure as it grants access to your data.
2. Authenticate requests: Use the obtained API key to authenticate your requests. When using the Vortexa Python client, authentication is straightforward:

import os
os.environ['VORTEXA_API_KEY'] = "YOUR_API_KEY"

Vortexa strongly recommends that users save their API key as an environment variable. So users only need authentication once. 

Accessing API documentation & support 

To efficiently use the Vortexa’s API, you should familiarise yourself with the available documentation:

1. Official API documentation

Vortexa’s official API documentation provides detailed information on endpoints, request parameters, and response formats. This documentation can be accessed via their website or directly through this https://docs.vortexa.com. You need to have Vortexa credentials to access the docs.

2. API reference documentation

The reference documentation provides comprehensive details about each API endpoint, including example requests and responses, which are crucial for understanding how to interact with the API effectively.

3. Content/Notebook library

Vortexa provides a variety of resources to help you get started quickly:

• Jupyter notebooks: These notebooks offer practical examples and use cases. You can find a library of Jupyter Notebooks that demonstrate how to use different API endpoints and integrate them into your workflows. Access these resources directly from the Vortexa SDK documentation.https://vortechsa.github.io/python-sdk/ 
• Sample code: The documentation and the Vortexa GitHub repository often contain sample code snippets to help you understand common tasks and best practices.

4. Vortexa’s solution architects support

Solutions architects can assist with designing and implementing integration with Vortexa data, tailored to your organisation’s needs. They provide expertise in API utilisation, data modelling, and integration strategies to optimise the use of Vortexa data.A solutions architect can be crucial in helping with API integrations, particularly in complex environments where multiple systems and data sources need to interact seamlessly.

Here are some examples of support from solution architects:

• Design the overall architecture for the integration, ensuring it meets business requirements and technical constraints.
• Recommendation of appropriate technologies, tools, and dash boarding platforms (e.g. Power BI) for the integration.
• Query guidance: Help in understanding every endpoint and its parameters, as well as support in setting up coding templates on a case-by-case basis.
• Definition of how our methodology works, including data definition, modelling and flows.
• Technical guidance and oversight to development teams during implementation.
• Error handling: We offer dedicated support to address any issues that arise, including guidance on making API/SDK queries, advice on handling invalid requests, and assistance with server error resolution.

5. Troubleshooting

Find solutions to common problems encountered while using the API. Reach out to support@vortexa.com at Vortexa if you need support to install or work with API.

Vortexa’s taxonomy

Understanding Vortexa’s taxonomy is crucial for effectively querying and interpreting the data:

1. Data hierarchy: Vortexa’s data is structured hierarchically, with detailed classifications for different entities such as vessels, cargoes, and locations.
2. Entity definitions: Familiarise yourself with the definitions and relationships of various entities to construct meaningful queries.
3. Taxonomy documentation: Detailed documentation on Vortexa’s taxonomy can be found within their API documentation, providing insights into the structure and classification of the data.

Conclusion

By following these steps, you can smoothly integrate Vortexa’s API with your internal systems. Ensure you thoroughly read the documentation, utilise the content library for practical examples, and refer to the FAQs for troubleshooting. With the right setup and understanding, you can leverage Vortexa’s powerful data to gain valuable insights and drive your business decisions.

For more detailed information, visit https://www.vortexa.com/product-data-api/