API Migration Guide: Unversioned to V1#

This guide details the changes introduced in API V1 and provides details for migrating your existing unversioned integration. The Leviaton API has been redesigned to provide all relevant information in one place. Below are the key changes for each endpoint and where you can get relevant information in the new version of the API.

Identifying Your API Version#

If you are currently using any of the following unversioned API base URLs or endpoints, this migration guide applies to you:

Unversioned API Base URLs: * https://api.leviaton.synmax.com/leviaton-be2/api/v2/analysis_report * https://api.leviaton.synmax.com/leviaton-be2/api/v2/targetd_query * https://api.leviaton.synmax.com/leviaton-be2/api/v2/queryAIS/query * https://api.leviaton.synmax.com/leviaton-be2/api/v2/live_status

Unversioned Endpoints: * POST /analysis_report (with req_report parameter: live_status, route_predictions, overview, or flow_timeseries) * POST /targetd_query * GET /api/v2/queryAIS/query * GET /api/v2/live_status

If you are using any of these endpoints, please review the migration guide below for the specific endpoint you use to understand how to migrate to the V1 API.

/analysis_report (live_status) Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/analysis_report with req_report: "live_status"

New Endpoint: https://leviaton.api.synmax.com/v1/vessels

Optional Endpoints: https://leviaton.api.synmax.com/v1/vessels/details

Summary of Changes#

  • The /analysis_report endpoint with the live_status parameter has been replaced by the dedicated /v1/vessels endpoint.

  • The response structure has been completely redesigned: instead of a job-based response with aggregated summary data, the new endpoint returns a direct array of individual vessel records with detailed information per vessel.

  • The new endpoint provides real-time vessel data with individual vessel attributes such as position, status, capacity, and forecast information.

Endpoint & Method#

Input Parameter Changes#

The old endpoint accepted a request body with req_report parameter specifying the report type. The new endpoint uses a different request structure.

Old Request Structure (``/analysis_report``):

{
  "req_report": "live_status",
  // ... additional parameters based on req_report type
}

The req_report: "live_status" parameter has been removed. The new /v1/vessels endpoint accepts different parameters for filtering vessel data. Please refer to the V1 API documentation for the available filtering options.

Response Body Changes#

The response structure has been completely redesigned. The old endpoint returned a job-based response with nested summary data and aggregated statistics. The new endpoint returns a direct array of vessel objects, each containing detailed information about individual vessels.

Unversioned Response Structure (``live_status``):

{
  "execution_seconds": 0.595,
  "job_id": "51946db6-caad-46e0-8023-81768ed486b5",
  "meta": {
    "epoch": 1762374779.422863,
    "execution": 119,
    "func": "live_status",
    "report_message": "report completed",
    "report_result": {
      "details": {
        "inactive": [
          {
            "imo": 9350927,
            "last_timestamp_position": "2025-08-25T00:40:59"
          }
        ],
        "maintenance": []
      },
      "notes": [/* note strings */],
      "summary": {
        "at_maintenance": 0,
        "at_terminal": 770,
        "balast": 532,
        "datetime": "2025-11-05T20:32:59.420523",
        "epoch": 1762374779,
        "inactive": 64,
        "laden": 289,
        "left_liquefaction_terminal": 289,
        "left_regasification_terminal": 435,
        "lng_fleet_size": 821,
        "lng_volume": 980487592.15,
        "lng_volume_unit": "mcf"
      }
    }
  },
  "state": "SUCCESS",
  "version": "v2"
}

V1 Response Structure:

[
  {
    "vessel_id": "vessel_53488763a",
    "imo": 7361922,
    "mmsi": 538003805,
    "name": "ENERGOS FREEZE",
    "callsign": "V7TH4",
    "length": 287,
    "width": 43,
    "maximum_capacity": 125000.0,
    "maximum_capacity_unit": "CUBIC_METER",
    "is_loaded": null,
    "latitude": 19.71842,
    "longitude": -71.73292,
    "last_ais_signal_timestamp": "2025-10-26 17:51:39",
    "captains_destination": "ATLANTC BASIN",
    "captains_eta": "2025-09-01 10:00:00",
    "vessel_type": "FSRU",
    "forecast_destination_terminal": null,
    "forecast_destination_terminal_id": null,
    "forecast_destination_timestamp": null,
    "status": "ACTIVE",
    "speed": 0.0,
    "heading": 242.0,
    "charterer": null,
    "flag_state": null,
    "first_active_date": null,
    "first_operation_date": null,
    "modified_at": "2025-05-15 16:56:38.600115"
  }
]

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested data, while the new endpoint returns a direct array of vessel objects.

  • Data Granularity: The old endpoint provided aggregated summary statistics (e.g., lng_fleet_size, at_terminal, balast, laden) and lists of inactive vessels. The new endpoint provides individual vessel records with detailed attributes.

  • Vessel Information: The new endpoint includes much more detailed information per vessel, including position (latitude/longitude), vessel characteristics (length, width, capacity), status, forecast data, and operational details.

  • Status Tracking: The old endpoint grouped vessels by status (inactive, at maintenance, at terminal) in summary form. The new endpoint provides individual vessel status per record.

  • No Job ID: The new endpoint does not use an asynchronous job-based pattern; it returns data directly.

