specification.yaml

openapi: 3.0.2
info:
  title: Sustainable Mobility API
  version: 1.0.0
  description: >-
    Promoting sustainable transportation systems by providing transparency into
    the environmental costs of transport journeys.
  license:
    name: Apache 2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0"
  contact:
    name: Brylie Christopher Oxley
    email: brylie.oxley@maas.global
servers:
  - url: /
    description: Local server relative to documentation server.
paths:
  /estimate-co2:
    summary: Estimate CO2 emissions for one or more transportation legs.
    post:
      operationId: api.estimate_request_co2
      summary: Get an estimate of CO2 emissions for one or more transport legs.
      description: >-
        This endpoint will estimate CO2 emissions for one or more transport legs based on:

        - either

          - origin and destination (WGS-84 lat/lon)

          - pre-calculated distance in kilometers

        - transport mode,

        - vehicle occupancy (optional),


        Additional properties will be ignored and returned in the response array.


        ## Design rationale

        Journey planners may need to annotate multiple transportation legs with
        CO2 estimates. The HTTP overhead for multiple annotations may add 
        unreasonable delay to the overall journey planner result. This endpoint
        reduces network overhead by producing multiple CO2 estimates from a single HTTP request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/itinerary_option_origin_destination"
                  - $ref: "#/components/schemas/itinerary_option_distance_km"
      responses:
        "200":
          description: >
            Returns an array of objects each containing an estimate of CO2 emissions in grams for the given
            transportation leg. 


            ## Errors

            Where the CO2 estimation was not possible for a particular input,
            an `error` object will be returned with a description of the issue in the `error_message` field.

            ## Original request

            The response will contain the unmodified `request_object` as provided in the request body.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/co2_estimate_response"
components:
  links: {}
  callbacks: {}
  schemas:
    coordinate:
      type: object
      description: A geographic coordinate with latitude and longitude in WGS-84 decimal degrees.
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
      required:
        - latitude
        - longitude
    itinerary_option_origin_destination:
      type: object
      description: Itinerary option where the trip origin and destination coordinates are known. Using WGS-84 lat/long.
      properties:
        transport_mode:
          $ref: "#/components/schemas/transport_mode"
        origin:
          $ref: "#/components/schemas/coordinate"
        destination:
          $ref: "#/components/schemas/coordinate"
        vehicle_occupancy:
          type: number
      required:
        - transport_mode
        - origin
        - destination
      additionalProperties: true
      example:
        origin:
          latitude: 60.2055
          longitude: 24.9384
        destination:
          latitude: 60.2055
          longitude: 24.6559
        transport_mode: "SMALL_CAR"
        other_property: "something else"
    itinerary_option_distance_km:
      type: object
      description: Itinerary option where the trip distince in kilometers is provided.
      properties:
        transport_mode:
          $ref: "#/components/schemas/transport_mode"
        distance_km:
          type: number
        vehicle_occupancy:
          type: number
      required:
        - transport_mode
        - distance_km
      additionalProperties: true
      example:
        transport_mode: "SMALL_CAR"
        vehicle_occupancy: 2
        distance_km: 20
        other_property: "something else"
    transport_mode:
      type: string
      enum:
        - LIGHT_RAIL
        - SMALL_CAR
        - LARGE_CAR
        - SCOOTER
        - BUS
        - WALK
        - BICYCLE
        - CAR
        - TRAM
        - SUBWAY
        - RAIL
        - FERRY
        - CABLE_CAR
        - GONDOLA
        - FUNICULAR
        - TRANSIT
        - LEG_SWITCH
        - AIRPLANE
        - WAIT
    co2_estimate:
      type: object
      description: An estimate of grams CO2 for the given transportation leg.
      properties:
        co2_estimate:
          type: object
          properties:
            transport_mode:
              type: string
            vehicle_occupancy:
              type: integer
            distance_km:
              type: number
            estimated_co2_g:
              type: number
      example:
        co2_estimate:
          transport_mode: "SMALL_CAR"
          vehicle_occupancy: 2
          distance_km: 20
          estimated_co2_g: 200
    error:
      type: object
      description: Error details about why CO2 estimation failed for this specific leg.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
      example:
        error:
          message: "Not enough information provided for CO2 estimate."
    co2_estimate_response:
      type: object
      description: A response item related to a specific request input. Will contain either a CO2 estimate or error object.
      oneOf:
        - $ref: "#/components/schemas/co2_estimate"
        - $ref: "#/components/schemas/error"
      properties:
        request_object:
          type: object
          description: "Unmodified object provided in request body."
security: []