cruise-itinerary-com Changes API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Changes 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: Changes
paths:
  /v1/changes:
    get:
      tags:
      - Changes
      summary: Change feed
      description: 'What changed between consecutive weekly loads: fare moves per cabin, cabins appearing or vanishing, sailings added or removed, itineraries swapped, port days moved or confirmed. Newest load first. `kind` takes a comma-separated list.'
      operationId: listChanges
      x-required-plan: business
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: since
        in: query
        required: false
        description: Earliest detected_on.
        schema:
          type: string
          format: date
        example: '2026-09-14'
      - name: until
        in: query
        required: false
        description: Latest detected_on.
        schema:
          type: string
          format: date
        example: '2026-09-28'
      - name: kind
        in: query
        required: false
        description: 'Comma-separated: price_drop, price_rise, cabin_unavailable, cabin_available, sailing_added, sailing_removed, itinerary_changed, schedule_changed.'
        schema:
          type: string
        example: price_drop,sailing_added
      - name: ship
        in: query
        required: false
        description: Ship slug.
        schema:
          type: string
        example: eurodam
      - name: line
        in: query
        required: false
        description: Line slug.
        schema:
          type: string
        example: holland-america-line
      - name: port
        in: query
        required: false
        description: Port slug; sailings that call there.
        schema:
          type: string
        example: miami
      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/ChangeEvent'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: 813554
                  detected_on: '2026-10-19'
                  previous_on: '2026-10-12'
                  kind: price_drop
                  sailing_id: 14026501
                  cruise_id: 21-night-panama-canal-nieuw-amsterdam-6d1d00
                  previous_cruise_id: null
                  ship:
                    id: nieuw-amsterdam
                    name: Nieuw Amsterdam
                  line:
                    id: holland-america-line
                    name: Holland America Line
                  departure_date: '2027-04-11'
                  cabin: inside
                  old_value: 2199
                  new_value: 2099
                  currency: USD
                - id: 813555
                  detected_on: '2026-10-19'
                  previous_on: '2026-10-12'
                  kind: price_drop
                  sailing_id: 14026507
                  cruise_id: 7-night-classic-california-coast-koningsdam-e49840
                  previous_cruise_id: null
                  ship:
                    id: koningsdam
                    name: Koningsdam
                  line:
                    id: holland-america-line
                    name: Holland America Line
                  departure_date: '2026-11-14'
                  cabin: inside
                  old_value: 949
                  new_value: 849
                  currency: USD
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 1734
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '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
    E400:
      description: 'Bad request: an unknown or malformed parameter. The message names it.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 400
              code: bad_request
              message: 'Parameter ''cabin'' must be one of: inside, outside, balcony, suite.'
    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
    Ref:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
    ChangeEvent:
      type: object
      properties:
        id:
          type: integer
        detected_on:
          type: string
          description: Load that revealed the change.
          format: date
        previous_on:
          type: string
          description: Load it was compared against.
          format: date
        kind:
          type: string
          description: '`schedule_changed`: the sailing''s route is the same but port days moved, were added or removed, or estimated days were confirmed by the line''s own itinerary; re-fetch the sailing for its new days. It covers every rebuild of the day-by-day itineraries since the previous load, nightly ones included.'
          enum:
          - price_drop
          - price_rise
          - cabin_unavailable
          - cabin_available
          - sailing_added
          - sailing_removed
          - itinerary_changed
          - schedule_changed
        sailing_id:
          type: integer
        cruise_id:
          oneOf:
          - type: string
            description: Cruise slug.
          - type: 'null'
        previous_cruise_id:
          oneOf:
          - type: string
            description: 'For itinerary_changed: the cruise it replaced.'
          - type: 'null'
        ship:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        line:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        departure_date:
          type: string
          format: date
        cabin:
          oneOf:
          - type: string
            enum:
            - inside
            - outside
            - balcony
            - suite
          - type: 'null'
        old_value:
          oneOf:
          - type: integer
            description: 'Fare before, USD. For schedule_changed: port days whose date moved, or that were added or removed.'
          - type: 'null'
        new_value:
          oneOf:
          - type: integer
            description: 'Fare after, USD. For schedule_changed: estimated days now exact.'
          - type: 'null'
        currency:
          type: string
          enum:
          - USD
      required:
      - id
      - detected_on
      - previous_on
      - kind
      - sailing_id
      - cruise_id
      - previous_cruise_id
      - ship
      - line
      - departure_date
      - cabin
      - old_value
      - new_value
      - currency
      additionalProperties: false
  parameters:
    page:
      name: page
      in: query
      description: Page number, from 1. Pages deeper than 100,000 rows are refused.
      schema:
        type: integer
        minimum: 1
        default: 1
    per_page:
      name: per_page
      in: query
      description: Rows per page, 1 to 200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  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.