/analysis_report (route_predictions) Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/analysis_report with req_report: "route_predictions"

New Endpoints: https://leviaton.api.synmax.com/v1/transactions/forecast (recommended) or https://leviaton.api.synmax.com/v1/vessels

Optional Endpoints: https://leviaton.api.synmax.com/v1/vessels, https://leviaton.api.synmax.com/v1/vessels/details (can be used to supplement the primary endpoint)

Summary of Changes#

  • The /analysis_report endpoint with the route_predictions parameter is best replaced by the /v1/transactions/forecast endpoint for forecasted transaction data, or the /v1/vessels endpoint for current vessel status and positions.

  • The response structure has been completely redesigned: the old endpoint returned simple prediction records with basic route information, while the new endpoints provide comprehensive transaction details (for forecast) or vessel information (for current status) including origin and destination terminals, countries, timestamps, and transaction metadata.

  • The new endpoints include detailed terminal information, country codes, transaction types, and volume data with proper units.

Endpoint & Method#

Input Parameter Changes#

The old endpoint accepted a request body with req_report parameter specifying the report type. The new endpoints use different request structures.

Old Request Structure (``/analysis_report``):

{
  "req_report": "route_predictions",
  // ... additional parameters based on req_report type
}

The req_report: "route_predictions" parameter has been removed. For forecasted route predictions, use the /v1/transactions/forecast endpoint which accepts parameters for filtering forecasted transaction data. Alternatively, use the /v1/vessels endpoint for current vessel status and positions. Please refer to the V1 API documentation for the available filtering options for each endpoint.

Response Body Changes#

The response structure has been completely redesigned. The old endpoint returned simple prediction records with basic route prediction information. The new /v1/transactions/forecast endpoint returns detailed forecasted transaction records with comprehensive origin and destination information, terminal details, and transaction metadata. The /v1/vessels endpoint returns current vessel status and position information.

Unversioned Response Structure (``route_predictions``):

{
  "version": "v2",
  "state": "SUCCESS",
  "job_id": "celery_job_id",
  "meta": {
    "report_result": [/* route_prediction_records */],
    "report_message": "report completed",
    "func": "route_predictions",
    "execution": 119,
    "epoch": 1762374779,
    "code": "[M11S9]"
  },
  "execution_seconds": 0.595
}

Example ``report_result`` record structure:

{
  "imo": 9256767,
  "p_volume": 0.06216216216216216,
  "predicated_rate": 1.0,
  "predicted_polygon": "europe continent",
  "start_polygon": "OTHER",
  "start_terminal_timestamp": "2020-11-28T07:00:02",
  "unit": "LNG_mt"
}

V1 Response Structure (``/v1/transactions/forecast``):

[
  {
    "imo": 7382732,
    "origin_terminal": "Cameroon FLNG",
    "origin_terminal_id": "terminal_f521f8c9f",
    "origin_country": "Cameroon",
    "origin_country_code": "CM",
    "origin_timestamp": "2020-06-24 10:16:04+00",
    "destination_terminal": "Sabine Pass",
    "destination_terminal_id": "terminal_220d7ad08",
    "destination_country": "USA",
    "destination_country_code": "US",
    "destination_timestamp": "2020-07-04 16:55:13+00",
    "loading_origin_terminal": null,
    "loading_origin_terminal_id": null,
    "loading_origin_country": null,
    "loading_origin_country_code": null,
    "loading_origin_timestamp": null,
    "volume": 0.3680382,
    "volume_unit": "bcf",
    "forecasted_transaction": false,
    "transaction_number": null,
    "transaction_type": "loading",
    "forecast_run_at": null,
    "modified_at": "2025-11-05 21:03:26.352993+00"
  }
]

