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.

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

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).

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.