openapi: 3.0.1
info:
  title: Searoutes CO2 Emissions Vessel API
  description: Maritime routing and carbon-emissions REST API. Compute sea routes and distances, geocode ports and places, calculate multimodal CO2e emissions, track vessels via AIS, look up carriers and services, and retrieve weather along routes. All endpoints are served from https://api.searoutes.com and authenticated with an x-api-key header. Endpoint paths are modeled from the published Searoutes developer documentation and llms.txt reference index; request/response schemas are summarized rather than exhaustive.
  termsOfService: https://searoutes.com/terms/
  contact:
    name: Searoutes
    email: contact@searoutes.com
    url: https://developer.searoutes.com/reference/introduction
  version: '2.0'
servers:
- url: https://api.searoutes.com
security:
- ApiKeyAuth: []
tags:
- name: Vessel
  description: AIS vessel positions, ETAs, arrivals, traces, and time series.
paths:
  /vessel/v2/position:
    get:
      operationId: getVesselPosition
      tags:
      - Vessel
      summary: Retrieve the latest vessel position via IMO or MMSI
      parameters:
      - name: imo
        in: query
        schema:
          type: integer
      - name: mmsi
        in: query
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vessel/v2/eta:
    get:
      operationId: getVesselEta
      tags:
      - Vessel
      summary: Get a vessel ETA prediction from AIS
      parameters:
      - name: imo
        in: query
        schema:
          type: integer
      - name: toLocode
        in: query
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vessel/v2/arrivals:
    get:
      operationId: getVesselArrivals
      tags:
      - Vessel
      summary: List scheduled vessel arrivals at a port (beta)
      parameters:
      - name: locode
        in: query
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vessel/v2/name:
    get:
      operationId: searchVesselByName
      tags:
      - Vessel
      summary: Search vessel information by name
      parameters:
      - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vessel/v2/timeseries:
    get:
      operationId: getVesselTimeseries
      tags:
      - Vessel
      summary: Access historical vessel position data between dates
      parameters:
      - name: imo
        in: query
        schema:
          type: integer
      - name: fromDate
        in: query
        schema:
          type: integer
          format: int64
      - name: toDate
        in: query
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vessel/v2/trace:
    get:
      operationId: getVesselTrace
      tags:
      - Vessel
      summary: Obtain a processed vessel trajectory/route history
      parameters:
      - name: imo
        in: query
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    VesselResponse:
      description: Vessel AIS data (position, ETA, trace, or time series).
      content:
        application/json:
          schema:
            type: object
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Query:
      name: query
      in: query
      required: true
      description: Free-text search term (name, code, or locode).
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued on signup and shown on the developer documentation authentication page. Pass it in the x-api-key request header.