Note: The /v1/vessels endpoint returns a different structure with vessel status, position, and vessel metadata. Use /v1/transactions/forecast for forecasted route predictions similar to the old route_predictions functionality.

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested meta.report_result containing the array of route prediction records. The new /v1/transactions/forecast endpoint returns a direct array of forecasted transaction records without the job wrapper. The /v1/vessels endpoint returns vessel status and position data.

  • Field Names: The old endpoint used p_volume and unit, while the new endpoint uses volume and volume_unit.

  • Prediction vs Transaction: The old endpoint focused on route predictions with predicated_rate and predicted_polygon fields. The new /v1/transactions/forecast endpoint provides forecasted transaction records with predicted origin and destination information. The /v1/vessels endpoint provides current vessel status and positions.

  • Terminal Information: The new endpoint includes detailed terminal information with both names and IDs (origin_terminal, origin_terminal_id, destination_terminal, destination_terminal_id).

  • Country Information: The new endpoint includes country names and ISO country codes (origin_country, origin_country_code, destination_country, destination_country_code).

  • Timestamps: The old endpoint had a single start_terminal_timestamp, while the new endpoint provides separate timestamps for origin and destination (origin_timestamp, destination_timestamp).

  • Transaction Metadata: The new endpoint includes transaction-specific fields such as transaction_type, forecasted_transaction, transaction_number, and forecast_run_at.

  • Loading Information: The new endpoint includes optional loading origin information for more complex transaction scenarios.

  • Data Completeness: The new endpoints provide much more comprehensive information about each transaction or vessel, replacing the simple polygon-based predictions with detailed terminal and country-level data.

  • No Job ID: The new endpoints do not use job IDs; they return data directly in the response body.

  • Synchronous Response: The new endpoints return data synchronously, eliminating the need for job status polling.

  • Endpoint Selection: Use /v1/transactions/forecast for forecasted route predictions (most similar to the old route_predictions functionality). Use /v1/vessels for current vessel status and positions.

/analysis_report (overview) Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/analysis_report with req_report: "overview"

New Endpoint: https://leviaton.api.synmax.com/v1/transactions

Optional Endpoints: https://leviaton.api.synmax.com/v1/vessels, https://leviaton.api.synmax.com/v1/vessels/details

Summary of Changes#

  • The /analysis_report endpoint with the overview parameter has been replaced by the dedicated /v1/transactions endpoint.

  • The old overview endpoint returned processed voyage transaction data with voyage chains, voyage status (Laden/Ballast), and voyage notation (L to R, R to R, etc.). The new endpoint provides raw transaction records that can be processed client-side to recreate the overview functionality.

  • The new endpoint includes comprehensive transaction details including origin and destination terminals, countries, timestamps, volume, and transaction metadata that can be used to build voyage chains and determine voyage status.

Endpoint & Method#

Input Parameter Changes#

The old endpoint accepted a request body with req_report parameter specifying the report type. The new endpoint uses a different request structure.

Old Request Structure (``/analysis_report``):

{
  "req_report": "overview",
  // ... additional parameters based on req_report type
}

The req_report: "overview" parameter has been removed. The new /v1/transactions endpoint accepts different parameters for filtering transactions data, including filters by IMO, country, terminal, date ranges, and transaction type. Please refer to the V1 API documentation for the available filtering options.

Response Body Changes#

The old overview endpoint returned processed voyage transaction records with voyage chains, voyage notation, and voyage status already calculated. The new endpoint returns raw transaction records that contain all the necessary data to recreate the overview functionality through client-side processing.

Unversioned Response Structure (``overview``):

{
  "version": "v2",
  "state": "SUCCESS",
  "job_id": "celery_job_id",
  "meta": {
    "report_result": {
      // Structure varies by format/strategy
      // For 's_voyage' format: DataFrame-like structure with voyage transactions
      // Includes: imo, timestamp_position, timestamp_terminal, terminal_type,
      //           terminal_country, next_terminal, next_country, next_terminal_type,
      //           voyage_tx (e.g., "L to R"), voyage_status ("Laden"/"Ballast"),
      //           volume, etc.
    },
    "query_message": "query completed",
    "func": "report_overview",
    "execution": 119,
    "epoch": 1762374779,
    "code": "[Z03F1]"
  },
  "execution_seconds": 0.595
}

Example ``report_result`` record structure (``s_voyage`` format):

{
  "imo": 9256767,
  "tx": 1,
  "start_date": "2020-11-28T07:00:02",
  "end_date": "2020-12-15T10:30:00",
  "start_country": "Qatar",
  "start_terminal": "terminal_123",
  "end_country": "USA",
  "end_terminal": "terminal_456",
  "voyage_status": "Laden",
  "type": "loading",
  "voyage_tx": "L to R",
  "volume": 0.06216216216216216,
  "units": "LNG_mt"
}

