openapi: 3.2.0
info:
  title: Open Mobility Foundation Stops 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 Stops 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: Stops
paths:
  /stops:
    post:
      operationId: post-stops
      description: Allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
      summary: /stops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/stop'
      responses:
        '201':
          description: Stops registered.
          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/stop'
                        oneOf:
                        - $ref: '#/components/schemas/response_error_bad_param'
                        - $ref: '#/components/schemas/response_error_missing_param'
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '406':
          description: MDS version in Accept header is unsupported or invalid.
        '409':
          description: A stop with `stop_id` is already registered.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response_bulk'
                - required:
                  - failures
                  properties:
                    failures:
                      minItems: 1
                      items:
                        allOf:
                        - $ref: '#/components/schemas/response_error_already_registered'
                        - properties:
                            item:
                              $ref: '#/components/schemas/stop'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error'
      tags:
      - Stops
    put:
      operationId: put-stops
      description: Update stop information. Each stop must already be registered.
      summary: /stops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/mutable-stop'
      responses:
        '200':
          description: Stop(s) updated.
          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/mutable-stop'
                        oneOf:
                        - $ref: '#/components/schemas/response_error_bad_param'
                        - $ref: '#/components/schemas/response_error_missing_param'
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '404':
          description: This `stop_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/mutable-stop'
        '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:
      - Stops
    get:
      operationId: get-stops
      description: Get a list of all stop records.
      summary: /stops
      responses:
        '200':
          description: Stops found.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/response_version'
                - type: object
                  description: Stops data payload
                  required:
                  - stops
                  properties:
                    stops:
                      type: array
                      items:
                        $ref: '#/components/schemas/stop'
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '404':
          description: Stops not found.
        '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:
      - Stops
  /stops/{stop_id}:
    parameters:
    - name: stop_id
      schema:
        $ref: '#/components/schemas/data-types_uuid'
      in: path
      required: true
      description: The `stop_id` for a Stop.
    get:
      operationId: get-stops-stop_id
      description: Get information about the specified stop.
      summary: /stops/{stop_id}
      responses:
        '200':
          description: Stop found.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/response_version'
                - type: object
                  description: Stops data payload
                  required:
                  - stops
                  properties:
                    stops:
                      type: array
                      minItems: 1
                      maxItems: 1
                      items:
                        $ref: '#/components/schemas/stop'
        '400':
          description: Bad request.
        '401':
          description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
        '404':
          description: Stop not found.
        '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:
      - Stops
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_string:
      title: data-types/string
      description: A length-limited string type.
      examples:
      - ABC123
      maxLength: 255
      pattern: ^(.*)$
      type: string
      x-stoplight:
        id: 2vqv7166161kh
    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
    response_error_already_registered:
      title: response/error_already_registered
      description: An item with that identifier is already registered.
      type: object
      x-stoplight:
        id: 3hzf84lqgzawp
      required:
      - item
      - error
      - error_description
      properties:
        error:
          const: already_registered
        error_description:
          type: string
          examples:
          - A vehicle with that device_id is already registered.
          - A stop with that stop_id is already registered.
        error_details:
          type: array
          items:
            type: string
    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
    data-types_vehicle-type:
      title: data-types/vehicle-type
      description: The allowed types of of vehicles in MDS. Based off of `form_factor` in [GBFS vehicle_types](https://github.com/MobilityData/gbfs/blob/master/gbfs.md#vehicle_typesjson), with some additional to support MDS modes.
      type: string
      x-stoplight:
        id: gbhhyditnvs5w
      enum:
      - bicycle
      - bus
      - cargo_bicycle
      - car
      - delivery_robot
      - moped
      - motorcycle
      - scooter_standing
      - scooter_seated
      - truck
      - other
    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
    mutable-stop:
      title: models/mutable-stop
      description: The fields of a Stop that can be changed in the Agency API.
      type: object
      x-stoplight:
        id: xs6ehwfn5b629
      required:
      - stop_id
      - last_updated
      properties:
        stop_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: UUID for the stop.
        last_updated:
          $ref: '#/components/schemas/data-types_timestamp'
          description: Date/Time of the the stop was last updated.
        status:
          type: object
          required:
          - is_installed
          - is_renting
          - is_returning
          properties:
            is_installed:
              type: boolean
              description: See GBFS [station_status.json](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson)
            is_renting:
              type: boolean
              description: See GBFS [station_status.json](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson)
            is_returning:
              type: boolean
              description: See GBFS [station_status.json](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson)
          description: The status of the stop.
        num_vehicles_available:
          $ref: '#/components/schemas/data-types_vehicle-type-counts'
          description: How many vehicles are available per [`vehicle_type`](./data-types/vehicle-type.yaml) at this stop?.
        num_vehicles_disabled:
          $ref: '#/components/schemas/data-types_vehicle-type-counts'
          description: How many vehicles are unavailable/reserved per [`vehicle_type`](./data-types/vehicle-type.yaml) at this stop?.
        rental_methods:
          type: array
          uniqueItems: true
          items:
            enum:
            - key
            - creditcard
            - paypass
            - applepay
            - androidpay
            - transitcard
            - accountnumber
            - phone
          description: List of payment methods accepted at stop, see [GBFS Rental Methods](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson).
        num_places_available:
          $ref: '#/components/schemas/data-types_vehicle-type-counts'
          description: How many places are free to be populated with vehicles per [`vehicle_type`](./data-types/vehicle-type.yaml) at this stop?
        num_places_disabled:
          $ref: '#/components/schemas/data-types_vehicle-type-counts'
          description: How many places are disabled and unable to accept vehicles per [`vehicle_type`](./data-types/vehicle-type.yaml) at this stop?
        devices:
          $ref: '#/components/schemas/data-types_uuid-array'
          description: List of `device_id` for [vehicles](./vehicle.yaml) currently at this stop.
    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'
    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
    data-types_vehicle-type-counts:
      title: data-types/vehicle-type-counts
      description: A dictionary of vehicle counts, keyed by [`vehicle_type`](./vehicle-type.yaml).
      type: object
      x-stoplight:
        id: isobk3kg3rr8r
      additionalProperties: false
      propertyNames:
        $ref: '#/components/schemas/data-types_vehicle-type'
      patternProperties:
        ? ''
        : $ref: '#/components/schemas/data-types_integer-positive'
    stop:
      title: models/stop
      description: 'Stops describe vehicle trip start and end locations in a pre-designated physical place. They can vary from docking stations

        with or without charging, corrals with lock-to railings, or suggested parking areas marked with spray paint.

        Stops are used in both [Provider](../reference/provider.yaml) and [Agency](#) telemetry data.'
      type: object
      x-stoplight:
        id: m0f816guajcjj
      allOf:
      - required:
        - name
        - location
        - status
        - capacity
        - num_vehicles_available
        - num_vehicles_disabled
        properties:
          name:
            $ref: '#/components/schemas/data-types_string'
            description: Name of the stop.
          location:
            $ref: '#/components/schemas/data-types_gps'
            description: Simple centerpoint location of the Stop. The use of the optional `geography_id` is recommended to provide more detail.
          capacity:
            $ref: '#/components/schemas/data-types_vehicle-type-counts'
            description: Number of total places per [`vehicle_type`](./data-types/vehicle-type.yaml).
          provider_id:
            $ref: '#/components/schemas/data-types_uuid'
            description: 'UUID for the Provider managing this Stop. Null/undefined if managed by an Agency.

              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: 'UUID for the data provider managing the data coming from this stop.

              Null/undefined if managed by an agency or a provider. Null/undefined if managed by an Agency.

              See MDS [provider list](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/providers.csv).'
          geography_id:
            $ref: '#/components/schemas/data-types_uuid'
            description: Pointer to the [Geography](#) that represents the Stop geospatially via Polygon or MultiPolygon.
          region_id:
            $ref: '#/components/schemas/data-types_string'
            description: ID of the region where station is located. See [GBFS Station Information](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson).
          short_name:
            $ref: '#/components/schemas/data-types_string'
            description: Abbreviated stop name.
          address:
            $ref: '#/components/schemas/data-types_string'
            description: Postal address (useful for directions).
          post_code:
            $ref: '#/components/schemas/data-types_string'
            description: Postal code.
            examples:
            - 10036
          cross_street:
            $ref: '#/components/schemas/data-types_string'
            description: Cross street of where station is located.
          parent_stop:
            $ref: '#/components/schemas/data-types_uuid'
            description: Describe a basic hierarchy of stops (e.g. a stop inside a greater stop).
          image_url:
            type: string
            format: uri
            description: Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop.
      - $ref: '#/components/schemas/mutable-stop'
    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
    response_ttl:
      title: response/ttl
      type: object
      x-stoplight:
        id: kejk1tkl7fdd2
      required:
      - ttl
      properties:
        ttl:
          $ref: '#/components/schemas/data-types_integer-positive'
          description: 'Integer representing the number of milliseconds before the data in this feed will be updated again

            (0 if the data should always be refreshed). The data returned by a near-realtime endpoint should be as close to realtime

            as possible, but in no case should it be more than 5 minutes out-of-date.'
          maximum: 300000
    response_last_updated:
      title: response/last_updated
      type: object
      x-stoplight:
        id: z6u8eu7rlkd1j
      required:
      - last_updated
      properties:
        last_updated:
          $ref: '#/components/schemas/data-types_timestamp'
          description: Timestamp indicating the last time the data in this feed was updated.
  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