openapi: 3.2.0
info:
  title: Open Mobility Foundation Telemetry API
  version: '2.0'
  contact:
    url: https://github.com/openmobilityfoundation/mobility-data-specification
    name: Open Mobility Foundation
    email: info@openmobilityfoundation.org
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/LICENSE
  description: 'Operations tagged Telemetry across 2 of this provider''s published API definitions: open-mobility-foundation-mds-agency-openapi.yml, open-mobility-foundation-mds-provider-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Telemetry
paths:
  /telemetry:
    post:
      operationId: post-telemetry
      description: Send vehicle telemetry data in a batch for any number of vehicles in the fleet.
      summary: /telemetry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/telemetry'
      responses:
        '201':
          description: Vehicle telemetry processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_bulk'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response_bulk'
                - required:
                  - failures
                  properties:
                    failures:
                      minItems: 1
                      items:
                        properties:
                          item:
                            $ref: '#/components/schemas/telemetry'
                        oneOf:
                        - $ref: '#/components/schemas/response_error_bad_param'
                        - $ref: '#/components/schemas/response_error_missing_param'
        '404':
          description: The `device_id` is unregistered.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response_bulk'
                - required:
                  - failures
                  properties:
                    failures:
                      minItems: 1
                      items:
                        allOf:
                        - $ref: '#/components/schemas/response_error_unregistered'
                        - properties:
                            item:
                              $ref: '#/components/schemas/telemetry'
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '406':
          description: MDS version in Accept header is unsupported or invalid.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error'
      tags:
      - Telemetry
    parameters:
    - name: telemetry_time
      schema:
        $ref: '#/components/schemas/data-types_iso-dayhour'
      in: query
      required: true
      description: The UTC hour during which telemetry events occurred.
    get:
      operationId: get-telemetry-telemetry_time
      description: Get all telemetry with timestamp occurring within the hour.
      summary: /telemetry
      responses:
        '200':
          description: Hour has been processed.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/response_version'
                - type: object
                  description: Telemetry data payload
                  required:
                  - telemetry
                  properties:
                    telemetry:
                      type: array
                      items:
                        $ref: '#/components/schemas/telemetry'
        '400':
          description: Request did not contain a `telemetry_time`.
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '406':
          description: MDS version in Accept header is unsupported or invalid.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error'
      tags:
      - Telemetry