V1 Response Structure:

[
  {
    "imo": 7382732,
    "origin_terminal": "Cameroon FLNG",
    "origin_terminal_id": "terminal_f521f8c9f",
    "origin_country": "Cameroon",
    "origin_country_code": "CM",
    "origin_timestamp": "2020-06-24 10:16:04+00",
    "destination_terminal": "Sabine Pass",
    "destination_terminal_id": "terminal_220d7ad08",
    "destination_country": "USA",
    "destination_country_code": "US",
    "destination_timestamp": "2020-07-04 16:55:13+00",
    "loading_origin_terminal": null,
    "loading_origin_terminal_id": null,
    "loading_origin_country": null,
    "loading_origin_country_code": null,
    "loading_origin_timestamp": null,
    "volume": 0.3680382,
    "volume_unit": "bcf",
    "forecasted_transaction": false,
    "transaction_number": null,
    "transaction_type": "loading",
    "forecast_run_at": null,
    "modified_at": "2025-11-05 21:03:26.352993+00"
  }
]

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested meta.report_result containing the processed voyage transaction records. The new endpoint returns a direct array of transaction records without the job wrapper.

  • Processing Model: The old endpoint returned pre-processed voyage chains with voyage notation (L to R, R to R, etc.) and voyage status (Laden/Ballast) already calculated. The new endpoint provides raw transaction records that require client-side processing to create voyage chains.

  • Field Names: The old endpoint used start_terminal/end_terminal and start_country/end_country, while the new endpoint uses origin_terminal/destination_terminal and origin_country/destination_country.

  • Transaction Sequencing: The old endpoint included a tx (transaction number) field that sequenced transactions per vessel. The new endpoint provides transaction records that can be sorted by IMO and timestamp to recreate voyage sequences.

  • Voyage Notation: The old endpoint included voyage_tx (e.g., “L to R”, “R to R”) and voyage_status (Laden/Ballast) fields. These must be calculated client-side from the transaction data and terminal types.

  • Terminal Information: The new endpoint includes detailed terminal information with both names and IDs (origin_terminal, origin_terminal_id, destination_terminal, destination_terminal_id).

  • Country Information: The new endpoint includes country names and ISO country codes (origin_country, origin_country_code, destination_country, destination_country_code).

  • Timestamps: The old endpoint had start_date and end_date, while the new endpoint provides origin_timestamp and destination_timestamp.

  • Volume Units: The old endpoint used units, while the new endpoint uses volume_unit.

  • Transaction Metadata: The new endpoint includes transaction-specific fields such as transaction_type, forecasted_transaction, and transaction_number.

  • Data Completeness: The new endpoint provides comprehensive transaction data that can be used to recreate the overview report functionality, but requires additional processing to generate voyage chains and voyage notation.

  • Format Variations: The old endpoint’s report_result structure varied by format/strategy (e.g., s_voyage format). The new endpoint provides a consistent structure regardless of query type.

  • No Job ID: The new endpoint does not use job IDs; it returns data directly in the response body.

  • Synchronous Response: The new endpoint returns data synchronously, eliminating the need for job status polling.

/analysis_report (flow_timeseries) Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/analysis_report with req_report: "flow_timeseries"

New Endpoint: https://leviaton.api.synmax.com/v1/volume_flows

Summary of Changes#

  • The /analysis_report endpoint with the flow_timeseries parameter has been replaced by the dedicated /v1/volume_flows endpoint.

  • The response structure has been redesigned to provide time series data with volume and count metrics, including standard deviation calculations for statistical analysis.

  • The new endpoint supports filtering by various dimensions including region, IMO (vessel), country, and other parameters for flexible querying of flow data over time.

Endpoint & Method#

Input Parameter Changes#

The old endpoint accepted a request body with req_report parameter specifying the report type. The new endpoint uses a different request structure.

Old Request Structure (``/analysis_report``):

{
  "req_report": "flow_timeseries",
  // ... additional parameters based on req_report type
}

The req_report: "flow_timeseries" parameter has been removed. The new /v1/volume_flows endpoint accepts different parameters for filtering volume flow data, including filters by region, IMO, country, and other dimensions. Please refer to the V1 API documentation for the available filtering options.

Response Body Changes#

The response structure has been redesigned to provide time series data with aggregated volume and count metrics, along with statistical measures. Each record represents a time point with volume and count data, including standard deviation calculations.

Unversioned Response Structure (``flow_timeseries``):

