AXSMarine Documentation

APIHUB

## Sections
• [Power Your Applications with AXSMarine Data](https://apidocs.axsmarine.com/getting-started/introduction.md): Accelerate your development with AXSMarine’s enterprise-grade APIs and maritime data services. Available via REST and GraphQL, our APIs make it easy to integrate accurate, real-time intelligence on shipping and commodities into your applications—supporting use cases such as freight analytics, fleet monitoring, commodity trade flow analysis, market forecasting, supply & demand modeling, trading signal generation, and operational optimization. Whether you're building internal tools or complex enterprise systems, AXSMarine provides the data backbone your solutions need to perform at scale
• [Basics of APIs](https://apidocs.axsmarine.com/api-reference-guide/basics-of-apis.md): This section provides an overview of essential HTTP methods, request parameters, and response status codes used in AXSMarine APIs. HTTP Methods HTTP methods, or verbs, denote actions performed on resources. AXSMarine APIs support various HTTP methods: GET: Retrieve a representation of a specific resource. Example: Retrieving transaction details. POST: Submit data to create a new resource or trigger a state change. Example: Creating a new customer profile. PUT: Replace all representations of a target resource with the provided payload. Example: Updating a subscription plan. DELETE: Remove a specified resource. Example: Deleting a stored card. PATCH: Apply partial modifications to a resource. Example: Changing the status of an existing order. Parameters Parameters allow customization of API requests and responses. AXSMarine APIs support four types of parameters: Path Parameters: Integral parts of the endpoint URL, identifying specific resources. Query Parameters: Appended to the endpoint URL to filter or paginate results. Request Body Parameters: Included in the request body, transmitting data to the API server. Response Body Parameters: Represent data returned by the server in response to a request. HTTP Status Codes HTTP status codes communicate the outcome of client requests. AXSMarine employs HTTP status codes categorized into the following classes: Success (200): The request was successfully processed. Example: Successfully retrieved a resource or completed an action. 400 (Bad Request): The server could not understand the request due to invalid syntax. Example: Missing required parameters in the request. 401 (Unauthorized): Authentication is required and has failed or has not yet been provided. Example: Invalid or missing API key. 402 (Request Failed): The parameters were valid but the request failed. Example: Insufficient funds or expired credit card. 403 (Forbidden): The client does not have access rights to the content. Example: Attempting to access a resource without the necessary permissions. 404 (Not Found): The server can not find the requested resource. Example: Trying to access an endpoint that does not exist.
• [Authentication](https://apidocs.axsmarine.com/api-reference-guide/authentication.md): When it comes to interacting with APIs, authentication is a critical step to ensure secure communication between your application and the API service. API authentication is performed via HTTP Bearer Auth, which involves including your API key in the HTTP request headers, following the Bearer prefix. This method verifies your identity and grants you access to the API's resources, ensuring that only authorized users can make requests. AXSMarine uses the header Authorization to authenticate requests. To obtain an API token, please contact your account manager. Your API keys grant significant access, so it’s crucial to keep them safe! Avoid sharing your secret API keys in public places like GitHub, client-side code, and similar locations. API requests without authentication will fail.
• [Pagination](https://apidocs.axsmarine.com/api-reference-guide/pagination.md): Pagination in APIs refers to the process of dividing a large set of data into smaller, manageable chunks (pages) that can be retrieved incrementally. Instead of returning all results at once, which can be inefficient or overwhelming, an API uses pagination to return a subset of data, typically with specific parameters to manage it. This allows you to request specific portions of data (for example, 20 results per page) and navigate through pages. Pagination improves performance, reduces bandwidth usage, and helps ensure stability when handling large datasets. The next pages will explain you how to handle pagination when using GraphQL and REST AXS APIs.
  • [GraphQL - Cursor Based Pagination](https://apidocs.axsmarine.com/api-reference-guide/pagination/graphql.md): Overview This document provides an introduction to using cursor-based pagination with our GraphQL APIs. We will explain the concept of pagination and provide step-by-step instructions on how to implement it in your application. What is Cursor-Based Pagination? Cursor-based pagination is a technique used by APIs to paginate large datasets. It allows you to request subsequent pages of results by providing the last seen cursor or identifier. Benefits of Pagination Reduced load on our API and servers Improved performance and faster response times Ability to handle large datasets Steps 1 Understanding the Pagination Parameters Our GraphQL API uses the following pagination parameters: first : The number of items to return in a single response. after : A unique identifier for the last item returned. Our GraphQL APIs returns the following pagination informations : PageInfo : contains information about the pagination of the whole request, based on non-pagination parameters. endCursor : located in the PageInfo , refers to the last cursor of the result. The idea of the Partial Pagination is to request for another page if the number of results was equal to the number requested (thanks to the first parameter). If the number of result was smaller than the number requested, it means that there is no more data matching the parameters. Basically, the cursor of the last node (conveniently the endCursor ) should be used in the after parameter if the result returned were equal to first parameter. 2 Making an Initial Request To start using pagination, make an initial request to our API without providing a cursor. This will return the first page of results along with the cursor for the last item. Example (using GraphQL query) GraphQL query { items(first: 3) { pageInfo { endCursor } edges { node { id name } } } } We are requesting for the first 3 items to be returned, along with the PageInfo object. We do not need to request for the cursor of the nodes, since the endCursor is enough to request for the next page. 3 Checking for returned items Check if there are more results available by examining the response. If the number of returned items is equal to the provided parameter first , then it's very likely that there are more items matching the same criterias.. Example of a response JSON { "data": { "items": { "pageInfo": { "endCursor": "MA==" }, "edges": [ { "node": { "id": 01 "name": "example" } }, { "node": { "id": 02 "name": "example" } } ] } } } 4 Passing the Cursor Locate the received endCursor . In the subsequent request, pass this cursor to our API using the after parameter. Example (using GraphQL query) GraphQL query { items(first: 10, after: "MA==") { pageInfo { endCursor } edges { node { id name } } } } Troubleshooting If you're experiencing issues with pagination, please contact our support team for assistance.
  • [REST - "next" link](https://apidocs.axsmarine.com/api-reference-guide/pagination/rest.md): Overview This document provides an introduction to using pagination with our REST APIs. How do we expose pagination on REST ? In the response of your request, you should receive an array called results and an object called links . This second object is an open object that can contains useful links, such as next . The next link will contain the same request you made, with the same parameters, including the pagination parameter after , containing the internal identifier of the last item returned in the results array. This link is usable directly to query the next page of results. If there are no more results than the ones returned, the field will be null .
• [Export OpenAPI File](https://apidocs.axsmarine.com/api-reference-guide/openapi-export-file.md): The AXSMarine API Hub documentation is available as an OpenAPI 3.0 specification export. ⬇️ Download Get the OpenAPI specification file from the link below and save it somewhere handy — you'll need it in the next step. 📎 AXSMarine_OpenAPI_Specification.json Client Setup Follow the steps below to set up your preferred API client. Each section walks you through importing the spec, configuring your environment, and sending your first request. Pick the client you use and follow its guide. Postman : Download if needed: postman.com/downloads Step 1 — Import the spec Open Postman and click the three dots (...) in the top-left sidebar, then click Import . Choose File and select the downloaded AXSMarine_OpenAPI_Specification.json , or paste the link directly. When prompted, choose Postman Collection as the import type. Click Import . A new collection will appear in your sidebar with all endpoints organized into folders. Step 2 — Create an environment Click the Environments tab on the lower-left sidebar, then click New Environment . Name it (e.g. AXSMarine ). Add the following two variables: Title Description Title Variable Initial Value Current Value host apihub.axsmarine.com apihub.axsmarine.com authorization YOUR_TOKEN_HERE YOUR_TOKEN_HERE Step 3 — Activate the environment In the top-right dropdown (shows "No Environment" by default), select your AXSMarine environment. Variables will now resolve automatically in all requests using the {{variable}} syntax. Step 4 — Make a request Expand the collection in the sidebar and pick any endpoint. Verify that the URL uses {{host}} and the Authorization header uses {{authorization}} . Click Send . Insomnia : Download if needed: insomnia.rest/download Step 1 — Import the spec Open Insomnia and go to your workspace. Click the + button and select File . Select the AXSMarine_OpenAPI_Specification.json file (or paste the URL directly if you prefer to point to the download link), then click Scan and Import . The collection will appear with all endpoints listed under a new document. Step 2 — Set up the environment In your collection, click the environment dropdown in the top-left (defaults to Base Environment ). Select OpenAPI env apihub.axsmarine.com — this is auto-generated from the spec and contains pre-configured values. Click the pencil icon next to the environment name to edit it. Add or update the following variables using the {{ _.variable }} syntax: { "scheme": "https", "base_path": "", "host": "apihub.axsmarine.com", "authorization": "YOUR_TOKEN_HERE" } Click Close in the bottom-right to save. Tip: Insomnia supports storing sensitive values like your API token as Secret variables (encrypted locally). In the environment editor, set the type of authorization to Secret to prevent it from being stored in plain text or accidentally synced. Step 3 — Make a request Select any endpoint from the list on the left. Click Send . Bruno : Download if needed: usebruno.com/downloads Bruno is a free, open-source API client that stores everything locally — no cloud sync, no account required. Step 1 — Import the spec Open Bruno, click the three dots ( ... ) in the top-left, and select Import Collection . Select Choose File(s) and select AXSMarine_OpenAPI_Specification.json , or select URL and paste the link directly. Select folder arrangement Tags (flat structure, all endpoints in one level) or Paths (folder tree structure, endpoints organized by URL path), then click Import . Choose a folder on your computer where Bruno will store the collection files. Step 2 — Create an environment In the top-right of Bruno, click the environment dropdown (shows No Environment by default). Select Configure to open the environment manager. Select AXSMarine API Hub environment. Add the following variable using the + Add Variable button: Title Description Name Value apiKey YOUR_TOKEN_HERE Click Save and Activate . Step 3 — Make a request Expand the collection in the left sidebar and select any endpoint. Click the → Send button. Quick Start Checklist Download the OpenAPI JSON file or copy the URL Open your API client and import the file Set up your environment with the required variables ( host + authorization for Postman/Insomnia, apiKey for Bruno) Activate the environment Pick an endpoint and click Send Full documentation: apidocs.axsmarine.com
  • [Version Guide](https://apidocs.axsmarine.com/api-reference-guide/openapi-export-file/version-guide.md): API Version Format The AXSMarine OpenAPI Specification uses a three-part version number: Plain Text 1 . X . Y │ │ └── Specification structure revision │ └──── API content revision └──────── Major version 1 . X . Y │ │ └── Specification structure revision │ └──── API content revision └──────── Major version What Each Number Means 1 — Major Version Only changes in the event of a fundamental architectural overhaul . Would be communicated in advance as a breaking change. X — API Content Revision Increments every time the API content changes : ➕ An endpoint was added or removed ➕ An HTTP method was added or removed from a path 🔄 A request parameter was added , removed , or modified 🔄 A request or response body schema was updated 🔄 A response status code was added or removed If X changed — review the Release Notes before updating your integration. Y — Specification Structure Revision Increments when the structure or format of the spec changes , but API behaviour is identical : New top-level sections added (e.g. servers , security , tags ) New metadata or extension fields introduced (e.g. x- extensions) Formatting or organisation of the file updated A Y -only bump is always safe — no endpoints or parameters changed. Do I Need to Update My Integration? X changed — ✅ Review the Release Notes — API behaviour changed Only Y changed — ⚡ Re-import the spec file — no logic changes needed Neither changed — ✅ No action needed Reading the Version at a Glance 1.0.0 — Initial release 1.1.0 — API content updated (X bumped) 1.1.1 — Spec structure improved, API content unchanged (Y bumped) 1.2.1 — API content updated again, structure unchanged (X bumped)
• [Dry](https://apidocs.axsmarine.com/rest-api-reference/dry.md): Welcome to the REST API references for DryBulk. You will find in the following pages everything you need to access, test, and use all our APIs related to the Drybulk sector. You need a token to use AXS APIs. In case of any questions, feel free to reach support@axsmarine.com
  • [Dry Polygon Events](https://apidocs.axsmarine.com/rest-api-reference/dry/polygon/dry-events.md): The Polygon Event API enables historical and real-time tracking of dry bulk vessels as they enter or exit defined maritime zones, such as ports, canals, anchorages, terminals, shipyards. By leveraging over 12 years of AXSMarine’s proprietary AIS data, this API provides structured insights into vessel movements across 60,000+ AXSMarine proprietary polygons. A Polygon Event represents a vessel’s movement through a strategically defined maritime zone, triggered when the vessel enters and exits the area. Each event is captured through two key AIS signals: entry (the first AIS signal detected within the polygon) and out (the last AIS signal before the vessel leaves the polygon), as reflected in the API response. Key Features 🚢 Vessel Activity Insights – Identify when a vessel enters and exits a geofenced area using the first and last AIS signals within the polygon. Each “Polygon Event” captures both entry and exit parameters, providing a detailed snapshot of the event. 📍 Geofenced Tracking – Track vessel movements through custom-defined zones including anchorages, canals, terminals, and more using polygon-based detection. ⏱ Event Duration – Calculate time spent within the polygon to support congestion analysis or loading duration metrics. 📊 Time Series Ready – Use historical event data to generate time series charts of port activity, vessel counts, and duration. 🚨 Activity Alerts – Monitor live “open” events to trigger alerts when vessels enter specific zones or are still present within them. 🎯 Flexible Filtering – Apply filters by: Vessel IMO, DWT, or other specifications Polygon ID, name, or type (e.g., anchorage, canal) Entry or exit timestamps and AIS attributes Filtering with is_open_event = true is recommended for tracking real-time vessel activity. 📚 Data Depth – Access a comprehensive archive of over 12 years of dry bulk vessel tracking data, suitable for trend analysis and predictive modeling. 📦 Efficient Pagination – Manage large datasets using link-based pagination via the "links" object (e.g., { "next": "" } ). Results are limited to 10,000 events per page. For handling large datasets, refer to the pagination section . 🧾 Flat Response Format – Structured output designed for easy integration and visualization, compatible with spreadsheets, BI tools, and time series databases. Filter by ancestors The ancestor_polygons parameter is a new filter introduced in the v5 API. It allows you to target events based on the parent (or “ancestor”) of the polygons that contain the event, something that wasn’t possible with the existing parameters in v4. What it does exactly Filters events whose polygon lies inside a parent polygon (e.g., a port, zone). Considers the parent polygon’s type via the polygon_types option. In other words, you must first specify the type of polygon you’re looking for (port, berth, etc.) and then provide the corresponding parent identifiers. Accepted value formats Title Description Title Format Example Explanation UN/LOCODE NLRTM International port code (e.g., Rotterdam). Numeric ID 3989 Internal ID of the parent polygon. Human‑readable name Rotterdam Name of the port or zone. You can provide these values in two ways: Comma‑separated list ancestor_polygons=NL,NLRTM Repeated parameter ancestor_polygons=NL&ancestor_polygons=NLRTM Example request https://apihub.axsmarine.com/dry/ais/event/polygon/v5?polygon_types=zone&ancestor_polygons=NLRTM&page_size=50 In this example, the call will return events located in zone polygons that are contained within the parent polygons identified by the LOCODE NLRTM . Why it’s useful Hierarchical geographic search – you can filter events not only by the polygon of interest but also by the larger geographic area that surrounds it. Noise reduction – by combining polygon_types and ancestor_polygons , you limit results to relevant child polygons of a given geographic structure. In summary, ancestor_polygons adds a layer of hierarchical filtering to requests, improving the accuracy and relevance of results obtained via the v5 API. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to dry bulk vessels , the GraphQL API provides real-time data across all vessel segments , including tankers, gas carriers, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs.
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/dry/polygon/changelog.md): All notable changes to the Dry Polygon Events API are documented on this page. [v6 – 2026‑02‑12] Added New fields entry_raw_destination and out_raw_destination to expose the destination as received by the AIS signal at entry and exit. [v5 – 2025‑11‑12] Added New filter query parameter ancestor_polygons (array of strings) to filter events by the parent polygons that contain the event. More information can be found here. New field event_id to expose the unique identifier of the polygon event. New fields min_speed , max_speed , average_speed to expose speed statistics during the event. [v4 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v3 – 2025‑04‑04] Initial Release
  • [Dry Current Ship Status](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-css.md): The Current Ship Status API provides real-time tracking and monitoring of dry bulk vessels , offering detailed insights into their latest positions, statuses, and operational activities. It enables users to track the most recent vessel positions, ETA and destination, and monitor live maritime movements for enhanced situational awareness. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Live Positioning Data – Access latest cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's current operational status derived from polygon events: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 5,000 vessels per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to dry bulk vessels , the GraphQL API provides real-time data across all vessel segments , including tankers, gas carriers, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. This API provides the latest known status for the dry bulk fleet currently tracked by AXSMarine. All vessels available within the 360 Web Interface are available through this API from their first AIS ping at delivery to their last AIS ping before demolition. Users can query the complete fleet every hour, ensuring up-to-date vessel information. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_teu_from / vessel_teu_to AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Trade Flow – commodities , voyage_type , include_cabotage Pagination – page_size (max 5,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/current/v5?page_size=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/current/v5?page_size=100&vessel_main_statuses=at_berth,at_anchorage" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by trade flow (laden voyages): Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/current/v5?page_size=100&voyage_type=laden&commodities=Coal" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/current/v5?page_size=100&imos=9292228,9123456" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/current/v5?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [📊 Pagination](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-css/dry-css-samples/pagination.md): Simple code snippet to request all results for a query with more than 5 000 results
    • [⚠️ Blackout Events](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-css/dry-css-samples/blackout-events.md): Instant snapshot of all vessels being in blackout (i.e not sending any AIS signal since more than 24 hours) and duration of the blackout event.
    • [⚓ Congestion](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-css/dry-css-samples/congestion.md): Getting all Panamaxes (dwt between 67 000 & 95 000 tons) currently waiting at anchorage off Paranaguá.
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-css/changelog.md): All notable changes to the Dry Current Ship Status API are documented on this page. [v5 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). New Trade Flow fields providing voyage-level information: trade_flow_voyage_id , trade_flow_type ( laden / ballast ), trade_flow_cabotage trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm Departure: trade_flow_departure_from , trade_flow_departure_to , trade_flow_departure_port_id , trade_flow_departure_port_name , trade_flow_departure_country_id , trade_flow_departure_country_name , trade_flow_departure_zone_id , trade_flow_departure_zone_name Arrival: trade_flow_arrival_from , trade_flow_arrival_to , trade_flow_arrival_port_id , trade_flow_arrival_port_name , trade_flow_arrival_country_id , trade_flow_arrival_country_name , trade_flow_arrival_zone_id , trade_flow_arrival_zone_name New filter commodities – filter by commodity names (array). New filter voyage_type – filter by laden or ballast . New filter include_cabotage – include cabotage voyages (boolean). [v4 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v3 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v2 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v1 – 2025‑03‑19] Initial Release
  • [Dry Historical Ship Status](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-hss.md): The Historical Ship Status API provides point-in-time snapshots of all dry bulk vessels being monitored or previously monitored by AXSMarine, offering detailed insights into their historical positions, statuses, and operational activities. For ease of use, these snapshots are available at regular intervals: 00:00, 06:00, 12:00 and 18:00 hours. Even in the event of a temporary loss of visibility (black-out), snapshots remain accessible and display the current status of the vessel as well as the last known information prior to the onset of black-out conditions. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Positioning Data – Access cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's operational status at the time of the snapshot: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 5,000 vessels per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to dry bulk vessels , the GraphQL API provides real-time data across all vessel segments , including tankers, gas carriers, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. In this historical API, Snapshots are available for all vessels from the first AIS signal up to the vessel demolition date. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_teu_from / vessel_teu_to AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Snapshot – snapshot_hours (only 0,6,12,18 ), snapshot_time_from / snapshot_time_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Trade Flow – commodities , voyage_type , include_cabotage Pagination – page_size (max 10,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/historical/v6?page_size=100&snapshot_hours=0" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/historical/v6?page_size=100&vessel_main_statuses=at_berth,at_anchorage&snapshot_hours=0,12" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by trade flow (laden voyages): Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/historical/v6?page_size=100&voyage_type=laden&commodities=Coal" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs and date range: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/historical/v6?page_size=100&imos=9292228,9123456&snapshot_time_from=2025-01-01T00:00:00Z&snapshot_time_to=2025-06-01T00:00:00Z" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/historical/v6?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-hss/changelog.md): All notable changes to the Dry Historical Ship Status API are documented on this page. [v6 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). New Trade Flow fields providing voyage-level information: trade_flow_voyage_id , trade_flow_type ( laden / ballast ), trade_flow_cabotage trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm Departure: trade_flow_departure_from , trade_flow_departure_to , trade_flow_departure_port_id , trade_flow_departure_port_name , trade_flow_departure_country_id , trade_flow_departure_country_name , trade_flow_departure_zone_id , trade_flow_departure_zone_name Arrival: trade_flow_arrival_from , trade_flow_arrival_to , trade_flow_arrival_port_id , trade_flow_arrival_port_name , trade_flow_arrival_country_id , trade_flow_arrival_country_name , trade_flow_arrival_zone_id , trade_flow_arrival_zone_name New filter commodities – filter by commodity names (array). New filter voyage_type – filter by laden or ballast . New filter include_cabotage – include cabotage voyages (boolean). [v5 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v4 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v3 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v2 – 2025‑07‑01] Added New filtering query parameters: Vessel characteristics ( vessel_built_from , vessel_built_to , vessel_beam_from , vessel_beam_to , vessel_loa_from , vessel_loa_to , vessel_draft_from , vessel_draft_to , vessel_dwt_from , vessel_dwt_to , vessel_teu_from , vessel_teu_to ) AIS characteristics ( ais_date_from , ais_date_to , ais_heading_from , ais_heading_to , ais_draft_from , ais_draft_to , ais_speed_from , ais_speed_to ) Snapshot information ( snapshot_hours , snapshot_time_from , snapshot_time_to ) Polygon‑level filtering ( polygon_ids , updated_after ) Expanded the response model with polygon‑event details (zone, port, canal, anchorage, berth, shipyard, blackout). Increased maximum page_size to 10,000 . Updated date‑time examples to include UTC offsets. Added validation for snapshot_hours (only 0,6,12,18 allowed). Changed Renamed time filter parameters: time_from → snapshot_time_from , time_to → snapshot_time_to . Updated page_size description and example to reflect the new limit. Refined field descriptions for consistency. [v1 – 2024‑03‑19] Initial Release
  • [Dry Ship Status Parquet Export](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-status/dry-ship-status-parquet-export.md): The Ship Status Parquet Export API provides access to historical ship status data in Parquet format for the DRY market segment (Dry bulk, MPP, and OBO vessels). This API allows you to download ZIP archives containing Parquet files for a specific year, representing the consolidated historical records for that period. Parquet is a columnar storage format optimized for analytics workloads, making it ideal for large-scale data processing and analysis. The API supports HTTP caching via ETag semantics, allowing efficient incremental updates when historical data is adjusted. Each archive contains the historical state of ship statuses for the requested year. To ensure data accuracy, archives are updated every weekend to include any retrospective adjustments made to the historical records. Key Features 📦 Historical Data Export – Download complete yearly datasets for a specific year (from 2013 onwards) in Parquet format, optimized for long-term trend analysis. 🗜️ ZIP Archive Format – Data is delivered as a ZIP archive containing one or more Parquet files, encompassing all data for the requested year. 🔄 HTTP Caching – Support for ETag-based caching allows clients to check if a year's archive has been updated (e.g., after weekend adjustments) without re-downloading the entire file. 📅 Yearly Archives – Retrieve data by year. The system maintains the most up-to-date version of the data for each year; older versions are replaced by the latest weekend update. ⚡ Efficient Processing – Parquet format enables fast columnar queries and efficient compression, significantly reducing memory and bandwidth usage compared to CSV or JSON. This API is designed for bulk historical retrieval and deep analytics. For real-time status updates, consider using the standard Ship Status API endpoints. Important: The ZIP archives are updated every weekend. If you are maintaining a local copy of historical data, we recommend performing a weekly check using ETags to ensure your local files include the latest adjustments. S3 Redirection The API returns an HTTP redirect (302/307) to a signed Amazon S3 URL where the Parquet archive is stored. Clients must follow redirects to download the actual file. Most HTTP clients (including curl and requests ) follow redirects automatically, but ensure your client is configured to do so. Make sure your HTTP client follows redirects. The initial API response will be a redirect to the S3 URL, and you must follow it to download the archive. Example Requests Basic Request Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -o ship_status_2023.zip The -L flag ensures curl follows redirects to the S3 URL. Request with ETag Caching First request: Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -D headers.txt \ -o ship_status_2023.zip Subsequent request (extract ETag from headers.txt ): Bash curl -X GET "https://apihub.axsmarine.com/dry/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "If-None-Match: \"abc123def456\"" \ -L \ -v If the archive hasn't changed since the last weekend update, you'll receive a 304 Not Modified response. Python Example with ETag Caching Python import requests import os # Configuration SEGMENT = "dry" YEAR = 2023 URL = f"https://apihub.axsmarine.com/{SEGMENT}/ship-status/parquet/v1" API_TOKEN = "YOUR_API_TOKEN" headers = { "Authorization": f"Bearer {API_TOKEN}" } params = {"year": YEAR} # Check if we have a cached ETag locally etag_file = f"etag_{SEGMENT}_{YEAR}.txt" if os.path.exists(etag_file): with open(etag_file, "r") as f: etag = f.read().strip() headers["If-None-Match"] = etag # requests.get() follows redirects automatically by default (allow_redirects=True) response = requests.get(URL, headers=headers, params=params, stream=True) if response.status_code == 304: print(f"Archive for {YEAR} has not changed since last weekend.") elif response.status_code == 200: # Save the new ETag if "ETag" in response.headers: with open(etag_file, "w") as f: f.write(response.headers["ETag"]) # Save the ZIP file using streaming to handle large files efficiently filename = f"ship_status_{SEGMENT}_{YEAR}.zip" with open(filename, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) print(f"Archive for {YEAR} downloaded successfully: {filename}") else: print(f"Error: {response.status_code}") print(response.text) Usage Patterns Weekly Historical Sync Since historical data can be adjusted, it is recommended to sync your local data weekly: Weekend Check : Run your export script every Monday. ETag Validation : Use the stored ETag to check if the specific year has been updated. Refresh Local Data : If a 200 OK is returned, replace your local Parquet files with the new ones from the ZIP. Full History Analysis To build a complete historical database: Date Loop : Iterate through years (from 2013 to current). Download & Extract : Extract the Parquet files from each ZIP. Load into Engine : Use tools like DuckDB , Pandas , or Apache Spark to query across multiple years. Parquet File Structure The ZIP archive contains one or more Parquet files. Content : Ship status records including vessel identifiers, status codes, timestamps, locations, vessel_main_status (operational status: at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea ), and voyage-level trade flow fields ( trade_flow_voyage_id , trade_flow_type , trade_flow_cabotage , trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm , departure/arrival location details). Schema : Self-describing Parquet schema including field names and data types (Integer, String, Timestamp, etc.). Optimized for : Fast filtering by vessel, status type, or specific date ranges within the year. Note: The archives can be quite large (hundreds of megabytes for recent years). Ensure sufficient disk space and use streaming downloads to avoid memory issues.
  • [Dry Countries](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-countries.md)
  • [Dry Zones](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-zones.md)
  • [Dry Coastal Areas](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-coastal-areas.md)
  • [Dry Ports](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-ports/dry-ports.md)
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-ports/changelog.md): All notable changes to the Dry Ports API are documented on this page. [v2 – 2026‑01‑21] Added In the response is added latitude data. In the response is added longitude data .
  • [Dry Canals](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-canals.md)
  • [Dry Shipyards](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-shipyards.md)
  • [Dry Anchorages](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-anchorages.md)
  • [Dry Berths](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-berths.md)
  • [Dry Rivers](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-rivers.md)
  • [Dry Waypoints](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-waypoints.md)
  • [Dry Migrations](https://apidocs.axsmarine.com/rest-api-reference/dry/locations/dry-migrations.md)
  • [Dry Voyages](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-voyages/dry-voyages.md): The Dry Voyages API provides comprehensive tracking and analysis of vessel voyages for the DRY market segment (dry bulk, MPP, and OBO vessels). This REST API enables users to query a paginated list of voyages with a rich set of filters, offering a simpler alternative to the GraphQL endpoint while maintaining powerful filtering capabilities. A voyage represents a complete journey undertaken by a vessel, including loading and discharge operations, port calls, and associated commodities. Each voyage contains detailed information about the vessel, its route, operational metrics, and cargo details. Key Features 🆔 Consistent Voyage Identifier – Every voyage now includes a persistent and unique id field, allowing you to reliably track voyage updates over time. This means you no longer need to pull the entire dataset each time you want to analyze or sync voyage data. 🚢 Comprehensive Voyage Data – Access detailed voyage information including vessel specifications, commodities, port calls, and operational metrics such as speed, duration, and draft measurements. 📍 Port Call Tracking – Track loading and discharge operations with detailed location information including zones, ports, berths, and anchorage data. 📦 Commodity Management – Retrieve comprehensive commodity information including intake volumes (metric tonnes, cubic metres, barrels), boil-off volumes, and charterer details. ⏱ Operational Metrics – Analyze voyage performance with metrics such as average speed, top speed, duration, sea duration, and draft ratios. 🎯 Flexible Filtering – Apply filters by: Voyage type (laden, ballast) Current voyages only Cabotage exclusion Commodities (names, IDs, or groups) Date ranges (start, end, last updated) Load and discharge areas (IDs, names, UNLOCODEs) Vessel specifications (IMO, DWT, LOA, beam, draft, TEU) Vessel segments (dry, mpp, obo), types, and sub-types Predicted voyages inclusion Ship-to-ship operations (load/discharge STS) 📊 Pagination – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🔮 Predicted Voyages – Include predicted voyages in your queries to track future vessel movements and planned operations. This REST endpoint offers a simpler way to get voyage data compared to the GraphQL endpoint. It is perfect for customers who value ease of use over advanced querying capabilities. The API automatically filters results to the DRY market segment (dry, mpp, obo). Example Requests Basic Request CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=10" -H "Authorization: Bearer YOUR_API_TOKEN" Current Voyages Only CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=50&only_current=true" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Vessel Specifications and Date Range CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=50&vessel_dwt_from=50000&vessel_dwt_to=100000&vessel_segments=dry&start_from=2025-01-01&start_to=2025-12-31" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Commodities and Load Areas CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=50&commodities=Iron%20Ore,Coal&load_areas=North%20West%20Africa&exclude_cabotage=true" -H "Authorization: Bearer YOUR_API_TOKEN" Include Predicted Voyages CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=50&include_predicted=true&only_current=true" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Multiple Vessel IMOs CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/v4?page_size=100&vessel_imos=9281906,9123456" -H "Authorization: Bearer YOUR_API_TOKEN" Market Segment This API automatically filters results to the DRY market segment , which includes: dry – Dry bulk carriers mpp – Multi-purpose vessels obo – Oil/Bulk/Ore carriers This API handles large datasets. Results are limited to 10,000 voyages per page. Use pagination to retrieve all results efficiently.
  • [Dry Voyages Parquet Export](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-voyages/dry-voyages-parquet-export.md): The Dry Voyages Parquet Export API provides access to daily snapshot data in Parquet format for the DRY market segment (dry bulk, MPP, and OBO vessels). This API allows you to download ZIP archives containing Parquet files for a specific date, where each archive represents a snapshot of voyage data as it existed on that date. Parquet is a columnar storage format optimized for analytics workloads, making it ideal for large-scale data processing and analysis. The API supports HTTP caching via ETag semantics, allowing efficient incremental updates. Each archive is a daily snapshot of voyage data, not a historical record. The snapshot contains the state of all voyages as they existed on the specified date. Key Features 📦 Bulk Data Export – Download complete daily snapshot datasets for a specific date in Parquet format, optimized for analytics and data processing. 🗜️ ZIP Archive Format – Data is delivered as a ZIP archive containing one or more Parquet files, making it easy to download and process. 🔄 HTTP Caching – Support for ETag-based caching allows clients to efficiently check if data has changed without re-downloading unchanged archives. 📅 Daily Snapshots – Retrieve daily snapshots of voyage data for any date. Each snapshot represents the state of all voyages as they existed on that specific date. ⚡ Efficient Processing – Parquet format enables fast columnar queries and efficient compression, reducing storage and transfer costs. This API is designed for bulk data retrieval and analytics use cases. For real-time or filtered queries, consider using the Dry Voyages API instead. Important : Each archive is a daily snapshot, not a historical record. To track changes over time, you need to download and compare multiple daily snapshots. S3 Redirection The API returns an HTTP redirect (302/307) to a signed S3 URL where the Parquet archive is stored. Clients must follow redirects to download the actual file. Most HTTP clients (including curl and requests ) follow redirects automatically, but ensure your client is configured to do so. Make sure your HTTP client follows redirects. The initial API response will be a redirect to the S3 bucket, and you must follow it to download the archive. Example Requests Basic Request CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -o voyages_2025-12-17.zip The -L flag ensures curl follows redirects to the S3 bucket (this is the default behavior, but explicitly included for clarity). Request with ETag Caching First request: CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -D headers.txt \ -o voyages_2025-12-17.zip Extract ETag from headers.txt (e.g., ETag: "abc123def456" ), then use it in subsequent requests: CURL curl -X GET "https://apihub.axsmarine.com/dry/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "If-None-Match: \"abc123def456\"" \ -L \ -v If the archive hasn't changed, you'll receive a 304 Not Modified response with no body. Python Example with ETag Caching Python import requests import os url = "https://apihub.axsmarine.com/dry/voyage/parquet/v1" headers = { "Authorization": "Bearer YOUR_API_TOKEN" } params = {"date": "2025-12-17"} # Check if we have a cached ETag etag_file = "etag_2025-12-17.txt" if os.path.exists(etag_file): with open(etag_file, "r") as f: etag = f.read().strip() headers["If-None-Match"] = etag # requests.get() follows redirects automatically by default response = requests.get(url, headers=headers, params=params, allow_redirects=True) if response.status_code == 304: print("Archive has not changed since last download") elif response.status_code == 200: # Save the ETag for next time if "ETag" in response.headers: with open(etag_file, "w") as f: f.write(response.headers["ETag"]) # Save the ZIP file with open("voyages_2025-12-17.zip", "wb") as f: f.write(response.content) print("Archive downloaded successfully") elif response.status_code == 404: print("Archive not found for the specified date") print(response.json()) else: print(f"Error: {response.status_code}") print(response.json()) Usage Patterns Daily Snapshot Sync For daily synchronization of voyage snapshot data: Download Today's Snapshot – Download the daily snapshot archive for the target date Store ETag – Save the ETag from the response headers Periodic Checks – On subsequent days, use the stored ETag with If-None-Match header to check if the snapshot has been updated Re-download if Changed – If you receive a 200 response, the snapshot has changed and should be processed Multiple Daily Snapshots Analysis To analyze voyage data across multiple dates using daily snapshots: Date Range Loop – Iterate through dates Download Snapshots – Download each date's snapshot archive Process Parquet Files – Extract and process Parquet files using tools like Pandas, Apache Spark, or DuckDB Compare Snapshots – Compare snapshots across dates to track changes in voyage states over time Batch Processing For batch processing workflows with multiple daily snapshots: Download Multiple Snapshots – Download snapshot archives for multiple dates in parallel Extract Parquet Files – Extract Parquet files from ZIP archives Load into Analytics Engine – Load Parquet files into your analytics platform (e.g., Apache Spark, DuckDB, BigQuery) Snapshot Analysis – Analyze and compare snapshots to understand voyage state changes over time Parquet File Structure The ZIP archive contains one or more Parquet files representing a daily snapshot. The exact structure may vary, but typically includes: Voyage data with all fields from the Dry Voyages API, representing the state of voyages on the specified date Columnar format optimized for analytics queries Compression for efficient storage Daily Snapshots Each archive represents a daily snapshot of voyage data. This means: Snapshot Content : The archive contains the state of all voyages as they existed on the specified date Not Historical Records : Each snapshot is independent and does not contain historical changes or updates State at Date : Voyages are included with their state (status, location, etc.) as of the snapshot date Time Series Analysis : To track changes over time, download and compare multiple daily snapshots Market Segment This API automatically filters results to the DRY market segment , which includes: dry – Dry bulk carriers mpp – Multi-purpose vessels obo – Oil/Bulk/Ore carriers The Parquet files can be large. Ensure you have sufficient storage and bandwidth for downloading and processing the archives. Use ETag caching to avoid unnecessary re-downloads.
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-voyages/changelog.md): All notable changes to the Dry Voyages API are documented on this page. [Voyages v4 – 2026‑02‑09] Removed The following fields have been removed: vessel_built_demolition : The year the vessel was demolished. commodity_intake_cbm : Intake volume in cubic metres. commodity_intake_bbl : Intake volume in barrels. commodity_boil_off_mt : Boil-off volume in metric tonnes. commodity_boil_off_cbm : Boil-off volume in cubic metres. [Voyages v3 – 2026‑01‑09] Initial Release [Voyages Parquet Export v1 – 2026‑01‑09] Initial Release
  • [DRY Trade Flows Grid Summary Analyses](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-grid-summary/dry-trade-flows-grid-summary-analyses.md)
  • [DRY Trade Flows Grid Summary Results](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-grid-summary/dry-trade-flows-grid-summary-results.md)
  • [DRY Trade Flows Voyage Details Results](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-voyage-details/dry-trade-flows-voyage-details-results.md)
  • [DRY Trade Flows Voyage Details Commodities](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-voyage-details/dry-trade-flows-voyage-details-commodities.md)
  • [DRY Trade Flows Voyage Details Waypoints](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-voyage-details/dry-trade-flows-voyage-details-waypoints.md)
  • [DRY Trade Flows Voyage Details Areas](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-voyage-details/dry-trade-flows-voyage-details-areas.md)
  • [DRY Trade Flows Voyage Details Analyses](https://apidocs.axsmarine.com/rest-api-reference/dry/trade-flows/dry-trade-flows-voyage-details/dry-trade-flows-voyage-details-analyses.md)
  • [Dry Trade Flows and Vessel Daily Status Data Generation Time](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-tradeflows-and-daily-status-data-generation-time.md)
  • [Dry Vessel Daily Status](https://apidocs.axsmarine.com/rest-api-reference/dry/vessel-daily-status/searches.md)
  • [Dry Locations](https://apidocs.axsmarine.com/rest-api-reference/dry/vessel-daily-status/aux/locations.md)
  • [Dry Commodities](https://apidocs.axsmarine.com/rest-api-reference/dry/vessel-daily-status/aux/commodities.md)
  • [DRY Shiplist Lists](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-ship-list-1/dry-ship-lists.md)
  • [DRY Vessels in Shiplist List](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-ship-list-1/dry-shiplist-vessels.md)
  • [DRY Shiplist Count](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-ship-list-1/dry-shiplist-counts.md)
  • [DRY Cargobook Lists](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-cargobook-search-1/dry-cargobook-search-lists.md)
  • [DRY Cargobook Cargoes](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-cargobook-search-1/dry-cargobook-search-cargoes.md)
  • [DRY Cargobook Counts](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-cargobook-search-1/dry-cargobook-search-counts-1.md)
  • [Dry Vessels](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-vessels/dry-shipinfo-vessels.md)
  • [Update Dry Vessel](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-vessels/dry-shipinfo-vessels-put.md)
  • [Dry Vessel's Comments](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-comments/dry-shipinfo-comments.md)
  • [Add new Dry Vessel's Comment](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-comments/dry-shipinfo-comments-post.md)
  • [Update existing Dry Vessel's Comment](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-comments/dry-shipinfo-comments-put.md)
  • [Delete existing Dry Vessel's Comment](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-comments/dry-shipinfo-comments-delete.md)
  • [Dry Company's Vessels Tags](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-tags/dry-shipinfo-tags.md)
  • [Add new Dry Company Vessel Tag](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-tags/dry-shipinfo-tags-post.md)
  • [Add new Tag to a Dry Vessel](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-tags/dry-shipinfo-tags-vessels-post.md)
  • [Delete existing Dry Vessel's Tag](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-tags/dry-shipinfo-tags-vessels-delete.md)
  • [Dry Vessel's Exnames](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-exnames/dry-shipinfo-exnames.md)
  • [Add new Dry Vessel's Exname](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-exnames/dry-shipinfo-exnames-post.md)
  • [Update existing Dry Vessel's Exname](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-exnames/dry-shipinfo-exnames-put.md)
  • [Delete existing Dry Vessel's Exname](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-exnames/dry-shipinfo-exnames-delete.md)
  • [Dry Vessel's Last DD](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-last-dd/dry-shipinfo-last-dd.md)
  • [Add new Dry Vessel's Last DD](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-last-dd/dry-shipinfo-last-dd-post.md)
  • [Update existing Dry Vessel's Last DD](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-last-dd/dry-shipinfo-last-dd-put.md)
  • [Delete existing Dry Vessel's Last DD](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-last-dd/dry-shipinfo-last-dd-delete.md)
  • [Dry Vessel's Engines](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-engines/dry-shipinfo-engines.md)
  • [Add new Dry Vessel's Enginee](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-engines/dry-shipinfo-engines-post.md)
  • [Update existing Dry Vessel's Enginee](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-engines/dry-shipinfo-engines-put.md)
  • [Delete existing Dry Vessel's Enginee](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-engines/dry-shipinfo-engines-delete.md)
  • [Dry Vessel's Holds](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-holds/dry-shipinfo-holds.md)
  • [Add new Dry Vessel's Hold](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-holds/dry-shipinfo-holds-post.md)
  • [Update existing Dry Vessel's Hold](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-holds/dry-shipinfo-holds-put.md)
  • [Delete existing Dry Vessel's Hold](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-holds/dry-shipinfo-holds-delete.md)
  • [Dry Vessel's Hatches](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-hatches/dry-shipinfo-holds.md)
  • [Add new Dry Vessel's Hatch](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-hatches/dry-shipinfo-holds-post.md)
  • [Update existing Dry Vessel's Hatch](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-hatches/dry-shipinfo-holds-put.md)
  • [Delete existing Dry Vessel's Hatch](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-hatches/dry-shipinfo-holds-delete.md)
  • [Dry Vessel's Notes](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-notes/dry-shipinfo-notes.md)
  • [Update Dry Vessel's Notes](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/dry-shipinfo-notes/dry-shipinfo-notes-post.md)
  • [Vessels Types](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-type.md)
  • [Vessels Categories](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-categories.md)
  • [Ship Market Statuses](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-statuses.md)
  • [Flags](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-flags.md)
  • [Class Status Codes](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-class-status-codes.md)
  • [Class Societies](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-class-societies.md)
  • [Reason Statuses](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-reason-statuses.md)
  • [Engines Models](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-engines-models.md)
  • [Engines Designs](https://apidocs.axsmarine.com/rest-api-reference/dry/ship-info/aux/dry-shipinfo-engines-designs.md)
  • [DRY Fixtures Search Results](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-fixtures-search-1/results-2.md)
  • [DRY Fixtures Search Proformas](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-fixtures-search-1/proformas-2.md)
  • [DRY AIS Search Results](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-ais-search-1/results.md)
  • [DRY AIS Search Proformas](https://apidocs.axsmarine.com/rest-api-reference/dry/dry-ais-search-1/proformas.md)
• [Tanker](https://apidocs.axsmarine.com/rest-api-reference/tanker.md): Welcome to the REST API references for Tanker. You will find in the following pages everything you need to access, test, and use all our APIs related to the wet, gas & chemicals sectors. You need a token to use AXS APIs. In case of any questions, feel free to reach support@axsmarine.com
  • [Tanker Polygon Events](https://apidocs.axsmarine.com/rest-api-reference/tanker/polygonevents/tan-events.md): The Polygon Event API enables historical and real-time tracking of tanker and gas vessels as they enter or exit defined maritime zones, such as ports, canals, anchorages, terminals, shipyards. By leveraging over 12 years of AXSMarine’s proprietary AIS data, this API provides structured insights into vessel movements across 60,000+ AXSMarine proprietary polygons. A Polygon Event represents a vessel’s movement through a strategically defined maritime zone, triggered when the vessel enters and exits the area. Each event is captured through two key AIS signals: entry (the first AIS signal detected within the polygon) and out (the last AIS signal before the vessel leaves the polygon), as reflected in the API response. Key Features 🚢 Vessel Activity Insights – Identify when a vessel enters and exits a geofenced area using the first and last AIS signals within the polygon. Each “Polygon Event” captures both entry and exit parameters, providing a detailed snapshot of the event. 📍 Geofenced Tracking – Track vessel movements through custom-defined zones including anchorages, canals, terminals, and more using polygon-based detection. ⏱ Event Duration – Calculate time spent within the polygon to support congestion analysis or loading duration metrics. 📊 Time Series Ready – Use historical event data to generate time series charts of port activity, vessel counts, and duration. 🚨 Activity Alerts – Monitor live “open” events to trigger alerts when vessels enter specific zones or are still present within them. 🎯 Flexible Filtering – Apply filters by: Vessel IMO, DWT, or other specifications Polygon ID, name, or type (e.g., anchorage, canal) Entry or exit timestamps and AIS attributes Filtering with is_open_event = true is recommended for tracking real-time vessel activity. 📚 Data Depth – Access a comprehensive archive of over 12 years of tanker and gas vessel tracking data, suitable for trend analysis and predictive modeling. 📦 Efficient Pagination – Manage large datasets using link-based pagination via the "links" object (e.g., { "next": "" } ). Results are limited to 10,000 events per page. For handling large datasets, refer to the pagination section . 🧾 Flat Response Format – Structured output designed for easy integration and visualization, compatible with spreadsheets, BI tools, and time series databases. Filter by ancestors The ancestor_polygons parameter is a new filter introduced in the v5 API. It allows you to target events based on the parent (or “ancestor”) of the polygons that contain the event, something that wasn’t possible with the existing parameters in v4. What it does exactly Filters events whose polygon lies inside a parent polygon (e.g., a port, zone). Considers the parent polygon’s type via the polygon_types option. In other words, you must first specify the type of polygon you’re looking for (port, berth, etc.) and then provide the corresponding parent identifiers. Accepted value formats Title Description Title Format Example Explanation UN/LOCODE NLRTM International port code (e.g., Rotterdam). Numeric ID 3989 Internal ID of the parent polygon. Human‑readable name Rotterdam Name of the port or zone. You can provide these values in two ways: Comma‑separated list ancestor_polygons=NL,NLRTM Repeated parameter ancestor_polygons=NL&ancestor_polygons=NLRTM Example request https://apihub.axsmarine.com/tanker/ais/event/polygon/v5?polygon_types=zone&ancestor_polygons=NLRTM&page_size=50 In this example, the call will return events located in zone polygons that are contained within the parent polygons identified by the LOCODE NLRTM . Why it’s useful Hierarchical geographic search – you can filter events not only by the polygon of interest but also by the larger geographic area that surrounds it. Noise reduction – by combining polygon_types and ancestor_polygons , you limit results to relevant child polygons of a given geographic structure. In summary, ancestor_polygons adds a layer of hierarchical filtering to requests, improving the accuracy and relevance of results obtained via the v5 API. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to tanker vessels , the GraphQL API provides real-time data across all vessel segments , including dry, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs.
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/tanker/polygonevents/changelog.md): All notable changes to the Tanker Polygon Events API are documented on this page. [v6 – 2026‑02‑12] Added New fields entry_raw_destination and out_raw_destination to expose the destination as received by the AIS signal at entry and exit. [v5 – 2025‑11‑12] Added New filter query parameter ancestor_polygons (array of strings) to filter events by the parent polygons that contain the event. More information can be found here. New field event_id to expose the unique identifier of the polygon event. New fields min_speed , max_speed , average_speed to expose speed statistics during the event. [v4 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v3 – 2025‑04‑04] Initial Release
  • [Tanker Current Ship Status](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-css.md): The Current Ship Status API provides real-time tracking and monitoring of tanker vessels , offering detailed insights into their latest positions, statuses, and operational activities. It enables users to track the most recent vessel positions, ETA and destination, and monitor live maritime movements for enhanced situational awareness. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Live Positioning Data – Access latest cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's current operational status derived from polygon events: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 5,000 vessels per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to tanker vessels , the GraphQL API provides real-time data across all vessel segments , including dry, mpp, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. This API provides the latest known status for the entire active tanker fleet currently tracked by AXSMarine. All vessels available within the 360 Web Interface are available through this API from their first AIS ping at delivery to their last AIS ping before demolition. Users can query the complete fleet every hour, ensuring up-to-date vessel information. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_cubic_from / vessel_cubic_to AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Trade Flow – commodities , voyage_type , include_cabotage Pagination – page_size (max 5,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/current/v5?page_size=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/current/v5?page_size=100&vessel_main_statuses=at_berth,at_anchorage" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by trade flow (laden voyages with crude oil): Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/current/v5?page_size=100&voyage_type=laden&commodities=Crude%20Oil" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/current/v5?page_size=100&imos=9292228,9123456" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/current/v5?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [📊 Pagination](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-css/examples/pagination.md): Simple code snippet to request all results for a query with more than 5 000 results
    • [⚠️ Blackout Events](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-css/examples/blackout-events.md): Instant snapshot of all vessels being in blackout (i.e not sending any AIS signal since more than 24 hours) and duration of the blackout event.
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-css/changelog.md): All notable changes to the Tanker Current Ship Status API are documented on this page. [v5 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). New Trade Flow fields providing voyage-level information: trade_flow_voyage_id , trade_flow_type ( laden / ballast ), trade_flow_cabotage trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm Departure: trade_flow_departure_from , trade_flow_departure_to , trade_flow_departure_port_id , trade_flow_departure_port_name , trade_flow_departure_country_id , trade_flow_departure_country_name , trade_flow_departure_zone_id , trade_flow_departure_zone_name Arrival: trade_flow_arrival_from , trade_flow_arrival_to , trade_flow_arrival_port_id , trade_flow_arrival_port_name , trade_flow_arrival_country_id , trade_flow_arrival_country_name , trade_flow_arrival_zone_id , trade_flow_arrival_zone_name New filter commodities – filter by commodity names (array). New filter voyage_type – filter by laden or ballast . New filter include_cabotage – include cabotage voyages (boolean). [v4 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v3 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v2 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v1 – 2025‑03‑19] Initial Release
  • [Tanker Historical Ship Status](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-hss.md): The Historical Ship Status API provides point-in-time snapshots of all tanker vessels being monitored or previously monitored by AXSMarine, offering detailed insights into their historical positions, statuses, and operational activities. For ease of use, these snapshots are available at regular intervals: 00:00, 06:00, 12:00 and 18:00 hours. Even in the event of a temporary loss of visibility (black-out), snapshots remain accessible and display the current status of the vessel as well as the last known information prior to the onset of black-out conditions. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Positioning Data – Access cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's operational status at the time of the snapshot: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 5,000 vessels per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to tanker vessels , the GraphQL API provides real-time data across all vessel segments , including dry, mpp, liners, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. In this historical API, Snapshots are available for all vessels from the first AIS signal up to the vessel demolition date. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_cubic_from / vessel_cubic_to AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Snapshot – snapshot_hours (only 0,6,12,18 ), snapshot_time_from / snapshot_time_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Trade Flow – commodities , voyage_type , include_cabotage Pagination – page_size (max 10,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/historical/v6?page_size=100&snapshot_hours=0" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/historical/v6?page_size=100&vessel_main_statuses=at_berth,at_anchorage&snapshot_hours=0,12" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by trade flow (laden voyages with crude oil): Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/historical/v6?page_size=100&voyage_type=laden&commodities=Crude%20Oil" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs and date range: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/historical/v6?page_size=100&imos=9292228,9123456&snapshot_time_from=2025-01-01T00:00:00Z&snapshot_time_to=2025-06-01T00:00:00Z" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/historical/v6?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tan-hss/changelog.md): All notable changes to the Tanker Historical Ship Status API are documented on this page. [v6 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). New Trade Flow fields providing voyage-level information: trade_flow_voyage_id , trade_flow_type ( laden / ballast ), trade_flow_cabotage trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm Departure: trade_flow_departure_from , trade_flow_departure_to , trade_flow_departure_port_id , trade_flow_departure_port_name , trade_flow_departure_country_id , trade_flow_departure_country_name , trade_flow_departure_zone_id , trade_flow_departure_zone_name Arrival: trade_flow_arrival_from , trade_flow_arrival_to , trade_flow_arrival_port_id , trade_flow_arrival_port_name , trade_flow_arrival_country_id , trade_flow_arrival_country_name , trade_flow_arrival_zone_id , trade_flow_arrival_zone_name New filter commodities – filter by commodity names (array). New filter voyage_type – filter by laden or ballast . New filter include_cabotage – include cabotage voyages (boolean). [v5 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v4 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v3 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v2 – 2025‑07‑01] Added New filtering query parameters: Vessel characteristics ( vessel_built_from , vessel_built_to , vessel_beam_from , vessel_beam_to , vessel_loa_from , vessel_loa_to , vessel_draft_from , vessel_draft_to , vessel_dwt_from , vessel_dwt_to , vessel_teu_from , vessel_teu_to ) AIS characteristics ( ais_date_from , ais_date_to , ais_heading_from , ais_heading_to , ais_draft_from , ais_draft_to , ais_speed_from , ais_speed_to ) Snapshot information ( snapshot_hours , snapshot_time_from , snapshot_time_to ) Polygon‑level filtering ( polygon_ids , updated_after ) Expanded the response model with polygon‑event details (zone, port, canal, anchorage, berth, shipyard, blackout). Increased maximum page_size to 10,000 . Updated date‑time examples to include UTC offsets. Added validation for snapshot_hours (only 0,6,12,18 allowed). Changed Renamed time filter parameters: time_from → snapshot_time_from , time_to → snapshot_time_to . [v1 – 2024‑03‑19] Initial Release
  • [Tanker Ship Status Parquet Export](https://apidocs.axsmarine.com/rest-api-reference/tanker/ss/tanker-ship-status-parquet-export.md): The Ship Status Parquet Export API provides access to historical ship status data in Parquet format for the TANKER market segment (tanker, chemical, LNG, LPG, FSO, and OBO vessels). This API allows you to download ZIP archives containing Parquet files for a specific year, representing the consolidated historical records for that period. Parquet is a columnar storage format optimized for analytics workloads, making it ideal for large-scale data processing and analysis. The API supports HTTP caching via ETag semantics, allowing efficient incremental updates when historical data is adjusted. Each archive contains the historical state of ship statuses for the requested year. To ensure data accuracy, archives are updated every weekend to include any retrospective adjustments made to the historical records. Key Features 📦 Historical Data Export – Download complete yearly datasets for a specific year (from 2013 onwards) in Parquet format, optimized for long-term trend analysis. 🗜️ ZIP Archive Format – Data is delivered as a ZIP archive containing one or more Parquet files, encompassing all data for the requested year. 🔄 HTTP Caching – Support for ETag-based caching allows clients to check if a year's archive has been updated (e.g., after weekend adjustments) without re-downloading the entire file. 📅 Yearly Archives – Retrieve data by year. The system maintains the most up-to-date version of the data for each year; older versions are replaced by the latest weekend update. ⚡ Efficient Processing – Parquet format enables fast columnar queries and efficient compression, significantly reducing memory and bandwidth usage compared to CSV or JSON. This API is designed for bulk historical retrieval and deep analytics. For real-time status updates, consider using the standard Ship Status API endpoints. Important: The ZIP archives are updated every weekend. If you are maintaining a local copy of historical data, we recommend performing a weekly check using ETags to ensure your local files include the latest adjustments. S3 Redirection The API returns an HTTP redirect (302/307) to a signed Amazon S3 URL where the Parquet archive is stored. Clients must follow redirects to download the actual file. Most HTTP clients (including curl and requests ) follow redirects automatically, but ensure your client is configured to do so. Make sure your HTTP client follows redirects. The initial API response will be a redirect to the S3 URL, and you must follow it to download the archive. Example Requests Basic Request Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -o ship_status_2023.zip The -L flag ensures curl follows redirects to the S3 URL. Request with ETag Caching First request: Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -D headers.txt \ -o ship_status_2023.zip Subsequent request (extract ETag from headers.txt ): Bash curl -X GET "https://apihub.axsmarine.com/tanker/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "If-None-Match: \"abc123def456\"" \ -L \ -v If the archive hasn't changed since the last weekend update, you'll receive a 304 Not Modified response. Python Example with ETag Caching Python import requests import os # Configuration SEGMENT = "tanker" YEAR = 2023 URL = f"https://apihub.axsmarine.com/{SEGMENT}/ship-status/parquet/v1" API_TOKEN = "YOUR_API_TOKEN" headers = { "Authorization": f"Bearer {API_TOKEN}" } params = {"year": YEAR} # Check if we have a cached ETag locally etag_file = f"etag_{SEGMENT}_{YEAR}.txt" if os.path.exists(etag_file): with open(etag_file, "r") as f: etag = f.read().strip() headers["If-None-Match"] = etag # requests.get() follows redirects automatically by default (allow_redirects=True) response = requests.get(URL, headers=headers, params=params, stream=True) if response.status_code == 304: print(f"Archive for {YEAR} has not changed since last weekend.") elif response.status_code == 200: # Save the new ETag if "ETag" in response.headers: with open(etag_file, "w") as f: f.write(response.headers["ETag"]) # Save the ZIP file using streaming to handle large files efficiently filename = f"ship_status_{SEGMENT}_{YEAR}.zip" with open(filename, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) print(f"Archive for {YEAR} downloaded successfully: {filename}") else: print(f"Error: {response.status_code}") print(response.text) Usage Patterns Weekly Historical Sync Since historical data can be adjusted, it is recommended to sync your local data weekly: Weekend Check : Run your export script every Monday. ETag Validation : Use the stored ETag to check if the specific year has been updated. Refresh Local Data : If a 200 OK is returned, replace your local Parquet files with the new ones from the ZIP. Full History Analysis To build a complete historical database: Date Loop : Iterate through years (from 2013 to current). Download & Extract : Extract the Parquet files from each ZIP. Load into Engine : Use tools like DuckDB , Pandas , or Apache Spark to query across multiple years. Parquet File Structure The ZIP archive contains one or more Parquet files. Content : Ship status records including vessel identifiers, status codes, timestamps, locations, vessel_main_status (operational status: at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea ), and voyage-level trade flow fields ( trade_flow_voyage_id , trade_flow_type , trade_flow_cabotage , trade_flow_commodity_name , trade_flow_commodity_group , trade_flow_intake_mt , trade_flow_intake_cbm , departure/arrival location details). Schema : Self-describing Parquet schema including field names and data types (Integer, String, Timestamp, etc.). Optimized for : Fast filtering by vessel, status type, or specific date ranges within the year. Note: The archives can be quite large (hundreds of megabytes for recent years). Ensure sufficient disk space and use streaming downloads to avoid memory issues.
  • [Tanker Countries](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-countries.md)
  • [Tanker Zones](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-zones.md)
  • [Tanker Coastal Areas](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-coastal-areas.md)
  • [Tanker Ports](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-ports/tanker-ports.md)
  • [ChangeLog](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-ports/changelog.md): All notable changes to the Tanker Ports API are documented on this page. [v2 – 2026‑01‑21] Added In the response is added latitude data. In the response is added longitude data .
  • [Tanker Canals](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-canals.md)
  • [Tanker Shipyards](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-shipyards.md)
  • [Tanker Anchorages](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-anchorages.md)
  • [Tanker Berths](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-berths.md)
  • [Tanker Rivers](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-rivers.md)
  • [Tanker Waypoints](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-waypoints.md)
  • [Tanker Migrations](https://apidocs.axsmarine.com/rest-api-reference/tanker/locations/tanker-migrations.md)
  • [Tanker Voyages](https://apidocs.axsmarine.com/rest-api-reference/tanker/voyages/tanker-voyages.md): The Tanker Voyages API provides comprehensive tracking and analysis of vessel voyages for the TANKER market segment (tanker, chemical, LNG, LPG, FSO, and OBO vessels). This REST API enables users to query a paginated list of voyages with a rich set of filters, offering a simpler alternative to the GraphQL endpoint while maintaining powerful filtering capabilities. A voyage represents a complete journey undertaken by a vessel, including loading and discharge operations, port calls, and associated commodities. Each voyage contains detailed information about the vessel, its route, operational metrics, and cargo details. Key Features 🆔 Consistent Voyage Identifier – Every voyage now includes a persistent and unique id field, allowing you to reliably track voyage updates over time. This means you no longer need to pull the entire dataset each time you want to analyze or sync voyage data. 🚢 Comprehensive Voyage Data – Access detailed voyage information including vessel specifications, commodities, port calls, and operational metrics such as speed, duration, and draft measurements. 📍 Port Call Tracking – Track loading and discharge operations with detailed location information including zones, ports, berths, and anchorage data. 📦 Commodity Management – Retrieve comprehensive commodity information including intake volumes (metric tonnes, cubic metres, barrels), boil-off volumes, and charterer details. ⏱ Operational Metrics – Analyze voyage performance with metrics such as average speed, top speed, duration, sea duration, and draft ratios. 🎯 Flexible Filtering – Apply filters by: Voyage type (laden, ballast) Current voyages only Cabotage exclusion Commodities (names, IDs, or groups) Date ranges (start, end, last updated) Load and discharge areas (IDs, names, UNLOCODEs) Vessel specifications (IMO, DWT, LOA, beam, draft, cubic capacity) Vessel segments (tanker, chemoil, chemical, lpg, lng, fso, obo), types, and sub-types Fleet names Predicted voyages inclusion Ship-to-ship operations (load/discharge STS) 📊 Pagination – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🔮 Predicted Voyages – Include predicted voyages in your queries to track future vessel movements and planned operations. This REST endpoint offers a simpler way to get voyage data compared to the GraphQL endpoint. It is perfect for customers who value ease of use over advanced querying capabilities. The API automatically filters results to the TANKER market segment (tanker, chemoil, chemical, lpg, lng, fso, obo). Example Requests Basic Request CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=10" -H "Authorization: Bearer YOUR_API_TOKEN" Current Voyages Only CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=50&only_current=true" -H “Authorization: Bearer YOUR_API_TOKEN” Filter by Vessel Specifications and Date Range CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=50&vessel_dwt_from=50000&vessel_dwt_to=100000&vessel_segments=tanker&start_from=2025-01-01&start_to=2025-12-31" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Commodities and Load Areas CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=50&commodities=Crude%20Oil,Clean&load_areas=West%20Africa&exclude_cabotage=true" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Fleet Names CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=50&vessel_fleets=CAPESIDE,SOVCOMFLOT" -H "Authorization: Bearer YOUR_API_TOKEN" Include Predicted Voyages CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=50&include_predicted=true&only_current=true" -H "Authorization: Bearer YOUR_API_TOKEN" Filter by Multiple Vessel IMOs CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/v4?page_size=100&vessel_imos=9292228,9073050" -H "Authorization: Bearer YOUR_API_TOKEN" Market Segment This API automatically filters results to the TANKER market segment , which includes: tanker – Crude oil tankers chemoil – Chemical tankers chemical – Chemical carriers lpg – LPG carriers lng – LNG carriers fso – Floating Storage and Offloading vessels obo – Oil/Bulk/Ore carriers This API handles large datasets. Results are limited to 10,000 voyages per page. Use pagination to retrieve all results efficiently.
  • [Tanker Voyages Parquet Export](https://apidocs.axsmarine.com/rest-api-reference/tanker/voyages/tanker-voyages-parquet-export.md): The Tanker Voyages Parquet Export API provides access to daily snapshot data in Parquet format for the TANKER market segment (tanker, chemical, LNG, LPG, FSO, and OBO vessels). This API allows you to download ZIP archives containing Parquet files for a specific date, where each archive represents a snapshot of voyage data as it existed on that date. Parquet is a columnar storage format optimized for analytics workloads, making it ideal for large-scale data processing and analysis. The API supports HTTP caching via ETag semantics, allowing efficient incremental updates. Each archive is a daily snapshot of voyage data, not a historical record. The snapshot contains the state of all voyages as they existed on the specified date. Key Features 📦 Bulk Data Export – Download complete daily snapshot datasets for a specific date in Parquet format, optimized for analytics and data processing. 🗜️ ZIP Archive Format – Data is delivered as a ZIP archive containing one or more Parquet files, making it easy to download and process. 🔄 HTTP Caching – Support for ETag-based caching allows clients to efficiently check if data has changed without re-downloading unchanged archives. 📅 Daily Snapshots – Retrieve daily snapshots of voyage data for any date. Each snapshot represents the state of all voyages as they existed on that specific date. ⚡ Efficient Processing – Parquet format enables fast columnar queries and efficient compression, reducing storage and transfer costs. This API is designed for bulk data retrieval and analytics use cases. For real-time or filtered queries, consider using the Tanker Voyages API instead. Important : Each archive is a daily snapshot, not a historical record. To track changes over time, you need to download and compare multiple daily snapshots. S3 Redirection The API returns an HTTP redirect (302/307) to a signed S3 URL where the Parquet archive is stored. Clients must follow redirects to download the actual file. Most HTTP clients (including curl and requests ) follow redirects automatically, but ensure your client is configured to do so. Make sure your HTTP client follows redirects. The initial API response will be a redirect to the S3 bucket, and you must follow it to download the archive. Example Requests Basic Request CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -o voyages_2025-12-17.zip The -L flag ensures curl follows redirects to the S3 bucket (this is the default behavior, but explicitly included for clarity). Request with ETag Caching First request: CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -D headers.txt \ -o voyages_2025-12-17.zip Extract ETag from headers.txt (e.g., ETag: "abc123def456" ), then use it in subsequent requests: CURL curl -X GET "https://apihub.axsmarine.com/tanker/voyage/parquet/v1?date=2025-12-17" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "If-None-Match: \"abc123def456\"" \ -L \ -v If the archive hasn't changed, you'll receive a 304 Not Modified response with no body. Python Example with ETag Caching Python import requests import os url = "https://apihub.axsmarine.com/tanker/voyage/parquet/v1" headers = { "Authorization": "Bearer YOUR_API_TOKEN" } params = {"date": "2025-12-17"} # Check if we have a cached ETag etag_file = "etag_2025-12-17.txt" if os.path.exists(etag_file): with open(etag_file, "r") as f: etag = f.read().strip() headers["If-None-Match"] = etag # requests.get() follows redirects automatically by default response = requests.get(url, headers=headers, params=params, allow_redirects=True) if response.status_code == 304: print("Archive has not changed since last download") elif response.status_code == 200: # Save the ETag for next time if "ETag" in response.headers: with open(etag_file, "w") as f: f.write(response.headers["ETag"]) # Save the ZIP file with open("voyages_2025-12-17.zip", "wb") as f: f.write(response.content) print("Archive downloaded successfully") elif response.status_code == 404: print("Archive not found for the specified date") print(response.json()) else: print(f"Error: {response.status_code}") print(response.json()) Usage Patterns Daily Snapshot Sync For daily synchronization of voyage snapshot data: Download Today's Snapshot – Download the daily snapshot archive for the target date Store ETag – Save the ETag from the response headers Periodic Checks – On subsequent days, use the stored ETag with If-None-Match header to check if the snapshot has been updated Re-download if Changed – If you receive a 200 response, the snapshot has changed and should be processed Multiple Daily Snapshots Analysis To analyze voyage data across multiple dates using daily snapshots: Date Range Loop – Iterate through dates Download Snapshots – Download each date's snapshot archive Process Parquet Files – Extract and process Parquet files using tools like Pandas, Apache Spark, or DuckDB Compare Snapshots – Compare snapshots across dates to track changes in voyage states over time Batch Processing For batch processing workflows with multiple daily snapshots: Download Multiple Snapshots – Download snapshot archives for multiple dates in parallel Extract Parquet Files – Extract Parquet files from ZIP archives Load into Analytics Engine – Load Parquet files into your analytics platform (e.g., Apache Spark, DuckDB, BigQuery) Snapshot Analysis – Analyze and compare snapshots to understand voyage state changes over time Parquet File Structure The ZIP archive contains one or more Parquet files representing a daily snapshot. The exact structure may vary, but typically includes: Voyage data with all fields from the Tanker Voyages API, representing the state of voyages on the specified date Columnar format optimized for analytics queries Compression for efficient storage Daily Snapshots Each archive represents a daily snapshot of voyage data. This means: Snapshot Content : The archive contains the state of all voyages as they existed on the specified date Not Historical Records : Each snapshot is independent and does not contain historical changes or updates State at Date : Voyages are included with their state (status, location, etc.) as of the snapshot date Time Series Analysis : To track changes over time, download and compare multiple daily snapshots Market Segment This API automatically filters results to the TANKER market segment , which includes: tanker – Crude oil tankers chemoil – Chemical tankers chemical – Chemical carriers lpg – LPG carriers lng – LNG carriers fso – Floating Storage and Offloading vessels obo – Oil/Bulk/Ore carriers The Parquet files can be large. Ensure you have sufficient storage and bandwidth for downloading and processing the archives. Use ETag caching to avoid unnecessary re-downloads.
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/tanker/voyages/changelog.md): All notable changes to the Tanker Voyages API are documented on this page. [Voyages v4 – 2026‑02‑09] Removed The following fields have been removed: vessel_built_demolition : The year the vessel was demolished. [Voyages v3 – 2026‑01‑09] Initial Release [Voyages Parquet Export v1 – 2026‑01‑09] Initial Release
  • [Tanker Trade Flows Grid Summary Analyses](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/tanker-trade-flows-grid-summary/tanker-trade-flows-grid-summary-analyses.md)
  • [Tanker Trade Flows Grid Summary Results](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/tanker-trade-flows-grid-summary/tanker-trade-flows-grid-summary-results.md)
  • [Trade Flows Voyage Details Results](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/trade-flows-voyage-details/trade-flows-voyage-details-results.md)
  • [Trade Flows Voyage Details Commodities](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/trade-flows-voyage-details/trade-flows-voyage-details-commodities.md)
  • [Trade Flows Voyage Details Waypoints](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/trade-flows-voyage-details/trade-flows-voyage-details-waypoints.md)
  • [Trade Flows Voyage Details Areas](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/trade-flows-voyage-details/trade-flows-voyage-details-areas.md)
  • [Trade Flows Voyage Details Analyses](https://apidocs.axsmarine.com/rest-api-reference/tanker/trade-flows/trade-flows-voyage-details/trade-flows-voyage-details-analyses.md)
  • [Tanker Trade Flows and Vessel Daily Status Data Generation Time](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-tradeflows-and-daily-status-data-generation-time.md)
  • [Tanker Vessel Daily Status](https://apidocs.axsmarine.com/rest-api-reference/tanker/daily-status-1/searches.md)
  • [Tanker Locations](https://apidocs.axsmarine.com/rest-api-reference/tanker/daily-status-1/aux/locations.md)
  • [Tanker Commodities](https://apidocs.axsmarine.com/rest-api-reference/tanker/daily-status-1/aux/commodities.md)
  • [Tanker Vessels in Shiplist List](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-vessel-search/proformas-5.md)
  • [Tanker Shiplist lists](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-vessel-search/results-5.md)
  • [Tanker Vessel](https://apidocs.axsmarine.com/rest-api-reference/tanker/shipinfo/tanker-vessel.md)
  • [Tanker Fixture Search Results](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-fixture-search-1/results-4.md)
  • [Tanker Fixture Search Proformas](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-fixture-search-1/proformas-4.md)
  • [Tanker AIS Search Results](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-ais-search-1/results-3.md)
  • [Tanker AIS Search Proformas](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-ais-search-1/proformas-3.md)
  • [Tanker Positions](https://apidocs.axsmarine.com/rest-api-reference/tanker/tanker-positions.md)
• [Liner](https://apidocs.axsmarine.com/rest-api-reference/liner.md): Welcome to the REST API references for Liner. You will find in the following pages everything you need to access, test, and use all our APIs related to the container sector. You need a token to use AXS APIs. In case of any questions, feel free to reach support@axsmarine.com
  • [Liner Polygon Events](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-events.md): The Polygon Event API enables historical and real-time tracking of containers and passenger vessels as they enter or exit defined maritime zones, such as ports, canals, anchorages, terminals, shipyards. By leveraging over 12 years of AXSMarine’s proprietary AIS data, this API provides structured insights into vessel movements across 60,000+ AXSMarine proprietary polygons. A Polygon Event represents a vessel’s movement through a strategically defined maritime zone, triggered when the vessel enters and exits the area. Each event is captured through two key AIS signals: entry (the first AIS signal detected within the polygon) and out (the last AIS signal before the vessel leaves the polygon), as reflected in the API response. Key Features 🚢 Vessel Activity Insights – Identify when a vessel enters and exits a geofenced area using the first and last AIS signals within the polygon. Each “Polygon Event” captures both entry and exit parameters, providing a detailed snapshot of the event. 📍 Geofenced Tracking – Track vessel movements through custom-defined zones including anchorages, canals, terminals, and more using polygon-based detection. 📌 Service Identification – Each event includes vessel_service_name and vessel_service_id , representing the service the vessel is part of. This enables deeper segmentation of vessel activity based on service context. ⏱ Event Duration – Calculate time spent within the polygon to support congestion analysis or loading duration metrics. 📊 Time Series Ready – Use historical event data to generate time series charts of port activity, vessel counts, and duration. 🚨 Activity Alerts – Monitor live “open” events to trigger alerts when vessels enter specific zones or are still present within them. 🎯 Flexible Filtering – Apply filters by: Vessel IMO, DWT, or other specifications Polygon ID, name, or type (e.g., anchorage, canal) Entry or exit timestamps and AIS attributes Filtering with is_open_event = true is recommended for tracking real-time vessel activity. 📚 Data Depth – Access a comprehensive archive of over 12 years of containers and passenger vessel tracking data, suitable for trend analysis and predictive modeling. 📦 Efficient Pagination – Manage large datasets using link-based pagination via the "links" object (e.g., { "next": "" } ). Results are limited to 10,000 events per page. For handling large datasets, refer to the pagination section . 🧾 Flat Response Format – Structured output designed for easy integration and visualization, compatible with spreadsheets, BI tools, and time series databases. Filter by ancestors The ancestor_polygons parameter is a new filter introduced in the v6 API. It allows you to target events based on the parent (or “ancestor”) of the polygons that contain the event, something that wasn’t possible with the existing parameters in v5. What it does exactly Filters events whose polygon lies inside a parent polygon (e.g., a port, zone). Considers the parent polygon’s type via the polygon_types option. In other words, you must first specify the type of polygon you’re looking for (port, berth, etc.) and then provide the corresponding parent identifiers. Accepted value formats Title Description Title Format Example Explanation UN/LOCODE NLRTM International port code (e.g., Rotterdam). Numeric ID 3989 Internal ID of the parent polygon. Human‑readable name Rotterdam Name of the port or zone. You can provide these values in two ways: Comma‑separated list ancestor_polygons=NL,NLRTM Repeated parameter ancestor_polygons=NL&ancestor_polygons=NLRTM Example request https://apihub.axsmarine.com/liner/ais/event/polygon/v6?polygon_types=zone&ancestor_polygons=NLRTM&page_size=50 In this example, the call will return events located in zone polygons that are contained within the parent polygons identified by the LOCODE NLRTM . Why it’s useful Hierarchical geographic search – you can filter events not only by the polygon of interest but also by the larger geographic area that surrounds it. Noise reduction – by combining polygon_types and ancestor_polygons , you limit results to relevant child polygons of a given geographic structure. In summary, ancestor_polygons adds a layer of hierarchical filtering to requests, improving the accuracy and relevance of results obtained via the v6 API. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to containers and passenger vessels , the GraphQL API provides real-time data across all vessel segments , including dry bulk, gas carriers, tankers, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs.
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-events/changelog.md): All notable changes to the Liner Polygon Events API are documented on this page. [v7 – 2026‑02‑12] Added New fields entry_raw_destination and out_raw_destination to expose the destination as received by the AIS signal at entry and exit. [v6 – 2025‑11‑12] Added New filter query parameter ancestor_polygons (array of strings) to filter events by the parent polygons that contain the event. More information can be found here. New field event_id to expose the unique identifier of the polygon event. New fields min_speed , max_speed , average_speed to expose speed statistics during the event. [v5 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v4 – 2025‑06‑26] Added New service‑id filters: vessel_service_ids and vessel_service_region_ids . New fields vessel_service_name , vessel_service_id . [v3 – 2025‑04‑04] Initial Release
  • [Liner Current Ship Status](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-ship-status/liner-css.md): The Current Ship Status API provides real-time tracking and monitoring of containers and passenger vessels , offering detailed insights into their latest positions, statuses, and operational activities. It enables users to track the most recent vessel positions, ETA and destination, and monitor live maritime movements for enhanced situational awareness. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Live Positioning Data – Access latest cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 📌 Service Identification – Each status includes vessel_service_name and vessel_service_id , representing the service the vessel is part of. This enables deeper segmentation of vessel activity based on service context. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's current operational status derived from polygon events: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 10,000 vessels per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to containers and passenger vessels , the GraphQL API provides real-time data across all vessel segments , including tankers, gas carriers, dry bulk, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. This API provides the latest known status for the liner fleet currently tracked by AXSMarine. All vessels available within the 360 Web Interface are available through this API from their first AIS ping at delivery to their last AIS ping before demolition. Users can query the complete fleet every hour, ensuring up-to-date vessel information. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_teu_from / vessel_teu_to Service – vessel_service_ids , vessel_service_region_ids AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Pagination – page_size (max 10,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/current/v6?page_size=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/current/v6?page_size=100&vessel_main_statuses=at_berth,at_anchorage" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/current/v6?page_size=100&imos=9292228,9123456" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/current/v6?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by service: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/current/v6?page_size=100&vessel_service_ids=123,456" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-ship-status/liner-css/changelog.md): All notable changes to the Liner Current Ship Status API are documented on this page. [v6 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). [v5 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v4 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v3 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v2 – 2025‑06‑26] Added Polygon id filter: polygon_ids . Vessel‑build date filters: vessel_built_from and vessel_built_to . Vessel‑beam filters: vessel_beam_from and vessel_beam_to . Vessel‑loa filters: vessel_loa_from and vessel_loa_to . Vessel‑draft filters: vessel_draft_from and vessel_draft_to . Vessel‑dwt filters: vessel_dwt_from and vessel_dwt_to . Vessel‑TEU filters: vessel_teu_from and vessel_teu_to . Service‑id filters: vessel_service_ids and vessel_service_region_ids . AIS‑date filters: ais_date_from and ais_date_to . AIS‑heading filters: ais_heading_from and ais_heading_to . AIS‑draft filters: ais_draft_from and ais_draft_to . AIS‑speed filters: ais_speed_from and ais_speed_to . Updated updatedAfter parameter name ( updated_after ) retained. New fields vessel_service_name , vessel_service_id . [v1 – 2025‑03‑19] Initial Release
  • [Liner Historical Ship Status](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-ship-status/liner-hss.md): The Historical Ship Status API provides point-in-time snapshots of all containers and passenger vessels being monitored or previously monitored by AXSMarine, offering detailed insights into their historical positions, statuses, and operational activities. For ease of use, these snapshots are available at regular intervals: 00:00, 06:00, 12:00 and 18:00 hours. Even in the event of a temporary loss of visibility (black-out), snapshots remain accessible and display the current status of the vessel as well as the last known information prior to the onset of black-out conditions. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Positioning Data – Access cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 📌 Service Identification – Each status includes vessel_service_name and vessel_service_id , representing the service the vessel is part of. This enables deeper segmentation of vessel activity based on service context. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's operational status at the time of the snapshot: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the vessel_main_statuses parameter. 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. Results are limited to 10,000 statuses per page. For handling large datasets, refer to the pagination section . 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. This API has been designed for simplified use and easy integration. It provides a flat response format that can be easily used as a single-dimensional table. Want more control over your data? Our GraphQL API offers advanced querying capabilities, allowing users to retrieve exactly the information they need. Unlike this REST API, which is dedicated to containers and passenger vessels , the GraphQL API provides real-time data across all vessel segments , including dry, mpp, tankers, and more . Users can customize queries to select specific fields, ensuring efficient data retrieval tailored to their operational needs. In this historical API, Snapshots are available for all vessels from the first AIS signal up to the vessel demolition date. Filtering 🎯 Apply filters by: Vessel – imos , vessel_ids , vessel_dwt_from / vessel_dwt_to , vessel_built_from / vessel_built_to , vessel_beam_from / vessel_beam_to , vessel_loa_from / vessel_loa_to , vessel_draft_from / vessel_draft_to , vessel_teu_from / vessel_teu_to Service – vessel_service_ids , vessel_service_region_ids AIS – ais_date_from / ais_date_to , ais_heading_from / ais_heading_to , ais_draft_from / ais_draft_to , ais_speed_from / ais_speed_to Snapshot – snapshot_hours (only 0,6,12,18 ), snapshot_time_from / snapshot_time_to Polygon – polygon_ids , updated_after Status – vessel_main_statuses , is_in_blackout , destinations Pagination – page_size (max 10,000), after (cursor) Example Requests Basic request: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/historical/v6?page_size=100&snapshot_hours=0" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by main status: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/historical/v6?page_size=100&vessel_main_statuses=at_berth,at_anchorage&snapshot_hours=0,12" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by vessel IMOs and date range: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/historical/v6?page_size=100&imos=9292228,9123456&snapshot_time_from=2025-01-01T00:00:00Z&snapshot_time_to=2025-06-01T00:00:00Z" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by destination: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/historical/v6?page_size=100&destinations=Singapore" \ -H "Authorization: Bearer YOUR_API_TOKEN" Filter by service: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/historical/v6?page_size=100&vessel_service_ids=123,456&snapshot_hours=0" \ -H "Authorization: Bearer YOUR_API_TOKEN"
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-ship-status/liner-hss/changelog.md): All notable changes to the Liner Historical Ship Status API are documented on this page. [v6 – 2026‑05‑21] Added New field vessel_main_status – the vessel's operational status derived from polygon events. Possible values : at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea New filter vessel_main_statuses – filter by one or more main statuses (array). New filter is_in_blackout – filter vessels currently in blackout (boolean). New filter destinations – filter by destination port or country. Accepts location IDs, names, or UN/LOCODE (array). [v5 – 2025‑11‑12] Added New field ais_destination_id to expose the numeric ID of the current destination. New fields anchorage_event_id , berth_event_id , canal_event_id , port_event_id , shipyard_event_id , and zone_event_id to expose the numeric ID of each polygon event. [v4 – 2025‑08‑26] Added New field ais_raw_destination Type : string Description : The raw destination string received by the AIS signal. Example : "SGP" [v3 – 2025‑07‑21] Added New filter query parameter vessel_ids (array of unique vessel IDs) to filter results by internal vessel identifiers. New field vessel_id to expose the unique vessel identifier. [v2 – 2025‑07‑01] Added New filtering query parameters: Vessel characteristics ( vessel_built_from , vessel_built_to , vessel_beam_from , vessel_beam_to , vessel_loa_from , vessel_loa_to , vessel_draft_from , vessel_draft_to , vessel_dwt_from , vessel_dwt_to , vessel_teu_from , vessel_teu_to , vessel_service_ids , vessel_service_region_ids ) AIS characteristics ( ais_date_from , ais_date_to , ais_heading_from , ais_heading_to , ais_draft_from , ais_draft_to , ais_speed_from , ais_speed_to ) Snapshot information ( snapshot_hours , snapshot_time_from , snapshot_time_to ) Polygon‑level filtering ( polygon_ids , updated_after ) Expanded the response model with polygon‑event details (zone, port, canal, anchorage, berth, shipyard, blackout). Increased maximum page_size to 10,000 . Updated date‑time examples to include UTC offsets. Added validation for snapshot_hours (only 0,6,12,18 allowed). Changed Renamed time filter parameters: time_from → snapshot_time_from , time_to → snapshot_time_to . [v1 – 2024‑03‑19] Initial Release
  • [Liner Ship Status Parquet Export](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-ship-status/liner-ship-status-parquet-export.md): The Ship Status Parquet Export API provides access to historical ship status data in Parquet format for the LINER market segment (Liner, MPP, Ropax Ferries, PCTC, Passengers, RORO, REEFER, CONRO, and ROLO vessels). This API allows you to download ZIP archives containing Parquet files for a specific year, representing the consolidated historical records for that period. Parquet is a columnar storage format optimized for analytics workloads, making it ideal for large-scale data processing and analysis. The API supports HTTP caching via ETag semantics, allowing efficient incremental updates when historical data is adjusted. Each archive contains the historical state of ship statuses for the requested year. To ensure data accuracy, archives are updated every weekend to include any retrospective adjustments made to the historical records. Key Features 📦 Historical Data Export – Download complete yearly datasets for a specific year (from 2013 onwards) in Parquet format, optimized for long-term trend analysis. 🗜️ ZIP Archive Format – Data is delivered as a ZIP archive containing one or more Parquet files, encompassing all data for the requested year. 🔄 HTTP Caching – Support for ETag-based caching allows clients to check if a year's archive has been updated (e.g., after weekend adjustments) without re-downloading the entire file. 📅 Yearly Archives – Retrieve data by year. The system maintains the most up-to-date version of the data for each year; older versions are replaced by the latest weekend update. ⚡ Efficient Processing – Parquet format enables fast columnar queries and efficient compression, significantly reducing memory and bandwidth usage compared to CSV or JSON. This API is designed for bulk historical retrieval and deep analytics. For real-time status updates, consider using the standard Ship Status API endpoints. Important: The ZIP archives are updated every weekend. If you are maintaining a local copy of historical data, we recommend performing a weekly check using ETags to ensure your local files include the latest adjustments. S3 Redirection The API returns an HTTP redirect (302/307) to a signed Amazon S3 URL where the Parquet archive is stored. Clients must follow redirects to download the actual file. Most HTTP clients (including curl and requests ) follow redirects automatically, but ensure your client is configured to do so. Make sure your HTTP client follows redirects. The initial API response will be a redirect to the S3 URL, and you must follow it to download the archive. Example Requests Basic Request Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -o ship_status_2023.zip The -L flag ensures curl follows redirects to the S3 URL. Request with ETag Caching First request: Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -L \ -D headers.txt \ -o ship_status_2023.zip Subsequent request (extract ETag from headers.txt ): Bash curl -X GET "https://apihub.axsmarine.com/liner/ship-status/parquet/v1?year=2023" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "If-None-Match: \"abc123def456\"" \ -L \ -v If the archive hasn't changed since the last weekend update, you'll receive a 304 Not Modified response. Python Example with ETag Caching Python import requests import os # Configuration SEGMENT = "liner" YEAR = 2023 URL = f"https://apihub.axsmarine.com/{SEGMENT}/ship-status/parquet/v1" API_TOKEN = "YOUR_API_TOKEN" headers = { "Authorization": f"Bearer {API_TOKEN}" } params = {"year": YEAR} # Check if we have a cached ETag locally etag_file = f"etag_{SEGMENT}_{YEAR}.txt" if os.path.exists(etag_file): with open(etag_file, "r") as f: etag = f.read().strip() headers["If-None-Match"] = etag # requests.get() follows redirects automatically by default (allow_redirects=True) response = requests.get(URL, headers=headers, params=params, stream=True) if response.status_code == 304: print(f"Archive for {YEAR} has not changed since last weekend.") elif response.status_code == 200: # Save the new ETag if "ETag" in response.headers: with open(etag_file, "w") as f: f.write(response.headers["ETag"]) # Save the ZIP file using streaming to handle large files efficiently filename = f"ship_status_{SEGMENT}_{YEAR}.zip" with open(filename, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) print(f"Archive for {YEAR} downloaded successfully: {filename}") else: print(f"Error: {response.status_code}") print(response.text) Usage Patterns Weekly Historical Sync Since historical data can be adjusted, it is recommended to sync your local data weekly: Weekend Check : Run your export script every Monday. ETag Validation : Use the stored ETag to check if the specific year has been updated. Refresh Local Data : If a 200 OK is returned, replace your local Parquet files with the new ones from the ZIP. Full History Analysis To build a complete historical database: Date Loop : Iterate through years (from 2013 to current). Download & Extract : Extract the Parquet files from each ZIP. Load into Engine : Use tools like DuckDB , Pandas , or Apache Spark to query across multiple years. Parquet File Structure The ZIP archive contains one or more Parquet files. Content : Ship status records including vessel identifiers, status codes, timestamps, locations, and vessel_main_status (operational status: at_shipyard , at_berth , at_anchorage , at_canal , at_port , at_sea ). Schema : Self-describing Parquet schema including field names and data types (Integer, String, Timestamp, etc.). Optimized for : Fast filtering by vessel, status type, or specific date ranges within the year. Note: The archives can be quite large (hundreds of megabytes for recent years). Ensure sufficient disk space and use streaming downloads to avoid memory issues.
  • [Liner Transit Time](https://apidocs.axsmarine.com/rest-api-reference/liner/analytics/transit-time.md): Gain comprehensive visibility into direct maritime services connecting two selected ports, without transhipments. This API delivers insights into active services, average measured transit durations, and historical evolution of performance between departure and arrival ports. Key Features 🛳 Service Discovery – Retrieve a list of all shipping services that offer direct connections (no transhipments) between a specified departure port and arrival port. ⚓ Transit & Waiting Durations The dataset provides a complete overview of port-to-port transit durations by accounting for both active voyage and operational delays. It explicitly details the waiting time at the arrival port and time at sea , alongside the total transit time (the sum of time spent at sea and port waiting time). 📈 Historical Evolution – Observe how transit durations have evolved since January 2020, allowing performance benchmarking, seasonal trend analysis, and historical comparisons. 📅 Time Frame Control – Customize your query with flexible date range parameters to analyze services and performance for a specific period. => Once you set up your observation_date & date_window filters, the calculated transit time will integrate all voyage legs that terminated within the date range , starting from { observation_date } up to { date_window } days backward. 🔄 No Transhipment – Results are filtered to include only direct services, ensuring clean routing data without intermediate port handling. 📊 Data Structuring & Pagination – Utilize cursor-based pagination to efficiently navigate large datasets across routes and time frames. 🚀 This API empowers supply chain professionals, port authorities, logistics teams, line managers, shippers, and cargo stakeholders with actionable insights into routing efficiency and service reliability between global port pairs. Methodology Transit time averages are computed based on the following tracking milestones: average_transit_time : Measured from the Port of Loading (POL) terminal departure to the Port of Discharge (POD) waiting area entry. average_arrival_waiting_time : Measured exclusively while the vessel is idling within the POD waiting/anchorage area. average_total_transit_time : The cumulative sum of the active transit time and the arrival waiting time.
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/analytics/transit-time/changelog.md): All notable changes to the Liner Transit Times API are documented on this page. [v2 – 2026‑06‑10] Added New field: average_arrival_waiting_time New field: average_total_transit_time New search filter: vessel_operator ⇒ To restrict the search to only vessels operated by a specific operator Modified filter date_window : it includes now all transits that terminated within the given date window (previous behaviour was inlcuding only transits that started and terminated within this date window) [v1 – 2025‑05‑16] Initial Release
  • [Liner Weekly Capacity](https://apidocs.axsmarine.com/rest-api-reference/liner/analytics/weekly-capacity.md): Track real vessel departures on direct services connecting a selected pair of ports. This API provides granular details on historical and forecasted sailings, enabling users to monitor service frequency, capacity deployment, and upcoming schedules—all without transhipments. Key Features 🛳 Direct Service Mapping – Identify all services offering direct connections (no transhipments) between a specific departure port and arrival port. 📤 Departure-Level Insights – Access real departure events for each direct service, including nominal TEU capacity of each individual sailing. 📅 Historical Trend Analysis – Explore departure history since 2020 to understand trends, patterns, and service regularity over time. ⇒ Week of departure is given in accordance with ISO 8601 standard. 🔮 Forward-Looking Forecasts – Leverage forecasted data to gain visibility into expected sailings in the coming weeks for each service. 📊 Temporal Filtering – Customize queries by time range to isolate specific periods for performance monitoring and planning. 📦 Capacity Monitoring – Monitor fluctuations in nominal TEU across sailings to assess how capacity is allocated and how it evolves over time. 🚀 This API empowers supply chain professionals, port authorities, logistics teams, line managers, shippers, and cargo stakeholders with actionable insights into sailing frequency, capacity trends, and direct service planning between global port pairs.
    • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/analytics/weekly-capacity/changelog.md): All notable changes to the Liner Weekly Capacity API are documented on this page. [v2 – 2026‑06‑10] Added New search filter: max_transit_duration ⇒ To restrict the search to services with a short leg between departure port and arrival port. [v1 – 2025‑05‑16] Initial Release
  • [Liner Predict](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-predictive-schedules.md): Alphaliner Predict API provide daily forecasts of next ports, Estimated Time of Arrival at anchor (ETA), Estimated Time of Berthing at terminal (ETB) and Estimated Time of departure from terminal (ETD) for all Containership fleet since January 2022 as well as comparison with actual arrival times. More than 60 millions data point covering all the fleet with point-in-time information. Key Features 📅 Updated forecasts everyday - Each day and for every vessels, ETA, ETB, ETD are produced for all port calls of the next full rotation (e.g. for a vessel deployed on a 10 ports loop service, we produce forecasted timing for the next 10 port calls). 📊 Dynamic forecast model - Based on avanced statistics and live geofencing, predictions integrate all recent events impacting timings : increasing congestion, re-routing, cleared birth for weather reason, etc. 📈 Point-in-time dataset - Every daily forecasts are stored for increased transparency & data benchmarking. 🔄 Predicted vs Actual - Once realised, every past prediction is compared to actual arrival, berthing & departure times. 🛳 Global coverage - Included all Liner vessels from 400 TEU deployed on a services, with a worlwide coverage. 📦 Full transparency - When prediction is not possible, get a comment explaining why : vessel port call deviating from proforma service's rotation, essel not deployed on a service etc.
  • [Liner Current Services](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/current/liner-current-services.md)
  • [Liner Current Services Ports](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/current/liner-current-services-ports.md)
  • [Liner Current Services Carriers](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/current/liner-current-services-carriers.md)
  • [Liner Current Services Regions](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/current/liner-current-services-regions.md)
  • [Liner Historical Services](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/historical/liner-historical-services.md)
  • [Liner Historical Services Ports](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/historical/liner-historical-services-ports.md)
  • [Liner Historical Services Carriers](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/historical/liner-historical-services-carriers.md)
  • [Liner Historical Services Regions](https://apidocs.axsmarine.com/rest-api-reference/liner/liner-services-1/historical/liner-historical-services-regions.md)
  • [Services](https://apidocs.axsmarine.com/rest-api-reference/liner/aux/services.md)
  • [Regions](https://apidocs.axsmarine.com/rest-api-reference/liner/aux/regions.md)
  • [Liner Zones](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-zones.md)
  • [Liner Countries](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-countries.md)
  • [Liner Coastal Areas](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-coastal-areas.md)
  • [Liner Ports](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-ports/liner-ports.md)
  • [Changelog](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-ports/changelog.md): All notable changes to the Liner Ports API are documented on this page. [v2 – 2026‑01‑21] Added In the response is added latitude data. In the response is added longitude data .
  • [Liner Canals](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-canals.md)
  • [Liner Shipyards](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-shipyards.md)
  • [Liner Anchorages](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-anchorages.md)
  • [Liner Berths](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-berths.md)
  • [Liner Rivers](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-rivers.md)
  • [Liner Waypoints](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-waypoints.md)
  • [Liner Migrations](https://apidocs.axsmarine.com/rest-api-reference/liner/locations/liner-migrations.md)
  • [Liner Vessel](https://apidocs.axsmarine.com/rest-api-reference/liner/shipinfo/liner-vessel.md)
• [Business Manager Search](https://apidocs.axsmarine.com/rest-api-reference/global/business-manager/business-manager-search.md)
• [Business Manager Search Simplified](https://apidocs.axsmarine.com/rest-api-reference/global/business-manager/new-section.md)
• [Business Manager Search Field](https://apidocs.axsmarine.com/rest-api-reference/global/business-manager/business-manager-search-field.md)
• [Business Manager Template](https://apidocs.axsmarine.com/rest-api-reference/global/business-manager/business-manager-template.md)
• [Business Manager](https://apidocs.axsmarine.com/rest-api-reference/global/business-manager/business-manager.md)
• [Baltic Index Definitions](https://apidocs.axsmarine.com/rest-api-reference/global/baltic-index/definitions.md)
• [Baltic Index Spots](https://apidocs.axsmarine.com/rest-api-reference/global/baltic-index/spots.md)
• [Baltic Index Forwards](https://apidocs.axsmarine.com/rest-api-reference/global/baltic-index/forwards.md)
• [Global Merchant Fleet Data](https://apidocs.axsmarine.com/rest-api-reference/global/merchant-fleet-data/global-merchant-fleet-data.md): The Global Merchant Fleet Data provides access to Signal-AXSMarine's vessel database, returning comprehensive specifications for vessels across all market verticals — dry, tanker, gas and liner — in a single response. It consolidates identity, dimensions, ownership, equipment and shipbuilding data into one structured record per vessel. A vessel record aggregates everything known about a ship into one object: its identity (IMO, MMSI, name and ex-names), particulars (type, dimensions, capacity, flag and class), equipment (engines, alternative-fuel readiness, wind propulsion, cranes), and the full chain of ownership and management entities — all returned together. Key Features 🚢 Comprehensive Vessel Specifications – Retrieve basic particulars, detailed technical specs, onboard equipment, ownership and shipbuilding details in a single record per vessel. 🏢 Ownership & Management – Access the complete chain of business entities per vessel — ordering company, beneficial owner, registered owner, shipowner, technical and ISM managers, and commercial operator, plus the parent shipowner and parent commercial operator, each with country and IMO number. ⚙️ Equipment & Propulsion – Inspect engines, scrubbers, alternative-fuel capability and readiness (LNG, LPG, methanol, ammonia, ethane, hydrogen, battery), wind-assisted propulsion systems, cranes and tank capacities. 📊 Range & Capacity Filtering – Narrow results by deadweight, gross/net tonnage, TEU, lane meters and cargo-tank capacity using min/max bounds. 📅 Date Filtering – Filter by built-date range or return only vessels modified since a given date for efficient incremental syncing. 🎯 Flexible Filtering – Apply filters by: Identity – IMO, MMSI, internal ID, current name, or ex-name Classification – type, subtype and status, by name or by ID Size – DWT, gross/net tonnage, TEU, lane meters, cargo-tank capacity Dates – built date range and last-modified date Market – set filter_by_onmarket=true to return only on-market vessels 📦 Pagination & Sorting – Page through large result sets with start and limit , and order results with order_by[] (e.g. order_by[]=name:desc&order_by[]=imo:asc ). All filter parameters are optional and AND-combined; calling the endpoint with no filters returns vessels using the default paging. This REST endpoint takes its input as query-string parameters and returns a flat, structured JSON record per vessel. For a nested response over the same database with richer querying, use the GraphQL endpoint. Vessel Statuses The status response field and the status filter accept the following values (each value is either on-market or off-market): DELIVERED (on-market) — Active and trading; handed over from the yard to the owner and fully operational. LAID UP (on-market) — Temporarily out of service (e.g. low demand); kept idle but maintained for future use. ON ORDER (on-market) — Under construction under a firm, confirmed building contract. OPTION (on-market) — A contractual option to order additional ships on the original contract's terms. PENDING/RUMOUR (on-market) — Rumoured or under consideration; not yet confirmed by a firm contract. UNDER REPAIR (on-market) — Temporarily out of service while undergoing repair or maintenance. UNDER CONVERSION (on-market) — Being converted from one vessel type to another (e.g. tanker to FSO). CANCELLED (off-market) — Order terminated before build; the ship was never constructed. SCRAPPED (off-market) — Dismantled and no longer in existence as an operational vessel. TOTAL LOSS (off-market) — Lost to sinking or severe damage; no longer active or trading.
• [Polygon Events](https://apidocs.axsmarine.com/graphql-api-reference/query/gql-events.md): The Polygon Event API enables historical and real-time tracking of all vessels as they enter or exit defined maritime zones, such as ports, canals, anchorages, terminals, shipyards. By leveraging over 12 years of AXSMarine’s proprietary AIS data, this API provides structured insights into vessel movements across 60 000+ AXSMarine proprietary polygons. A polygon event represents a vessel's movement through a strategically defined maritime zone, triggered when the vessel enters and exits the area. Each event is captured through two key AIS signals: entry (the first AIS signal detected within the polygon) and out (the last AIS signal before the vessel leaves the polygon), as reflected in the API response. Key Features 🚢 Vessel Activity Insights – Identify when a vessel enters and exits a geofenced area using the first and last AIS signals within the polygon. Each “polygon event” captures both entry and exit parameters, providing a detailed snapshot of the event. 📍 Geofenced Tracking – Track vessel movements through custom-defined zones including anchorages, canals, terminals, and more using polygon-based detection. ⏱ Event Duration – Calculate time spent within the polygon to support congestion analysis or loading duration metrics. 📊 Time Series Ready – Use historical event data to generate time series charts of port activity, vessel counts, and duration. 🚨 Activity Alerts – Monitor live “open” events to trigger alerts when vessels enter specific zones or are still present within them. 🎯 Flexible Filtering – Apply filters by: Vessel IMO, DWT, or other specifications Polygon ID, name, or type (e.g., anchorage, canal) Entry or exit timestamps and AIS attributes Filtering with isOpen = true is recommended for tracking real-time vessel activity. 📚 Data Depth – Access a comprehensive archive of over 12 years of vessel tracking data, suitable for trend analysis and predictive modeling. 📦 Efficient Pagination – Handle large result sets with cursor-based pagination. Use tight filters to limit scope and improve performance. The GraphQL endpoint provides enhanced filtering capabilities and returns a richer dataset compared to its RESTful counterparts, albeit with an increase in complexity. Below, we provide illustrative examples to facilitate your utilization of this API. Our REST endpoint Dry or Tanker or Liner offers a simpler way to get what you need. It is perfect for customers who value ease of use over advanced querying capabilities. The purpose of this API is to provide a unified response across all vertical markets that we serve. Two points need to be taken into considerations: Geographic location: While most geographic locations are common across all verticals (e.g. the Port of Rotterdam is identical for dry and tanker vessels), this is not the case for zone locations, which are market-dependent areas and are not shared across verticals. Segments filtering: This API offers greater granularity than REST APIs, which are decoupled by main verticals (dry / tanker). In contrast, this API provides a more detailed list of segments , as shown below: REST Endpoint equivalent Segments Dry Polygon Events ["dry", "mpp", "obo"] Tanker Polygon Events ["tanker", "chemoil", "chemical", "lpg", "lng", "fso", "obo"] Liner Polygon Events ["liner", “mpp”, "ropax_ferry", "pctc", “passenger”, "roro", "reefer", "conro", "rolo"] Advanced Filtering The new filter ancestorPolygons lets you target events that occur within a parent polygon (e.g., a port or broader zone). What is ancestorPolygons? ancestorPolygons restricts the search to events whose child polygon is inside one or more specified parent polygons. It must be used together with polygonTypes to narrow the child type (e.g., anchorage, canal, port ). Value Example Meaning UN/LOCODE "NLRTM" International port code. Numeric ID "3989" Internal AXSMarine ID. Human‑readable name "Rotterdam" Full name of the parent polygon. Example Query GraphQL query GetOpenAnchorages { polygonEvents( first: 50 isOpen: true polygonTypes: ["anchorage"] ancestorPolygons: ["NLRTM"] ) { edges { node { _id isOpen duration polygon { _id name type } vessel { imo name type segment } entryAis { time latitude longitude } outAis { time latitude longitude } } cursor } pageInfo { hasNextPage endCursor } totalCount } } This returns the first 50 open anchorage events that are inside the “NLRTM”(Rotterdam) parent polygons. This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 events per page.
• [Deleted Polygon Events](https://apidocs.axsmarine.com/graphql-api-reference/query/deleted-polygon-events.md): The Deleted Polygon Event API exposes only the polygon events that have been removed from the server’s persistent store . This lightweight stream allows a client to perform an incremental sync : by consuming the deleted events, the client can delete the corresponding records locally, keeping its view of the vessel‑zone activity in lock‑step with the server without pulling the entire dataset again. How It Works Every time a polygon event is deleted on the server (e.g., a cleanup operation, data correction, or re‑processing), the event is pushed to this endpoint. The payload contains the event record that has been removed, including most of the fields that are returned by the Polygon Event API. Clients can consume the stream once, store a cursor (or last‑seen timestamp), and resume from that point in subsequent polls to avoid re‑processing the same records. Key Features Incremental Sync – Clients receive only the changes that matter (deletions), drastically reducing bandwidth and processing overhead. Consistent State – By applying deletions exactly as they happen, the client’s local dataset stays in perfect sync with the server. Low Latency – Polling the deleted‑only stream is lightweight and can be performed frequently (e.g., every 30 min) without impacting overall API throughput. Simplified Logic – Clients don’t need to maintain a full event store; they only need to delete or update entries based on the received payload. Auditability – Each deleted record includes the deleted_at timestamp, enabling traceability and rollback if needed. Integration Checklist Authenticate with your API key/token (the same credentials used for the full Polygon Event API). Poll the endpoint at your chosen interval (e.g., every 30 minutes). Store the latest deleted_at value as a cursor for the next request. Apply deletions to your local data store: Remove the record identified by event_id . Optionally, archive the deleted event for audit purposes. Handle Errors : If a request fails, retry after a back‑off period; on repeated failures, log and alert. You can refer to the Incremental updates of polygon events guide as a use case. What This API Does Not Provide Full polygon event data (only deleted events are returned). Real‑time live “open” events or incremental additions or updates . Historical aggregation or analytics (use the full Polygon Event API for those purposes). Data Retention For storage management, data accessed through this API is retained for 12 months only . Any data older than one year will be automatically deleted. Recommended Usage Pattern Initial Sync – Perform a full pull from the standard Polygon Event API to seed the local store. Continuous Sync – After the initial sync, switch to the Deleted‑Only stream to catch up with any deletions. Periodic Re‑Sync – Every few weeks, perform a full pull again to guard against drift (e.g., missed deletions, client outages). This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 events per page.
• [Current Ship Status](https://apidocs.axsmarine.com/graphql-api-reference/query/gql-css.md): The Current Ship Status API provides real-time tracking and monitoring of all vessels , offering detailed insights into their latest positions, statuses, and operational activities. It enables users to track the most recent vessel positions, ETA and destination, and monitor live maritime movements for enhanced situational awareness. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Live Positioning Data – Access latest cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's current operational status derived from polygon events: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the mainStatuses argument. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. Filter by commodities , voyageType , and includeCabotage . 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. The GraphQL endpoint provides enhanced filtering capabilities and returns a richer dataset compared to its RESTful counterparts, albeit with an increase in complexity. Below, we provide illustrative examples to facilitate your utilization of this API. Our REST endpoint Dry or Tanker or Liner offers a simpler way to get what you need. It is perfect for customers who value ease of use over advanced querying capabilities. The purpose of this API is to provide a unified response across all vertical markets that we serve. Two points need to be taken into considerations: Geographic location: While most geographic locations are common across all verticals (e.g. the Port of Rotterdam is identical for dry and tanker vessels), this is not the case for zone locations, which are market-dependent areas and are not shared across verticals. Segments filtering: This API offers greater granularity than REST APIs, which are decoupled by main verticals (dry / tanker). In contrast, this API provides a more detailed list of segments , as shown below: REST Endpoint equivalent Segments Dry Ship Status ["dry", "mpp", "obo"] Tanker Ship Status ["tanker", "chemoil", "chemical", "lpg", "lng", "fso", "obo"] Liner Ship Status ["liner", “mpp”, "ropax_ferry", "pctc", “passenger”, "roro", "reefer", "conro", "rolo"] This API provides the latest known status for the entire active fleet currently tracked by AXSMarine. All vessels available within the 360 Web Interface are available through this API from their first AIS ping at delivery to their last AIS ping before demolition. Users can query the complete fleet every hour, ensuring up-to-date vessel information. This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 vessels per page.
• [Historical Ship Status](https://apidocs.axsmarine.com/graphql-api-reference/query/gql-hss.md): The Historical Ship Status API provides point-in-time snapshots of all vessels being monitored or previously monitored by AXSMarine, offering detailed insights into their historical positions, statuses, and operational activities. For ease of use, these snapshots are available at regular intervals: 00:00, 06:00, 12:00 and 18:00 hours. Even in the event of a temporary loss of visibility (black-out), snapshots remain accessible and display the current status of the vessel as well as the last known information prior to the onset of black-out conditions. Key Features 🚢 Vessel Details – Retrieve essential vessel specifications, including IMO, name, dwt, nominal draft, type, and flag. 📍 Positioning Data – Access cleaned AIS signals with latitude, longitude, speed, heading, draft, and navigation status. 🗺 Geospatial Insights – Identify vessel presence in specific zones such as ports, canals, berths, anchorages, and shipyards using AXSMarine proprietary polygon-based tracking. ⏳ Destination & ETA – Monitor reported destination and estimated time of arrival. ⚠️ Blackout Events – Detect AIS signal loss or transmission gaps to assess operational reliability and identify potential dark activities, such as intentional tracking disablement. 🏷 Main Status – Get the vessel's operational status at the time of the snapshot: at_shipyard , at_berth , at_anchorage , at_canal , at_port , or at_sea . Filter vessels by one or more statuses using the mainStatuses argument. 🚢 Trade Flow – Access voyage-level trade flow information including voyage type ( laden / ballast ), cabotage flag, commodity details (name, group, intake in MT and CBM), and departure/arrival locations (port, country, zone) with date ranges. Filter by commodities , voyageType , and includeCabotage . 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🚀 This API supports data-driven decision-making for logistics, shipping operations, and supply chain management by providing high-fidelity maritime data. The GraphQL endpoint provides enhanced filtering capabilities and returns a richer dataset compared to its RESTful counterparts, albeit with an increase in complexity. Below, we provide illustrative examples to facilitate your utilization of this API. Our REST endpoint Dry or Tanker or Liner offers a simpler way to get what you need. It is perfect for customers who value ease of use over advanced querying capabilities. The purpose of this API is to provide a unified response across all vertical markets that we serve. Two points need to be taken into considerations: Geographic location: While most geographic locations are common across all verticals (e.g. the Port of Rotterdam is identical for dry and tanker vessels), this is not the case for zone locations, which are market-dependent areas and are not shared across verticals. Segments filtering: This API offers greater granularity than REST APIs, which are decoupled by main verticals (dry / tanker). In contrast, this API provides a more detailed list of segments , as shown below: REST Endpoint equivalent Segments Dry Ship Status ["dry", "mpp", "obo"] Tanker Ship Status ["tanker", "chemoil", "chemical", "lpg", "lng", "fso", "obo"] Liner Ship Status ["liner", “mpp”, "ropax_ferry", "pctc", “passenger”, "roro", "reefer", "conro", "rolo"] In this historical API, Snapshots are available for all vessels from the first AIS signal up to the vessel demolition date. This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 statuses per page.
• [Voyage](https://apidocs.axsmarine.com/graphql-api-reference/query/gql-voyages.md): The Voyage API provides comprehensive tracking and analysis of vessel voyages, enabling users to query a paginated list of voyages with a rich set of filters. This API supports tracking of both current and historical voyages, including predicted voyages, with detailed vessel specifications, commodity information, and port call data. A voyage represents a complete journey undertaken by a vessel, including loading and discharge operations, port calls, and associated commodities. Each voyage contains detailed information about the vessel, its route, operational metrics, and cargo details. Key Features 🆔 Consistent Voyage Identifier – Every voyage now includes a persistent and unique voyageId field, allowing you to reliably track voyage updates over time. This means you no longer need to pull the entire dataset each time you want to analyze or sync voyage data. 🚢 Comprehensive Voyage Data – Access detailed voyage information, including vessel specifications, commodities, port calls, and operational metrics such as speed, duration, and draft measurements. 📍 Port Call Tracking – Track loading and discharge operations with detailed location information, including zones, ports, berths, and anchorage data. 📦 Commodity Management – Retrieve comprehensive commodity information, including intake volumes (metric tonnes, cubic metres, barrels), boil-off volumes, and charterer details. ⏱ Operational Metrics – Analyze voyage performance with metrics such as average speed, top speed, duration, sea duration, and draft ratios. 🎯 Flexible Filtering – Apply filters by: Voyage type (laden, ballast) Current voyages only Cabotage exclusion Commodities (names, IDs, or groups) Date ranges (start, end, last updated) Load and discharge areas (IDs, names, UNLOCODEs) Vessel specifications (IMO, DWT, LOA, beam, draft, TEU, cubic capacity) Vessel segments, types, and sub-types Fleet names Load/discharge status flags Predicted voyages inclusion 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🔮 Predicted Voyages – Include predicted voyages in your queries to track future vessel movements and planned operations. The GraphQL endpoint provides enhanced filtering capabilities and returns a richer dataset compared to its RESTful counterparts, albeit with an increase in complexity. Below, we provide illustrative examples to facilitate your utilization of this API. Our REST endpoint Dry or Tanker offers a simpler way to get what you need. It is perfect for customers who value ease of use over advanced querying capabilities. The purpose of this API is to provide a unified response across all vertical markets that we serve. Two points need to be taken into consideration: Geographic location: While most geographic locations are common across all verticals (e.g., the Port of Rotterdam is identical for dry and tanker vessels), this is not the case for zone locations, which are market-dependent areas and are not shared across verticals. Segments filtering: This API offers greater granularity than REST APIs, which are decoupled by main verticals (dry / tanker). In contrast, this API provides a more detailed list of segments, as shown below: REST Endpoint equivalent Segments Dry Voyages ["dry", "mpp", "obo"] Tanker Voyages ["tanker", "chemoil", "chemical", "lpg", "lng", "fso", "obo"] Default Values The voyages query has the following default values: onlyCurrent : false – Returns both current and historical voyages by default excludeCabotage : false – Includes cabotage voyages by default includePredicted : false – Excludes predicted voyages by default Example Queries Basic Voyage Query GraphQL query GetVoyages { voyages(first: 50) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id type lastUpdated vessel { imo name dwt type } commodities { name group intakeMt } load { port { name } entryDate outDate } disch { port { name } entryDate outDate } } } } } Current Voyages Only GraphQL query GetCurrentVoyages { voyages( first: 100 onlyCurrent: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id type vessel { imo name } load { port { name } } disch { port { name } } } } } } Filter by Vessel Specifications and Date Range GraphQL query GetVoyagesByVesselSpecs { voyages( first: 50 vesselDwt: { from: 50000, to: 100000 } vesselSegments: ["tanker"] start: { from: "2024-01-01", to: "2024-12-31" } ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id vessel { imo name dwt segment } avgSpeed duration load { port { name } } disch { port { name } } } } } } Filter by Commodities and Load Areas GraphQL query GetVoyagesByCommodity { voyages( first: 50 commodities: ["Crude Oil", "Clean"] loadAreas: ["NLRTM", "USNYC"] excludeCabotage: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id commodities { name group intakeMt charterer } load { port { name } zone { name } } vessel { imo name } } } } } Include Predicted Voyages GraphQL query GetVoyagesIncludingPredicted { voyages( first: 50 includePredicted: true onlyCurrent: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id isPredicted type vessel { imo name } load { port { name } } disch { port { name } } } } } } This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 voyages per page. A voyage represents a complete journey undertaken by a vessel, including loading and discharge operations, port calls, and associated commodities. Each voyage contains detailed information about the vessel, its route, operational metrics, and cargo details. Key Features 🆔 Consistent Voyage Identifier – Every voyage now includes a persistent and unique voyageId field, allowing you to reliably track voyage updates over time. This means you no longer need to pull the entire dataset each time you want to analyze or sync voyage data. 🚢 Comprehensive Voyage Data – Access detailed voyage information, including vessel specifications, commodities, port calls, and operational metrics such as speed, duration, and draft measurements. 📍 Port Call Tracking – Track loading and discharge operations with detailed location information, including zones, ports, berths, and anchorage data. 📦 Commodity Management – Retrieve comprehensive commodity information, including intake volumes (metric tonnes, cubic metres, barrels), boil-off volumes, and charterer details. ⏱ Operational Metrics – Analyze voyage performance with metrics such as average speed, top speed, duration, sea duration, and draft ratios. 🎯 Flexible Filtering – Apply filters by: Voyage type (laden, ballast) Current voyages only Cabotage exclusion Commodities (names, IDs, or groups) Date ranges (start, end, last updated) Load and discharge areas (IDs, names, UNLOCODEs) Vessel specifications (IMO, DWT, LOA, beam, draft, TEU, cubic capacity) Vessel segments, types, and sub-types Fleet names Load/discharge status flags Predicted voyages inclusion 📊 Pagination & Query Control – Handle large datasets efficiently with cursor-based pagination for structured data retrieval. 🔮 Predicted Voyages – Include predicted voyages in your queries to track future vessel movements and planned operations. The GraphQL endpoint provides enhanced filtering capabilities and returns a richer dataset compared to its RESTful counterparts, albeit with an increase in complexity. Below, we provide illustrative examples to facilitate your utilization of this API. Our REST endpoint Dry or Tanker offers a simpler way to get what you need. It is perfect for customers who value ease of use over advanced querying capabilities. The purpose of this API is to provide a unified response across all vertical markets that we serve. Two points need to be taken into consideration: Geographic location: While most geographic locations are common across all verticals (e.g., the Port of Rotterdam is identical for dry and tanker vessels), this is not the case for zone locations, which are market-dependent areas and are not shared across verticals. Segments filtering: This API offers greater granularity than REST APIs, which are decoupled by main verticals (dry / tanker). In contrast, this API provides a more detailed list of segments, as shown below: REST Endpoint equivalent Segments Dry Voyages ["dry", "mpp", "obo"] Tanker Voyages ["tanker", "chemoil", "chemical", "lpg", "lng", "fso", "obo"] Default Values The voyages query has the following default values: onlyCurrent : false – Returns both current and historical voyages by default excludeCabotage : false – Includes cabotage voyages by default includePredicted : false – Excludes predicted voyages by default Example Queries Basic Voyage Query GraphQL query GetVoyages { voyages(first: 50) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id type lastUpdated vessel { imo name dwt type } commodities { name group intakeMt } load { port { name } entryDate outDate } disch { port { name } entryDate outDate } } } } } Current Voyages Only GraphQL query GetCurrentVoyages { voyages( first: 100 onlyCurrent: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id type vessel { imo name } load { port { name } } disch { port { name } } } } } } Filter by Vessel Specifications and Date Range GraphQL query GetVoyagesByVesselSpecs { voyages( first: 50 vesselDwt: { from: 50000, to: 100000 } vesselSegments: ["tanker"] start: { from: "2024-01-01", to: "2024-12-31" } ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id vessel { imo name dwt segment } avgSpeed duration load { port { name } } disch { port { name } } } } } } Filter by Commodities and Load Areas GraphQL query GetVoyagesByCommodity { voyages( first: 50 commodities: ["Crude Oil", "Clean"] loadAreas: ["NLRTM", "USNYC"] excludeCabotage: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id commodities { name group intakeMt charterer } load { port { name } zone { name } } vessel { imo name } } } } } Include Predicted Voyages GraphQL query GetVoyagesIncludingPredicted { voyages( first: 50 includePredicted: true onlyCurrent: true ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id isPredicted type vessel { imo name } load { port { name } } disch { port { name } } } } } } This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 voyages per page.
• [Deleted Voyage](https://apidocs.axsmarine.com/graphql-api-reference/query/deleted-voyages.md): The Deleted Voyages API exposes only the voyages that have been removed from the server's persistent store . This lightweight stream allows a client to perform an incremental sync : by consuming the deleted voyages, the client can delete the corresponding records locally, keeping its view of the voyage data in lock-step with the server without pulling the entire dataset again. How It Works Every time a voyage is deleted on the server (e.g., a cleanup operation, data correction, or re-processing), the voyage is pushed to this endpoint. The payload contains the voyage record that has been removed, including the vessel information and the deletion timestamp. Clients can consume the stream once, store a cursor (or last-seen timestamp), and resume from that point in subsequent polls to avoid re-processing the same records. Key Features Incremental Sync – Clients receive only the changes that matter (deletions), drastically reducing bandwidth and processing overhead. Consistent State – By applying deletions exactly as they happen, the client's local dataset stays in perfect sync with the server. Low Latency – Polling the deleted-only stream is lightweight and can be performed frequently (e.g., every 30 min) without impacting overall API throughput. Simplified Logic – Clients don't need to maintain a full voyage store; they only need to delete or update entries based on the received payload. Auditability – Each deleted record includes the deletedAt timestamp, enabling traceability and rollback if needed. Vessel Information – Each deleted voyage includes complete vessel information, allowing clients to identify which vessel's voyage was deleted. Flexible Filtering – Apply filters by: Deletion date/time range Vessel specifications (IMO, DWT, LOA, beam, draft, TEU, cubic capacity) Vessel segments, types, and sub-types Fleet names Vessel build year Integration Checklist Authenticate with your API key/token (the same credentials used for the full Voyages API). Poll the endpoint at your chosen interval (e.g., every day). Store the latest deletedAt value as a cursor for the next request. Apply deletions to your local data store: Remove the record identified by _id . Optionally, archive the deleted voyage for audit purposes. Handle Errors : If a request fails, retry after a back-off period; on repeated failures, log and alert. You can refer to the Incremental updates of polygon events guide as a use case for similar incremental sync patterns. What This API Does Not Provide Full voyage data (only deleted voyages are returned). Real-time live voyages or incremental additions or updates. Historical aggregation or analytics (use the full Voyages API for those purposes). Example Queries Basic Deleted Voyages Query GraphQL query GetDeletedVoyages { deletedVoyages(first: 50) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id deletedAt vessel { imo name dwt type } } } } } Filter by Deletion Date Range GraphQL query GetDeletedVoyagesByDate { deletedVoyages( first: 100 deletedAt: { from: "2025-12-01", to: "2025-12-31" } ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id deletedAt vessel { imo name segment } } } } } Filter by Vessel Specifications GraphQL query GetDeletedVoyagesByVesselSpecs { deletedVoyages( first: 50 vesselDwt: { from: 50000, to: 100000 } vesselSegments: ["tanker"] vesselImos: [89035137, 9063108] ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id deletedAt vessel { imo name dwt segment type } } } } } Incremental Sync Pattern GraphQL query GetDeletedVoyagesSince { deletedVoyages( first: 1000 deletedAt: { from: "2024-12-01T00:00:00Z" } after: "cursor_from_last_request" ) { pageInfo { hasNextPage endCursor } totalCount edges { node { _id deletedAt vessel { imo name } } } } } Recommended Usage Pattern Initial Sync – Perform a full pull from the standard Voyages API to seed the local store. Continuous Sync – After the initial sync, switch to the Deleted-Only stream to catch up with any deletions. Periodic Re-Sync – Every few weeks, perform a full pull again to guard against drift (e.g., missed deletions, client outages). This API is handling large datasets. Please refer to the Pagination documentation for more information. Results are limited to 10,000 deleted voyages per page.
• [Global Merchant Fleet Data](https://apidocs.axsmarine.com/graphql-api-reference/query/global-merchant-fleet-data.md): The Global Merchant Fleet Data provides access to Signal-AXSMarine's vessel database, returning comprehensive specifications for vessels across all market verticals — dry, tanker, gas and liner — in a single response. It consolidates identity, dimensions, ownership, equipment and shipbuilding data into one structured record per vessel. A vessel record aggregates everything known about a ship into one object: its identity (IMO, MMSI, name and ex-names), particulars (type, dimensions, capacity, flag and class), equipment (engines, alternative-fuel readiness, wind propulsion, cranes), and the full chain of ownership and management entities — all returned together. Key Features 🚢 Comprehensive Vessel Specifications – Retrieve basic particulars, detailed technical specs, onboard equipment, ownership and shipbuilding details in a single record per vessel. 🏢 Ownership & Management – Access the complete chain of business entities per vessel — ordering company, beneficial owner, registered owner, shipowner, technical and ISM managers, and commercial operator, plus the parent shipowner and parent commercial operator, each with country and IMO number. ⚙️ Equipment & Propulsion – Inspect engines, scrubbers, alternative-fuel capability and readiness (LNG, LPG, methanol, ammonia, ethane, hydrogen, battery), wind-assisted propulsion systems, cranes and tank capacities. 📊 Range & Capacity Filtering – Narrow results by deadweight, gross/net tonnage, TEU, lane meters and cargo-tank capacity using min/max bounds. 📅 Date Filtering – Filter by built-date range or return only vessels modified since a given date for efficient incremental syncing. 🎯 Flexible Filtering – Apply filters by: Identity – IMO, MMSI, internal ID, current name, or ex-name Classification – type, subtype and status, by name or by ID Size – DWT, gross/net tonnage, TEU, lane meters, cargo-tank capacity Dates – built date range and last-modified date Market – set filterByOnmarket: true to return only on-market vessels 📦 Pagination & Sorting – Page through large result sets with start and limit , and order results with orderBy (e.g. ["name:desc", "imo:asc"] ). All filter parameters are optional and AND-combined; calling the endpoint with no filters returns vessels using the default paging. This GraphQL endpoint takes its input as query variables and returns a nested, structured record per vessel. For a simpler, flat response over the same database, use the REST endpoint ( Global Merchant Fleet Data ). Vessel Statuses The status response field and the status filter accept the following values (each value is either on-market or off-market): DELIVERED (on-market) — Active and trading; handed over from the yard to the owner and fully operational. LAID UP (on-market) — Temporarily out of service (e.g. low demand); kept idle but maintained for future use. ON ORDER (on-market) — Under construction under a firm, confirmed building contract. OPTION (on-market) — A contractual option to order additional ships on the original contract's terms. PENDING/RUMOUR (on-market) — Rumoured or under consideration; not yet confirmed by a firm contract. UNDER REPAIR (on-market) — Temporarily out of service while undergoing repair or maintenance. UNDER CONVERSION (on-market) — Being converted from one vessel type to another (e.g. tanker to FSO). CANCELLED (off-market) — Order terminated before build; the ship was never constructed. SCRAPPED (off-market) — Dismantled and no longer in existence as an operational vessel. TOTAL LOSS (off-market) — Lost to sinking or severe damage; no longer active or trading.
• [Objects](https://apidocs.axsmarine.com/graphql-api-reference/objects.md): Objects in GraphQL represent complex data structures. They define the fields and their types that can be queried in a GraphQL API. Objects can have nested fields and relationships with other objects.
  • [Vessel](https://apidocs.axsmarine.com/graphql-api-reference/objects/vessel.md): The Vessel section allows users to retrieve detailed information about a specific vessel, including its specifications and classifications. By accessing this section, users can gain insights into the characteristics of the vessel, enabling them to make informed decisions related to maritime activities or operations.
  • [AIS](https://apidocs.axsmarine.com/graphql-api-reference/objects/ais.md): The AIS section provides access to data from the Automatic Identification System, allowing users to retrieve real-time information on maritime vessel locations and movements. With this API section, users can track ships, monitor traffic patterns, and enhance maritime navigation and security operations.
• [Enums](https://apidocs.axsmarine.com/graphql-api-reference/enums.md): Enums in GraphQL define a set of possible values for a field. They represent a discrete set of options or states that a field can have. Enums help ensure type safety and provide a clear list of valid values for a field.
  • [Vessel Types](https://apidocs.axsmarine.com/graphql-api-reference/enums/vesseltypeenum.md): Types Subtypes Bulk carrier Aggregates Carrier Bulk Carrier Bulk/Oil Carrier Bulker - Great Lakes Only CABU Carrier Cement Carrier Limestone Carrier Ore Carrier Ore/Oil Carrier Self Discharging Bulk Carrier Wood Chips Carrier Wood Pulp Carrier MPP Bulk/Container Carrier Deck Cargo Ship General Cargo Ship Heavy Lift Cargo Vessel Heavy Load Carrier Multi-Purpose Open Hatch Carrier Palletised Cargo Ship Semi-submersible Heavy Lift Liner - Containership Container Ship Tanker Asphalt Tanker Asphalt/Bitumen Tanker Bitumen Tanker Bunkering Tanker Caprolactam Tanker Chemical Tanker Chemical/Oil Products Tanker CO2 Tanker Coal/Oil Mixture Tanker Crude Oil Tanker Edible Oil Tanker FPSO Fruit Juice Tanker FSO Inland Tanker LNG Bunker Tanker Molasses Tanker Oil Products Tanker Shuttle Tanker Tanker Vegetable Oil Tanker Vessel (function unknown) Water Tanker Wine Tanker Gas carrier Ammonia Carrier FLNG FSRU LNG Tanker LPG Tanker LPG/Ethylene Carrier LPG/LAG Carrier Other Landing craft Leisure Vessel Livestock Carrier Miscellaneous Non Cargo Non Merchant Training Ship Trans Shipment Vessel Waste Disposal Vessel Ro-ro CONRO Ro-Ro Vehicles Carrier Passenger Passenger/General Cargo Ship ROPAX/FERRY Reefer Refrigerated Cargo Ship
  • [Vessel Segments](https://apidocs.axsmarine.com/graphql-api-reference/enums/vesselsegmentsenum.md): Value AXSDry AXSTanker AXSLiner chemical ✅ chemoil ✅ conro ✅ dry ✅ fso ✅ liner ✅ lng ✅ lpg ✅ mpp ✅ ✅ obo ✅ ✅ passenger ✅ pctc ✅ reefer ✅ rolo ✅ ropax_ferry ✅ roro ✅ tanker ✅
  • [Navigation States](https://apidocs.axsmarine.com/graphql-api-reference/enums/navstateenum.md): Possible AIS navState values Under way using its engine Anchored Not under command Has restricted maneuverability Ship draught is limiting its movement Moored (tied to another object to limit free movement) Aground Engaged in fishing Under way sailing Reserved for carrying dangerous goods/harmful substances/marine pollutants) Power-driven vessel towing astern Power-driven vessel pushing ahead/towing alongside Reserved for future use Emergency Undefined (default)
  • [Location Types](https://apidocs.axsmarine.com/graphql-api-reference/enums/location-types.md): Possible Location / Polygon Types This is exhaustive list of location types. Although, we do not create events for all the types. Please see below for the compatibility with the Polygon Events. Polygon Type Compatible with Polygon Events APIs Zone ✅ Country Coastal Area ✅ Port ✅ Canal ✅ Shipyard ✅ Anchorage ✅ Berth ✅ River Waypoint ✅
• [How to track a container vessel?](https://apidocs.axsmarine.com/graphql-api-reference/how-tos/tracking-a-vessel-example-of-a-container-vessel-copy-1.md): Are you willing to track precise movements of a container vessel around the world and follow up which ports it calls over time? This code captures 4 months of history (with 4 points per day) for a containership deployed on a “North Europe – Far East” trade. The result enables you to easily plug the data on a map to visualize the vessel’s passage as per screenshot.
• [How to analyze change of vessel’s draft in Goteborg (port)?](https://apidocs.axsmarine.com/graphql-api-reference/how-tos/congestion-copy-1.md): Are you willing to understand how vessels’ draft adapts based on port calls at all different berths of a port and for all types of vessels? This code captures the variations of draft for all entries and exits of berths in the port of Goteborg for all drybulk, gas, tanker and container vessels over the time. The result enables you to analyze and visualize easily on a graph (see screenshot) the variation based on berths and type of vessels.
• [How to follow trends of passages through Suez Canal?](https://apidocs.axsmarine.com/graphql-api-reference/how-tos/eventsinrotterdam.md): Are you willing to track the trends of passages through the Suez Canal to identify changing trading patterns? This code captures passages through the Canal of Suez (polygon type = canal) for all drybulk, tankers, gas and container vessels. The result enables you to analyze and visualize easily on a graph (see screenshot) the trend. You should be able to easily spot the impact of the start of the conflict arising in the south of the Red Sea and the traffic going down through the Suez Canal after it started.
• [Incremental Updates of Polygon Events](https://apidocs.axsmarine.com/graphql-api-reference/how-tos/incremental-updates-of-polygon-events.md): Goal : retrieve only the events that have changed (added, updated, or deleted) since the last run, without downloading the entire dataset each time. Context : The AXSMarine API exposes two GraphQL endpoints: polygonEvents – the active events. deletedPolygonEvents – the events that have been removed. 1. Prerequisites Step Details Resources 1️⃣ Access Token Obtain your bearer token from AXSMarine and replace the placeholder INSERT MY TOKEN in the script. 2️⃣ Python 3.9+ The script uses requests and pandas . 3️⃣ Persistence A local CSV cache is used; you can swap it for a database or cloud storage if desired. 4️⃣ Timestamp handling lastUpdated is inclusive; subtract 24 h from the last modification time to avoid missing boundary events. 2. API Architecture Plain text # 1. polygonEvents type Query { polygonEvents( first: Int, last: Int, before: String, after: String, isOpen: Boolean, polygonIds: [Int], polygonTypes: [String], entryDate: RangeDate, outDate: RangeDate, entryDraft: RangeFloat, entryHeading: RangeInt, entrySpeed: RangeFloat, outDraft: RangeFloat, outHeading: RangeInt, outSpeed: RangeFloat, duration: RangeInt, lastUpdated: RangeDate, vesselBuilt: RangeDate, vesselBeam: RangeFloat, vesselLoa: RangeFloat, vesselDraft: RangeFloat, vesselDwt: RangeInt, vesselTeu: RangeInt, vesselCubic: RangeInt, vesselIds: [Int], vesselImos: [Int], vesselSegments: [String], vesselTypes: [String], vesselSubtypes: [String], vesselLinerServiceIds: [Int], vesselLinerRegionIds: [Int] ): PolygonEventCursorConnection # 2. deletedPolygonEvents type Query { deletedPolygonEvents( first: Int, last: Int, before: String, after: String, polygonIds: [Int], polygonTypes: [String], deletedAt: RangeDate, vesselIds: [Int], vesselImos: [Int], vesselSegments: [String], vesselTypes: [String], vesselSubtypes: [String] ): deletedPolygonEventCursorConnection } Pagination – Each response returns a pageInfo ( endCursor , startCursor ) and a list of edges . Use after to iterate over the entire set. 3. Workflow Overview Load the local cache (or initialize an empty dataframe). Determine the update window : If a file exists, the last run is its modification time minus 24 h. Otherwise, this is the first run, and we’ll request all events. Query polygonEvents with filters polygonTypes , entryDate , lastUpdated . Loop over pages until the number of records is < pageSize . Merge the new data into the dataframe and deduplicate on _id . Query deletedPolygonEvents for the same window ( deletedAt ). Remove rows that _id appear in the deletion list. Save the final DataFrame to a CSV file. 4. Complete Python Example Tip : Store your token in a .env file or use environment variables; the script uses it in plain text for demonstration. Python #!/usr/bin/env python3 import os import logging import requests import pandas as pd from datetime import datetime, timedelta # -------------------------------------------------------------------- # 1️⃣ Configuration # ------------------------------------------------------------------ TOKEN = "INSERT MY TOKEN" # ← Replace with your token HEADERS = {"Authorization": f"Bearer {TOKEN}"} BASE_URL = "https://apihub.axsmarine.com/global/events/v1" # Example: only retrieve "shipyard" events. POLYGON_TYPES = ["shipyard"] ENTRY_START_DATE = "2025-01-01" # ISO‑8601 CSV_FILE = "2025_shipyard_events.csv" # ------------------------------------------------------------------ # 2️⃣ Load cache (if present) # ------------------------------------------------------------------ last_execution_time: str | None = None data = pd.DataFrame() if os.path.exists(CSV_FILE): # Ensure we don't miss events updated the same day. last_exec_ts = datetime.fromtimestamp(os.path.getmtime(CSV_FILE)) - timedelta(days=1) last_execution_time = last_exec_ts.strftime("%Y-%m-%d") data = pd.read_csv(CSV_FILE) # ------------------------------------------------------------------ # 3️⃣ Generic GraphQL query helper # ------------------------------------------------------------------ def gql_query(query: str, variables: dict) -> dict: """Execute a GraphQL request and return the JSON payload.""" logging.debug(f"Request variables: {variables}") resp = requests.post(BASE_URL, json={"query": query, "variables": variables}, headers=HEADERS) resp.raise_for_status() return resp.json()["data"] # ------------------------------------------------------------------ # 4️⃣ Retrieve active polygon events # ------------------------------------------------------------------ def fetch_polygon_events() -> pd.DataFrame: """Fetch active events, paginating until exhaustion.""" page_size = 5000 variables = { "pageSize": page_size, "polygonTypes": POLYGON_TYPES, "entryDate": {"from": ENTRY_START_DATE}, "lastUpdated": {"from": last_execution_time} if last_execution_time else None, } query = """ query polygonEvents( $pageSize: Int, $afterCursor: String, $polygonTypes: [String], $entryDate: RangeDate, $lastUpdated: RangeDate ) { polygonEvents( first: $pageSize, after: $afterCursor, polygonTypes: $polygonTypes, entryDate: $entryDate, lastUpdated: $lastUpdated ) { pageInfo { endCursor } edges { node { _id polygon { _id, name } vessel { _id, imo, name, type } entryAis { time } outAis { time } lastUpdated } } } } """ all_rows = [] cursor = None while True: variables["afterCursor"] = cursor payload = gql_query(query, variables) edges = payload["polygonEvents"]["edges"] rows = pd.json_normalize([e["node"] for e in edges]) all_rows.append(rows) if len(edges) < page_size: break cursor = payload["polygonEvents"]["pageInfo"]["endCursor"] if all_rows: df = pd.concat(all_rows, ignore_index=True) return df return pd.DataFrame() # ------------------------------------------------------------------ # 5️⃣ Remove deleted events # ------------------------------------------------------------------ def purge_deleted_events(df: pd.DataFrame) -> pd.DataFrame: """Delete rows that match events reported as deleted.""" if last_execution_time is None: # First run → nothing to purge return df page_size = 1000 variables = { "pageSize": page_size, "polygonTypes": POLYGON_TYPES, "deletedAt": {"from": last_execution_time}, } query = """ query deletedPolygonEvents( $pageSize: Int, $afterCursor: String, $polygonTypes: [String], $deletedAt: RangeDate ) { deletedPolygonEvents( first: $pageSize, after: $afterCursor, polygonTypes: $polygonTypes, deletedAt: $deletedAt ) { pageInfo { endCursor } edges { node { _id } } } } """ cursor = None deleted_ids = set() while True: variables["afterCursor"] = cursor payload = gql_query(query, variables) edges = payload["deletedPolygonEvents"]["edges"] deleted_ids.update(e["node"]["_id"] for e in edges) if len(edges) < page_size: break cursor = payload["deletedPolygonEvents"]["pageInfo"]["endCursor"] if deleted_ids: df = df[~df["_id"].isin(deleted_ids)].reset_index(drop=True) return df # ------------------------------------------------------------------ # 6️⃣ Main integration # ------------------------------------------------------------------ def main(data): logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") # 6.1 Fetch new/updated events new_events = fetch_polygon_events() logging.info(f"Fetched {len(new_events)} new/updated events") # 6.2 Merge with existing cache if not data.empty: data = pd.concat([data, new_events], ignore_index=True) data = data.drop_duplicates(subset=["_id"], keep="last") else: data = new_events # 6.3 Remove events that were deleted data = purge_deleted_events(data) logging.info(f"Dataset after purge: {len(data)} records") # 6.4 Persist data.to_csv(CSV_FILE, index=False) logging.info(f"Persisted {CSV_FILE}") if __name__ == "__main__": main(data) Implementation notes pandas.json_normalize flattens the nested GraphQL structure into a tidy dataframe. The lastUpdated filter is inclusive; subtracting 24 h from the file’s mtime guarantees that we don’t miss updates on the boundary day. pageSize can be tuned to match network capacity and available memory. 5. Best Practices Practice Why Secure token Store it in a .env file or environment variable. Limit pageSize Prevent server/client time‑outs. Logging Enable debugging output ( logging ). Error handling Catch HTTP errors ( requests.exceptions.HTTPError ) and retry with exponential back‑off. Unit tests Mock API responses to validate merge and purge logic. Monitoring Run via Cron/Argo‑workflow and track record counts per run. 6. Advanced Use‑Cases Scenario Solution Sync to SQL Use SQLAlchemy to bulk‑load the dataframe. Partitioning Separate CSVs or tables by year/month. Integrity check Store a SHA-256 hash of the payload and verify it each time. 7. Conclusion This approach lets you: Significantly cut down network traffic (only changed data). Keep your local cache fresh (add, update, delete). Easily automate the process with a clear, maintainable script. By following this guide, you can integrate AXSMarine’s polygon events into your document‑management ecosystem while keeping bandwidth and storage usage minimal. 🚀 References GraphQL Cursor Connections Specification pandas.json_normalize requests pandas