cruise-itinerary-com Bulk exports API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Bulk exports API
  version: 1.0.0
  summary: Cruise reference data, weekly fares, itineraries on the calendar, port traffic and a change feed.
  description: 'Reference data and weekly fare snapshots for cruise lines, ships, ports and sailings, refreshed every Monday. Fares are snapshots from an inventory feed, not live bookable prices. A null fare means the cabin is not offered or is sold out; the feed does not distinguish.


    **Authentication.** Send `Authorization: Bearer ` or `X-API-Key: `. Every endpoint needs a key, and a Free key costs nothing but an email address. A request without one gets 401 `key_required`. A malformed, unknown or revoked key is a 401, never a silent downgrade.


    **Plans.** Each endpoint lists the lowest plan that can call it in `x-required-plan`. Rate limits are per minute and some plans have a monthly call quota; both are reported in response headers. See /pricing for the current numbers.


    **Envelope.** Single objects come back as `{"data": {...}, "meta": {...}}`, lists as `{"data": [...], "meta": {as_of, page, per_page, total, has_more}}`, errors as `{"error": {status, code, message}}`. Every key is always present; absent values are null. Dates are YYYY-MM-DD. Money is whole US dollars.


    **Ids.** Lines, ships, ports, destinations, regions and cruises use slugs. Sailings use their integer id.


    **Caching.** Anonymous responses from open endpoints are cacheable for an hour and carry an ETag. Everything keyed is `private, no-store`.


    **Counting.** A keyed request that returns 2xx counts toward the monthly quota; errors do not.'
  termsOfService: https://cruise-itinerary.com/terms
  contact:
    name: Cruise Itinerary
    url: https://cruise-itinerary.com
servers:
- url: https://cruise-itinerary.com
  description: Production
security:
- {}
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Bulk exports
paths:
  /v1/exports:
    get:
      tags:
      - Bulk exports
      summary: List weekly exports
      description: 'The last eight weekly bulk files, as gzipped CSV, with row counts and SHA-256 checksums. Column names match the API and ids are slugs, so files join to the `identity-*` files. `access: free` files (the `identity-*` files) download with any key; the rest need Platform.'
      operationId: listExports
      x-required-plan: free
      parameters: []
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExportWeek'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - date: '2026-09-28'
                  files:
                  - name: identity-lines.csv.gz
                    bytes: 895
                    rows: 45
                    sha256: e1f11e7d1fe1601a81c30c8f7e410793893ac5d02c9e4000e1de6a9d653c0d29
                    access: free
                    url: https://cruise-itinerary.com/v1/exports/2026-10-19/identity-lines.csv.gz
                  - name: identity-ships.csv.gz
                    bytes: 21017
                    rows: 657
                    sha256: a1c287404b74bfa3bdcdd3946bbc8b35805396b63d45d9a50331b372a88599de
                    access: free
                    url: https://cruise-itinerary.com/v1/exports/2026-10-19/identity-ships.csv.gz
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 4
                  total: 4
                  has_more: false
        '401':
          $ref: '#/components/responses/E401'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/exports/{date}/{file}:
    get:
      tags:
      - Bulk exports
      summary: Download an export file
      description: Streams one gzipped CSV. `date` may be `latest`. Files named `identity-*` (lines, ships, ports, destinations, regions) come with every plan, Free included; the rest need Platform.
      operationId: downloadExport
      x-required-plan: free
      parameters:
      - name: date
        in: path
        required: true
        description: Export date from the listing, or latest.
        schema:
          type: string
        example: latest
      - name: file
        in: path
        required: true
        description: File name from the listing.
        schema:
          type: string
        example: identity-lines.csv.gz
      responses:
        '200':
          description: The file.
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
components:
  responses:
    E429:
      description: Per-minute rate limit (`rate_limited`, with `Retry-After`) or monthly quota (`quota_exceeded`) reached.
      headers:
        Retry-After:
          description: Seconds until the rate window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 429
              code: rate_limited
              message: Rate limit of 60 requests per minute exceeded. Retry in 31 seconds.
    E401:
      description: No key was sent (`key_required`; a free key is one email away at /signup), or the key is malformed, unknown or revoked (`invalid_key`). A bad key is never treated as anonymous.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 401
              code: key_required
              message: 'This endpoint needs an API key. Get a free one at https://cruise-itinerary.com/signup and send it as "Authorization: Bearer <key>".'
              required_plan: free
    E403:
      description: The plan does not include this endpoint (`plan_required`, with `required_plan`), or the account is suspended (`account_suspended`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 403
              code: plan_required
              message: This endpoint needs the Business plan or above; this key is on the Developer plan.
              required_plan: business
    E500:
      description: Internal error. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 500
              code: internal
              message: Internal error. Try again; if it persists, contact support.
    E404:
      description: No such entity or endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 404
              code: not_found
              message: No such ship.
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per one-minute window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - status
          - code
          - message
          properties:
            status:
              type: integer
            code:
              type: string
              enum:
              - bad_request
              - key_required
              - invalid_key
              - account_suspended
              - plan_required
              - not_found
              - rate_limited
              - quota_exceeded
              - method_not_allowed
              - internal
            message:
              type: string
              description: Human-readable explanation; safe to show to a developer, not a stable string to match on.
            required_plan:
              type: string
              description: 'Present on plan_required and key_required: the lowest plan that can call the endpoint.'
              enum:
              - free
              - developer
              - business
              - platform
    ListMeta:
      type: object
      properties:
        as_of:
          oneOf:
          - type: string
            description: Date of the latest inventory load the response reflects.
            format: date
          - type: 'null'
        page:
          type: integer
          description: Current page, from 1.
        per_page:
          type: integer
          description: Rows per page.
        total:
          type: integer
          description: Rows matching the query across all pages.
        has_more:
          type: boolean
          description: True when a later page exists.
      required:
      - as_of
      - page
      - per_page
      - total
      - has_more
      additionalProperties: false
    ExportWeek:
      type: object
      properties:
        date:
          type: string
          format: date
        files:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              bytes:
                type: integer
              rows:
                type: integer
              sha256:
                type: string
              access:
                type: string
                description: 'free: any key, Free included; platform: the Platform plan.'
                enum:
                - free
                - platform
              url:
                type: string
                format: uri
            required:
            - name
            - bytes
            - rows
            - sha256
            - access
            - url
            additionalProperties: false
      required:
      - date
      - files
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Key from the dashboard: ci_live_ followed by 32 letters and digits.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same key, as a header.