{
  "version": "v2",
  "state": "SUCCESS",
  "job_id": "celery_job_id",
  "meta": {
    "report_result": {
      "data": {/* timeseries_data */},
      "polygon_order": [/* polygon_names */],
      "volume_unit": "mcf",
      "aggregation": "daily",
      "details": {/* detail_records */},
      "tx_type": "loading"
    },
    "report_message": "report completed",
    "func": "flow_timeseries",
    "execution": 119,
    "epoch": 1762374779,
    "code": "[K83F1]"
  },
  "execution_seconds": 0.595
}

V1 Response Structure:

[
  {
    "timestamp": "2025-12-03T00:00:00",
    "volume": 9.03914164526418,
    "count": 2.4788550697926066,
    "volume_unit": "gas_Bcf",
    "volume_std": 4.835830271670738,
    "count_std": 1.325188734809749
  },
  {
    "timestamp": "2025-12-04T00:00:00",
    "volume": 8.786809869970448,
    "count": 2.423902971396833,
    "volume_unit": "gas_Bcf",
    "volume_std": 4.81684312316682,
    "count_std": 1.326858472572955
  }
]

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested meta.report_result containing the time series data. The new endpoint returns a direct array of time series records without the job wrapper.

  • Time Series Format: The old endpoint’s data field contained pivoted/aggregated time series data. The new endpoint returns an array of time series records, each with a timestamp field representing the time point.

  • Polygon Order: The old endpoint included polygon_order to specify the order of polygons in the response. This ordering must now be handled client-side if needed.

  • Aggregation: The old endpoint specified the aggregation level (daily|weekly|monthly) in the response. The new endpoint provides daily granularity by default, with aggregation performed client-side if needed.

  • Transaction Type: The old endpoint included tx_type to specify the transaction type. The new endpoint provides transaction type filtering through request parameters rather than in the response structure.

  • Details Field: The old endpoint included a details field with detailed transaction records. The new endpoint provides a simplified time series structure; detailed transaction data can be obtained separately from /v1/transactions if needed.

  • Volume and Count Metrics: The new endpoint provides both volume and count metrics, allowing for analysis of both total volume and transaction counts over time.

  • Standard Deviation: The new endpoint includes volume_std and count_std fields, providing statistical measures of uncertainty or variability in the data.

  • Volume Units: Both endpoints support volume units, but the new endpoint uses volume_unit in each record (e.g., gas_Bcf) rather than a single volume_unit at the report level.

  • No Job ID: The new endpoint does not use job IDs; it returns data directly in the response body.

  • Synchronous Response: The new endpoint returns data synchronously, eliminating the need for job status polling.

/targetd_query Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/targetd_query

New Endpoints: https://leviaton.api.synmax.com/v1/vessels, https://leviaton.api.synmax.com/v1/transactions, https://leviaton.api.synmax.com/v1/volume_flows

Summary of Changes#

  • The /targetd_query endpoint has been replaced by multiple dedicated V1 endpoints: /v1/vessels, /v1/transactions, and /v1/volume_flows.

  • The old endpoint executed targeted queries using polygon-based geographic filtering with optional terminal type filtering (Liquefaction/Regasification). The new endpoints provide similar filtering capabilities through different parameter structures.

  • Polygon-based queries must now be implemented client-side by filtering results based on latitude/longitude coordinates, or by using region/country/terminal filters available in the new endpoints.

Endpoint & Method#

Version

HTTP Method & Path

unversioned

POST /targetd_query

v1

POST /v1/vessels

v1

POST /v1/transactions

v1

POST /v1/volume_flows

Input Parameter Changes#

The old endpoint accepted polygon-based queries with the following structure. The new endpoints use different filtering mechanisms:

Old Request Structure (``/targetd_query``):

{
  "req_query": "polygon_data_mapper",
  "polygons": [
    {
      "name": "polygon_name",
      "coords": [[[-71.5, 42.3], [-71.4, 42.4], /* additional coordinate pairs */]],
      "terminal_types": ["L", "R"]
    }
  ]
}

The new endpoints accept filtering parameters such as region, country, terminal, IMO, and date ranges. For polygon-based filtering, you will need to:

  • Vessel Queries: Use /v1/vessels with filters for region, country, or terminal, then filter results client-side by checking if vessel coordinates (latitude, longitude) fall within your polygon boundaries.

  • Transaction Queries: Use /v1/transactions with filters for origin/destination country, terminal, or region, then filter by terminal locations within your polygon areas.

  • Volume Flow Queries: Use /v1/volume_flows with filters for country, region, or terminal to get aggregated flow data for areas that correspond to your polygon queries.

