Voyage

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 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:

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

 
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

 
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

 
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

 
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

 
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 } }
      }
    }
  }
}

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 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:

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

 
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

 
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

 
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

 
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

 
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 } }
      }
    }
  }
}