components:
  schemas:
    data-types_uuid-array:
      title: data-types/uuid-array
      description: Array of UUID.
      type: array
      x-stoplight:
        id: v932clitbqv31
      uniqueItems: true
      items:
        $ref: '#/components/schemas/data-types_uuid'
    response_bulk:
      title: response/bulk
      type: object
      description: For multi-record POST and PUT calls, e.g. sending Events using the Agency API, the bulk-response structure describes a list of results.
      x-stoplight:
        id: sdj75536ytrso
      required:
      - success
      - total
      properties:
        success:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: Number of successfully written records.
        total:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: Total number of provided records.
        failures:
          type: array
    data-types_timestamp:
      title: data-types/timestamp
      description: Integer milliseconds since Unix epoch.
      examples:
      - 1514764800000
      - 1681855703000
      minimum: 1514764800000
      multipleOf: 1
      type: number
      x-stoplight:
        id: vliol1hqlxw6y
    telemetry:
      title: models/telemetry
      description: 'A standard point of vehicle telemetry. References to latitude and longitude imply coordinates encoded in the

        [WGS 84 (EPSG:4326)](https://en.wikipedia.org/wiki/World_Geodetic_System) standard GPS or GNSS projection expressed

        as [Decimal Degrees](https://en.wikipedia.org/wiki/Decimal_degrees).'
      type: object
      x-stoplight:
        id: 47oju05zyh09f
      required:
      - device_id
      - provider_id
      - telemetry_id
      - timestamp
      - trip_ids
      - journey_id
      - location
      properties:
        device_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: A unique device ID in UUID format.
        provider_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: A UUID for the Provider, unique within MDS. See MDS [provider list](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/providers.csv).
        data_provider_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: If different than `provider_id`, a UUID for the data solution provider managing the data feed in this endpoint.
        telemetry_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: ID used for uniquely-identifying a Telemetry entry.
        timestamp:
          $ref: '#/components/schemas/data-types_timestamp'
          description: Date/time that event occurred.
        trip_ids:
          oneOf:
          - $ref: '#/components/schemas/data-types_uuid-array'
            minItems: 1
            description: If telemetry occurred during a trip, the ID of the trip(s).
          - type: 'null'
            description: If not in a trip, null.
        journey_id:
          oneOf:
          - $ref: '#/components/schemas/data-types_uuid'
            description: If telemetry occurred during a trip and journeys are used for the mode, the ID of the journey.
          - type: 'null'
            description: If not in a trip, null.
        stop_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: Stop that the vehicle is currently located at.
        location:
          $ref: '#/components/schemas/data-types_gps'
          description: Telemetry position data.
        location_type:
          type: string
          enum:
          - street
          - sidewalk
          - crosswalk
          - garage
          - bike_lane
        battery_percent:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: Percent battery charge of vehicle, expressed between 0 and 100.
          maximum: 100
        fuel_percent:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: Percent fuel in vehicle, expressed between 0 and 100.
          maximum: 100
        tipped_over:
          type: boolean
          description: If detectable and known, is the device tipped over or not?
          default: false
    response_error:
      title: response/error
      description: An error message for troubleshooting.
      type: object
      x-stoplight:
        id: 90yc58ni8u0ch
      required:
      - error
      - error_description
      - error_details
      properties:
        error:
          type: string
          description: Error message string.
        error_description:
          type: string
          description: Human readable error description (can be localized).
        error_details:
          type: array
          description: Human readable error description (can be localized).
          minItems: 1
          items:
            type: string
    response_error_missing_param:
      title: response/error_missing_param
      description: A required parameter is missing.
      type: object
      x-stoplight:
        id: huc7x2g2wfq5a
      required:
      - item
      - error
      - error_description
      - error_details
      properties:
        error:
          const: missing_param
        error_description:
          type: string
          examples:
          - A required parameter is missing.
        error_details:
          type: array
          description: Array of missing parameters.
          minItems: 1
          items:
            type: string
    data-types_integer-positive:
      title: data-types/integer-positive
      description: An integer greater than or equal to 0.
      minimum: 0
      type: integer
      x-stoplight:
        id: nfkphjmpm8yay
    data-types_uuid:
      title: data-types/uuid
      description: A UUID used to uniquely identity an object.
      type: string
      x-stoplight:
        id: np9kodwmy2kqa
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      examples:
      - 3c9604d6-b5ee-11e8-96f8-529269fb1459
    data-types_gps:
      title: data-types/gps
      properties:
        altitude:
          description: Altitude above mean sea level in meters.
          type: number
        heading:
          description: Degrees - clockwise starting at 0 degrees at true North.
          type: number
        horizontal_accuracy:
          description: Horizontal accuracy in meters.
          type: number
        lat:
          description: Latitude coordinate.
          maximum: 90
          minimum: -90
          type: number
        lng:
          description: Longitude coordinate.
          maximum: 180
          minimum: -180
          type: number
        satellites:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: Number of GPS or GNSS satellites.
        speed:
          description: Estimated speed in meters / sec as reported by the GPS chipset.
          type: number
        vertical_accuracy:
          description: Vertical accuracy in meters.
          type: number
      required:
      - lat
      - lng
      type: object
      x-stoplight:
        id: 8aooo5ag7x7vh
    response_error_bad_param:
      title: response/error_bad_param
      description: A validation error occurred.
      type: object
      x-stoplight:
        id: vekidez6dfa4u
      required:
      - item
      - error
      - error_description
      - error_details
      properties:
        error:
          const: bad_param
        error_description:
          type: string
          examples:
          - A validation error occurred
        error_details:
          type: array
          description: Array of parameters with errors.
          minItems: 1
          items:
            type: string
    response_error_unregistered:
      title: response/error_unregistered
      description: An item with that identifier is not registered.
      type: object
      x-stoplight:
        id: cw4q7ycy1a17h
      required:
      - item
      - error
      - error_description
      properties:
        error:
          const: unregistered
        error_description:
          type: string
          examples:
          - This device_id is not registered.
          - This stop_id is unregistered
        error_details:
          type: array
          items:
            type: string
    data-types_iso-dayhour:
      title: data-types/iso-dayhour
      description: An ISO 8601 extended datetime representing an UTC hour between 00 and 23 `YYYY-MM-DDTHH`; valid for dates in 1970 and later.
      examples:
      - 2023-12-31T23
      - 2024-01-01T01
      pattern: (19[789]\d|[2-9]\d{3})-(0[1-9]|1[02])-([12]\d|0[1-9]|3[01])T([0-2][0-3]|[01]\d)
      type: string
      x-stoplight:
        id: rc4v7nsrgdqpm
    data-types_version:
      title: data-type/version
      description: The version of MDS this data represents.
      type: string
      x-stoplight:
        id: bt49ntcbcuxbh
      pattern: ^2\.(\d|[1-9]\d+)\.(\d|[1-9]\d+)$
      examples:
      - 2.0.0
    response_version:
      title: response/version
      description: Response bodies must be a UTF-8 encoded JSON object and must minimally include the MDS `version`.
      type: object
      x-stoplight:
        id: ivd8jadc3rqf7
      required:
      - version
      properties:
        version:
          $ref: '#/components/schemas/data-types_version'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'All MDS Agency endpoints require authentication.


        JSON Web Token ([JWT](https://jwt.io/introduction/)) is RECOMMENDED as the token format.


        When making requests, the endpoints expect `provider_id` to be part of the claims the JWT. The token issuance,

        expiration and revocation policies are at the discretion of the agency.'
x-refined-from:
- open-mobility-foundation-mds-agency-openapi.yml
- open-mobility-foundation-mds-provider-openapi.yml
x-stoplight:
  id: f3thjnkfyv60k
x-bundled-from: https://github.com/openmobilityfoundation/mds-openapi/blob/v2.0/reference/agency.yaml (commit 0c07bc3d294237dd41c6273f059efb11b8149c66); external $refs into ../models/ inlined under components.schemas, no other changes