Note: The new endpoints do not support direct polygon coordinate input. Geographic polygon filtering must be implemented client-side by: 1. Querying the appropriate endpoint with available filters (country, region, terminal) 2. Filtering the results to include only records within your polygon boundaries using the latitude/longitude fields for vessels or terminal locations for transactions

Response Body Changes#

The old endpoint returned data based on the req_query parameter and polygon filters. The response structure varied by query type. The new endpoints return structured data arrays that can be filtered client-side to match polygon-based queries.

Key Differences:

  • Polygon Filtering: The old endpoint accepted polygon coordinates directly in the request. The new endpoints require client-side polygon filtering using geographic coordinates from the response data.

  • Terminal Type Filtering: The old endpoint supported filtering by terminal types (L=Liquefaction, R=Regasification) within polygons. The new endpoints provide terminal information through terminal IDs and names, which can be cross-referenced with terminal type data.

  • Geographic Queries: The old endpoint’s polygon-based queries can be recreated by: - Querying /v1/vessels and filtering results where latitude/longitude fall within polygon boundaries - Querying /v1/transactions and filtering by origin/destination terminals located within polygon areas - Querying /v1/volume_flows with country/region filters that correspond to polygon areas

  • Data Structure: The new endpoints provide consistent, well-defined data structures with geographic coordinates (for vessels) and terminal information (for transactions) that enable polygon-based filtering.

  • Flexibility: The new approach allows for more flexible querying, as you can combine multiple filters and then apply polygon boundaries, rather than being limited to polygon-only queries.

/api/v2/queryAIS/query Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/queryAIS/query

New Endpoints: https://leviaton.api.synmax.com/v1/vessels, https://leviaton.api.synmax.com/v1/transactions, https://leviaton.api.synmax.com/v1/transactions/forecast

Summary of Changes#

  • The /api/v2/queryAIS/query endpoint has been replaced and comparable data is now available across multiple dedicated endpoints: /v1/vessels, /v1/transactions, and /v1/transactions/forecast.

  • The old endpoint used an asynchronous job-based response pattern with nested query_result data that varied by query_func parameter. The new endpoints provide direct, synchronous responses with structured data.

  • Different query_func values that were used with queryAIS now map to different V1 endpoints based on the type of data requested.

Endpoint & Method#

Input Parameter Changes#

The query_func parameter that was previously sent to /api/v2/queryAIS/query has been removed. The functionality has been split across multiple dedicated endpoints:

  • Vessel-related queries: Use /v1/vessels to get current vessel status, positions, and vessel information.

  • Historical transaction queries: Use /v1/transactions to get completed transactions with origin and destination details.

  • Forecast transaction queries: Use /v1/transactions/forecast to get predicted future transactions with probability scores.

Each new endpoint accepts different parameters for filtering data. Please refer to the V1 API documentation for the available filtering options for each endpoint.

Response Body Changes#

The old endpoint returned an asynchronous job-based response with nested data structure. The actual query results were contained within the meta.query_result field, and the structure varied based on the query_func parameter. The new endpoints return direct, synchronous responses with consistent data structures.

V2 Response Structure (``queryAIS``):

{
  "version": "v2",
  "state": "SUCCESS",
  "job_id": "celery_job_id",
  "meta": {
    "query_result": {/* actual_data */},
    "query_message": "query completed",
    "func": "query_func_name",
    "execution": 119,
    "epoch": 1762374779
  },
  "execution_seconds": 0.595
}

V1 Response Structures:

The new endpoints return direct arrays of data objects:

``/v1/vessels`` Response:

[
  {
    "vessel_id": "vessel_53488763a",
    "imo": 7361922,
    "mmsi": 538003805,
    "name": "ENERGOS FREEZE",
    "status": "ACTIVE",
    "latitude": 19.71842,
    "longitude": -71.73292,
    "last_ais_signal_timestamp": "2025-10-26 17:51:39",
    "vessel_type": "FSRU",
    "maximum_capacity": 125000.0,
    "maximum_capacity_unit": "CUBIC_METER"
  }
]

``/v1/transactions`` Response:

[
  {
    "imo": 7382732,
    "origin_terminal": "Cameroon FLNG",
    "origin_terminal_id": "terminal_f521f8c9f",
    "origin_country": "Cameroon",
    "origin_country_code": "CM",
    "origin_timestamp": "2020-06-24 10:16:04+00",
    "destination_terminal": "Sabine Pass",
    "destination_terminal_id": "terminal_220d7ad08",
    "destination_country": "USA",
    "destination_country_code": "US",
    "destination_timestamp": "2020-07-04 16:55:13+00",
    "volume": 0.3680382,
    "volume_unit": "bcf",
    "transaction_type": "loading",
    "forecasted_transaction": false
  }
]

