cruise-itinerary-com Resolver API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Resolver 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: Resolver
paths:
  /v1/resolve:
    get:
      tags:
      - Resolver
      summary: Resolve a name
      description: Match free text such as "Port Canaveral, Florida" or "Royal Caribbean Symphony of the Seas" to ports, ships and lines. Returns up to five candidates, best first. Confidence is 1.0 for an exact name, about 0.9 to 0.97 after normalising accents, punctuation, country suffixes and aliases, and 0.85 or less for approximate matches. For many names at once, use the POST form.
      operationId: resolve
      x-required-plan: free
      parameters:
      - name: q
        in: query
        required: true
        description: The text to match, up to 120 characters.
        schema:
          type: string
        example: Port Canaveral, Florida
      - name: type
        in: query
        required: false
        description: Restrict to one kind of entity.
        schema:
          type: string
          enum:
          - port
          - ship
          - line
      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/ResolveCandidate'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - type: port
                  id: port-canaveral
                  name: Port Canaveral
                  confidence: 0.9
                  match: normalized
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 1
                  total: 1
                  has_more: false
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
    post:
      tags:
      - Resolver
      summary: Resolve names in bulk
      description: Up to 100 items per request. The response holds one entry per item, in order, each with its own candidate list.
      operationId: resolveBatch
      x-required-plan: free
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    properties:
                      q:
                        type: string
                        maxLength: 120
                      type:
                        type: string
                        enum:
                        - port
                        - ship
                        - line
                    required:
                    - q
                    additionalProperties: false
              required:
              - items
              additionalProperties: false
            example:
              items:
              - q: Port Canaveral
                type: port
              - q: Allure of the seas
      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/ResolveBatchResult'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - q: Port Canaveral
                  type: port
                  candidates:
                  - type: port
                    id: port-canaveral
                    name: Port Canaveral
                    confidence: 1
                    match: exact
                - q: Allure of the seas
                  type: null
                  candidates:
                  - type: ship
                    id: allure-of-the-seas
                    name: Allure of the Seas
                    confidence: 1
                    match: exact
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 2
                  has_more: false
        '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'
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
    ResolveBatchResult:
      type: object
      properties:
        q:
          type: string
        type:
          oneOf:
          - type: string
          - type: 'null'
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/ResolveCandidate'
      required:
      - q
      - type
      - candidates
      additionalProperties: false
    ResolveCandidate:
      type: object
      properties:
        type:
          type: string
          enum:
          - port
          - ship
          - line
        id:
          type: string
          description: Slug.
        name:
          type: string
        confidence:
          type: number
          description: 0 to 1. 1.0 is an exact name match; below about 0.6 is a guess.
          minimum: 0
          maximum: 1
        match:
          type: string
          enum:
          - exact
          - alias
          - normalized
          - fuzzy
      required:
      - type
      - id
      - name
      - confidence
      - match
      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.