openapi: 3.0.1
info:
  title: Searoutes 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: Ocean Routing
    description: Sea routes, distances, durations, and voyage plans.
  - name: Geocoding
    description: Ports, airports, places, areas, postal codes, and nearest points.
  - name: CO2 Emissions
    description: Multimodal CO2e emission calculations (sea, road, rail, air, inland water).
  - name: Vessel
    description: AIS vessel positions, ETAs, arrivals, traces, and time series.
  - name: Search
    description: Carrier and liner-service lookup.
  - name: Weather
    description: Historical, real-time, and forecasted weather.
paths:
  /route/v2/sea/{locations}:
    get:
      operationId: getSeaRoute
      tags:
        - Ocean Routing
      summary: Get sea route between locations
      description: >-
        Returns the sea route between a source and target location (and up to 20
        waypoints) as coordinate pairs (longitude,latitude) or UN/LOCODEs
        separated by semicolons, along with route distance (meters), duration
        (milliseconds), and the crossed areas.
      parameters:
        - $ref: '#/components/parameters/Locations'
        - name: continuousCoordinates
          in: query
          schema:
            type: boolean
            default: true
        - name: allowIceAreas
          in: query
          schema:
            type: boolean
            default: false
        - name: avoidHRA
          in: query
          description: Avoid the High Risk Area.
          schema:
            type: boolean
            default: false
        - name: avoidSeca
          in: query
          description: Avoid Sulphur Emission Control Areas.
          schema:
            type: boolean
            default: false
        - name: blockAreas
          in: query
          description: Comma-separated area ids to block.
          schema:
            type: string
        - name: departure
          in: query
          description: Departure time as a Unix timestamp in milliseconds.
          schema:
            type: integer
            format: int64
        - name: imo
          in: query
          description: Vessel IMO number.
          schema:
            type: integer
        - name: speed
          in: query
          description: Vessel speed in km/h.
          schema:
            type: number
        - name: speedInKts
          in: query
          description: Vessel speed in knots.
          schema:
            type: number
        - name: vesselDraft
          in: query
          description: Vessel draft in meters.
          schema:
            type: number
      responses:
        '200':
          description: A GeoJSON FeatureCollection describing the route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /route/v2/sea/{locations}/plan:
    get:
      operationId: getSeaRoutePlan
      tags:
        - Ocean Routing
      summary: Get a detailed sea route plan
      description: >-
        Returns a sea route with a leg-by-leg voyage plan including timing based
        on the departure time and vessel speed.
      parameters:
        - $ref: '#/components/parameters/Locations'
        - name: departure
          in: query
          schema:
            type: integer
            format: int64
        - name: speedInKts
          in: query
          schema:
            type: number
      responses:
        '200':
          description: A route plan with timed legs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/all:
    get:
      operationId: geocodeAll
      tags:
        - Geocoding
      summary: Find all types of locations
      description: Search ports, airports, terminals, and postal codes in one call.
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/port:
    get:
      operationId: geocodePort
      tags:
        - Geocoding
      summary: Find ports by name or locode
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/airport:
    get:
      operationId: geocodeAirport
      tags:
        - Geocoding
      summary: Search airports by name, locode, or IATA code
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/area:
    get:
      operationId: geocodeArea
      tags:
        - Geocoding
      summary: Locate routing areas by name
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/zip:
    get:
      operationId: geocodeZip
      tags:
        - Geocoding
      summary: Retrieve coordinates for postal codes
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/closest:
    get:
      operationId: geocodeClosest
      tags:
        - Geocoding
      summary: Identify nearest locations from coordinates
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
        - name: lon
          in: query
          required: true
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /geocoding/v2/place:
    get:
      operationId: geocodePlace
      tags:
        - Geocoding
      summary: Check if coordinates are at sea or find the closest sea point
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
        - name: lon
          in: query
          required: true
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/GeocodingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/shipment:
    get:
      operationId: getShipmentCo2
      tags:
        - CO2 Emissions
      summary: Get CO2e emissions for a multimodal shipment
      description: ISO 14083 / GLEC-accredited multimodal shipment CO2e (v2.1).
      parameters:
        - name: fromLocode
          in: query
          schema:
            type: string
        - name: toLocode
          in: query
          schema:
            type: string
        - name: nContainers
          in: query
          schema:
            type: integer
        - name: containerSizeTeu
          in: query
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/vessel:
    get:
      operationId: getVesselCo2
      tags:
        - CO2 Emissions
      summary: Compute emissions for an ocean voyage by vessel or trade lane
      parameters:
        - name: imo
          in: query
          schema:
            type: integer
        - name: fromLocode
          in: query
          schema:
            type: string
        - name: toLocode
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/road:
    get:
      operationId: getRoadCo2
      tags:
        - CO2 Emissions
      summary: Calculate road transport emissions
      parameters:
        - $ref: '#/components/parameters/Locations'
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/rail:
    get:
      operationId: getRailCo2
      tags:
        - CO2 Emissions
      summary: Compute rail journey emissions
      parameters:
        - $ref: '#/components/parameters/Locations'
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/aircraft:
    get:
      operationId: getAircraftCo2
      tags:
        - CO2 Emissions
      summary: Determine air cargo or passenger emissions
      parameters:
        - $ref: '#/components/parameters/Locations'
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/inland-water:
    get:
      operationId: getInlandWaterCo2
      tags:
        - CO2 Emissions
      summary: Calculate inland waterway emissions
      parameters:
        - $ref: '#/components/parameters/Locations'
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/run:
    post:
      operationId: getMilkRunCo2
      tags:
        - CO2 Emissions
      summary: Compute milk-run (collection/delivery) emissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/plan:
    get:
      operationId: getPlanCo2
      tags:
        - CO2 Emissions
      summary: Get CO2e statistics for carriers on a port pair
      parameters:
        - name: fromLocode
          in: query
          schema:
            type: string
        - name: toLocode
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/proformas/{hash}:
    get:
      operationId: getProformaCo2
      tags:
        - CO2 Emissions
      summary: Retrieve CO2 details for a specific itinerary
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /co2/v2/execution/{hash}:
    get:
      operationId: getExecutionCo2
      tags:
        - CO2 Emissions
      summary: Access CO2e breakdown for an ocean schedule execution
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Co2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /search/v2/carriers:
    get:
      operationId: searchCarriers
      tags:
        - Search
      summary: Find maritime carriers by name or SCAC code
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          $ref: '#/components/responses/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/v2/carrier/{id}:
    get:
      operationId: getCarrier
      tags:
        - Search
      summary: Retrieve a specific carrier
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/v2/service:
    get:
      operationId: searchServices
      tags:
        - Search
      summary: Search services by name with optional carrier filtering
      parameters:
        - $ref: '#/components/parameters/Query'
        - name: carrierId
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/v2/service/{id}:
    get:
      operationId: getService
      tags:
        - Search
      summary: Get service details including vessels and ports
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /weather/v2/forecast:
    get:
      operationId: getWeatherForecast
      tags:
        - Weather
      summary: Retrieve bulk weather forecasts (up to 14 days)
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
        - name: lon
          in: query
          required: true
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/WeatherResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /weather/v2/historical:
    get:
      operationId: getWeatherHistorical
      tags:
        - Weather
      summary: Access historical weather data (2013-present)
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
        - name: lon
          in: query
          required: true
          schema:
            type: number
        - name: date
          in: query
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/WeatherResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /weather/v2/track:
    post:
      operationId: getWeatherAlongTrack
      tags:
        - Weather
      summary: Obtain weather conditions along a specific route
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/WeatherResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  parameters:
    Locations:
      name: locations
      in: path
      required: true
      description: >-
        Coordinate pairs (longitude,latitude) or UN/LOCODEs separated by
        semicolons. Up to 20 positions.
      schema:
        type: string
      example: -1.27,50.80;8.83,53.88
    Query:
      name: query
      in: query
      required: true
      description: Free-text search term (name, code, or locode).
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    GeocodingResponse:
      description: A GeoJSON FeatureCollection of matching locations.
      content:
        application/json:
          schema:
            type: object
    Co2Response:
      description: CO2e emission results in grams/kilograms with methodology metadata.
      content:
        application/json:
          schema:
            type: object
    VesselResponse:
      description: Vessel AIS data (position, ETA, trace, or time series).
      content:
        application/json:
          schema:
            type: object
    SearchResponse:
      description: Carrier or service search results.
      content:
        application/json:
          schema:
            type: object
    WeatherResponse:
      description: Weather conditions (historical, current, or forecast).
      content:
        application/json:
          schema:
            type: object
  schemas:
    RouteResponse:
      type: object
      properties:
        type:
          type: string
          example: FeatureCollection
        features:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: Feature
              geometry:
                type: object
              properties:
                type: object
                properties:
                  distance:
                    type: number
                    description: Route distance in meters.
                  duration:
                    type: number
                    description: Route duration in milliseconds.
                  crossedAreas:
                    type: array
                    items:
                      type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string