``/v1/transactions/forecast`` Response:

[
  {
    "imo": 7382732,
    "origin_terminal": "Cameroon FLNG",
    "origin_terminal_id": "terminal_f521f8c9f",
    "origin_country": "Cameroon",
    "origin_country_code": "CM",
    "origin_timestamp": "2026-06-24 10:16:04+00",
    "destination_terminal": "Sabine Pass",
    "destination_terminal_id": "terminal_220d7ad08",
    "destination_country": "USA",
    "destination_country_code": "US",
    "destination_timestamp": "2026-07-04 16:55:13+00",
    "volume": 0.3680382,
    "volume_unit": "bcf",
    "route_score": 0.85,
    "route_score_weighted_volume": 0.3129,
    "forecasted_transaction": true
  }
]

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested meta.query_result containing the actual data. The new endpoints return direct arrays of data objects without the job wrapper.

  • Asynchronous vs Synchronous: The old endpoint used an asynchronous job pattern with a job_id for tracking. The new endpoints return data synchronously.

  • Data Structure: The old endpoint’s query_result structure varied by query_func. The new endpoints have consistent, well-defined data structures.

  • Vessel Data: For queries related to current vessel status, positions, or vessel information, use /v1/vessels. This replaces any queryAIS queries that returned vessel-level data.

  • Transaction Data: For queries related to historical or completed transactions, use /v1/transactions. This provides detailed transaction records with origin and destination information, replacing any queryAIS queries that returned transaction data.

  • Forecast Data: For queries related to predicted future transactions, use /v1/transactions/forecast. This provides forecasted transactions with route scores and probability weighting, replacing any queryAIS queries that returned forecast or prediction data.

  • Error Handling: The old endpoint included execution metadata (execution_seconds, execution milliseconds) in the response. The new endpoints use standard HTTP status codes for error handling.

  • No Job ID: The new endpoints do not use job IDs; they return data directly in the response body.

GET /api/v2/live_status Endpoint Migration#

Old Endpoint: https://api.leviaton.synmax.com/leviaton-be2/api/v2/live_status

New Endpoint: https://leviaton.api.synmax.com/v1/vessels (with https://leviaton.api.synmax.com/v1/transactions as supplementary)

Summary of Changes#

  • The GET /api/v2/live_status endpoint has been replaced by the /v1/vessels endpoint, with /v1/transactions available as a supplementary data source.

  • The old endpoint returned aggregated summary statistics (fleet size, volume totals, status counts) and lists of vessels in specific states. The new endpoint returns individual vessel records that can be aggregated client-side to recreate the summary statistics.

  • The old endpoint provided pre-calculated aggregates and filtered lists (inactive vessels, maintenance vessels). The new endpoint provides detailed vessel data that allows for flexible filtering and aggregation based on specific requirements.

  • For certain calculations like terminal departures (left_regasification_terminal, left_liquefaction_terminal) and determining laden/ballast status, the /v1/transactions endpoint can provide supplementary data to enhance the analysis.

Endpoint & Method#

Input Parameter Changes#

The old endpoint was a simple GET request with no parameters. The new /v1/vessels endpoint is a POST request that accepts filtering parameters to filter vessels by status, type, country, terminal, and other criteria.

For supplementary data, the /v1/transactions endpoint accepts parameters to filter transactions by IMO, terminal, country, date ranges, and transaction type. This can be useful for calculating terminal departure counts and determining vessel load status.

Please refer to the V1 API documentation for the available filtering options for each endpoint.

Response Body Changes#

The old endpoint returned an asynchronous job-based response with aggregated summary statistics and filtered vessel lists. The new endpoint returns direct vessel records that contain all the necessary data to recreate the summary statistics and filtered lists through client-side processing.

V2 Response Structure (``live_status``):

