Deleted Voyage

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

1. Authenticate with your API key/token (the same credentials used for the full Voyages API).
2. Poll the endpoint at your chosen interval (e.g., every day).
3. Store the latest deletedAt value as a cursor for the next request.
4. Apply deletions to your local data store:
5. Remove the record identified by _id.
6. Optionally, archive the deleted voyage for audit purposes.
7. Handle Errors: If a request fails, retry after a back-off period; on repeated failures, log and alert.

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

 
query GetDeletedVoyages {
  deletedVoyages(first: 50) {
        pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
    edges {
      node {
        _id
        deletedAt
        vessel {
          imo
          name
          dwt
          type
        }
      }
    }
  }
}

Filter by Deletion Date Range

 
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

 
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

 
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

1. Initial Sync – Perform a full pull from the standard Voyages API to seed the local store.
2. Continuous Sync – After the initial sync, switch to the Deleted-Only stream to catch up with any deletions.
3. Periodic Re-Sync – Every few weeks, perform a full pull again to guard against drift (e.g., missed deletions, client outages).