{
  "version": "v2",
  "state": "SUCCESS",
  "job_id": "celery_job_id",
  "meta": {
    "report_result": {
      "summary": {
        "lng_fleet_size": 821,
        "lng_volume": 980487592.15,
        "lng_volume_unit": "mcf",
        "at_terminal": 770,
        "at_maintenance": 0,
        "inactive": 64,
        "laden": 289,
        "balast": 532,
        "left_regasification_terminal": 435,
        "left_liquefaction_terminal": 289,
        "datetime": "2025-11-05T20:32:59.420523",
        "epoch": 1762374779
      },
      "details": {
        "inactive": [
          {
            "imo": 9350927,
            "last_timestamp_position": "2025-08-25T00:40:59"
          }
        ],
        "maintenance": []
      },
      "notes": [
        "1. At the terminal, - vessels may be located in close proximity, though not necessarily within the terminal itself",
        "2. Inactive - A vessel with no signal for more than 5 days is considered inactive",
        "3. at maintanence - A vessel located within a maintenance area for more than 72 hours is classified as undergoing maintenance."
      ]
    },
    "report_message": "report completed",
    "func": "live_status",
    "execution": 119,
    "epoch": 1762374779.422863
  },
  "execution_seconds": 0.595
}

V1 Response Structure (``/v1/vessels``):

[
  {
    "vessel_id": "vessel_53488763a",
    "imo": 7361922,
    "mmsi": 538003805,
    "name": "ENERGOS FREEZE",
    "callsign": "V7TH4",
    "length": 287,
    "width": 43,
    "maximum_capacity": 125000.0,
    "maximum_capacity_unit": "CUBIC_METER",
    "is_loaded": null,
    "latitude": 19.71842,
    "longitude": -71.73292,
    "last_ais_signal_timestamp": "2025-10-26 17:51:39",
    "captains_destination": "ATLANTC BASIN",
    "captains_eta": "2025-09-01 10:00:00",
    "vessel_type": "LNG_CARRIER",
    "forecast_destination_terminal": null,
    "forecast_destination_terminal_id": null,
    "forecast_destination_timestamp": null,
    "status": "ACTIVE",
    "speed": 0.0,
    "heading": 242.0,
    "charterer": null,
    "flag_state": null,
    "first_active_date": null,
    "first_operation_date": null,
    "modified_at": "2025-05-15 16:56:38.600115"
  }
]

Key Differences:

  • Response Format: The old endpoint returned a job-based response with nested meta.report_result containing summary statistics and filtered lists. The new endpoint returns a direct array of vessel objects without aggregation.

  • Aggregated vs Individual Data: The old endpoint provided pre-calculated summary statistics (fleet size, volume totals, status counts). The new endpoint provides individual vessel records that require client-side aggregation to calculate summary statistics.

  • Fleet Size: The old endpoint’s lng_fleet_size can be calculated by counting vessels with status: "ACTIVE" in the new endpoint.

  • Volume Calculations: The old endpoint’s lng_volume and lng_volume_unit can be calculated by summing maximum_capacity values from active vessels, converting units as needed. The new endpoint provides maximum_capacity and maximum_capacity_unit per vessel.

  • Status Counts: The old endpoint provided counts for at_terminal, at_maintenance, inactive, laden, and balast. These can be determined from the new endpoint by: - at_terminal: Filter vessels by position proximity to terminals (using latitude and longitude) - at_maintenance: Filter vessels that have been in maintenance areas for extended periods (requires position analysis) - inactive: Filter vessels where last_ais_signal_timestamp is older than 5 days - laden/ballast: Use is_loaded field or analyze recent transactions from /v1/transactions to determine load status

  • Terminal Departures: The old endpoint’s left_regasification_terminal and left_liquefaction_terminal counts can be calculated by analyzing recent transactions from /v1/transactions to identify vessels that have left specific terminal types.

  • Using ``/v1/transactions`` as Supplementary Data: While /v1/vessels provides the primary data for recreating the live status summary, the /v1/transactions endpoint can be used to supplement specific calculations: - Terminal Departures: Query /v1/transactions filtered by recent timestamps and terminal types to identify vessels that have departed from regasification or liquefaction terminals - Laden/Ballast Status: Analyze recent transactions to determine if a vessel is currently laden (loaded) or ballast (empty) based on transaction history and destination terminal types - Transaction History: Use transaction data to provide context about vessel movements and terminal activities that may not be directly available in the vessel status data

  • Vessel Lists: The old endpoint provided filtered lists in details.inactive and details.maintenance. These can be recreated by filtering the vessel array from the new endpoint based on the criteria above.

  • Notes: The old endpoint included explanatory notes about data definitions. These definitions should be applied when processing the new endpoint data to ensure consistent categorization.

  • No Job ID: The new endpoint does not use job IDs; it returns data directly in the response body.

  • Synchronous Response: The new endpoint returns data synchronously, eliminating the need for job status polling.

  • Flexibility: The new endpoint allows for more flexible filtering and analysis, as you can apply custom criteria rather than relying on pre-defined aggregates.