DatabaseCatalogAPI.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: Mobility Database Catalog
  description: |
    API for the Mobility Database Catalog. See [https://mobilitydatabase.org/](https://mobilitydatabase.org/).
    
    The Mobility Database API uses OAuth2 authentication.
    To initiate a successful API request, an access token must be included as a bearer token in the HTTP header. Access tokens are valid for one hour. To obtain an access token, you'll first need a refresh token, which is long-lived and does not expire.
  termsOfService: https://mobilitydatabase.org/terms-and-conditions
  contact:
    name: MobilityData
    url: https://mobilitydata.org/
    email: api@mobilitydata.org
  license:
    name: MobilityData License
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.mobilitydatabase.org/
    description: Prod release environment
  - url: https://api-qa.mobilitydatabase.org/
    description: Pre-prod environment
  - url: https://api-dev.mobilitydatabase.org/
    description: Development environment
  - url: http://localhost:8080/
    description: Local development environment

tags:
  - name: "feeds"
    description: "Feeds of the Mobility Database"
  - name: "datasets"
    description: "Datasets of the Mobility Database"
  - name: "metadata"
    description: "Metadata about the API"

paths:
  /v1/feeds:
    get:
      description: Get some (or all) feeds from the Mobility Database. The items are sorted by provider in alphabetical ascending order.
      tags:
        - "feeds"
      operationId: getFeeds
      parameters:
        - $ref: "#/components/parameters/limit_query_param"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/status"
        - $ref: "#/components/parameters/provider"
        - $ref: "#/components/parameters/producer_url"
        - $ref: "#/components/parameters/is_official_query_param"

      security:
        - Authentication: [ ]
      responses:
        200:
          description: >
            Successful pull of the feeds common info. 
            This info has a reduced set of fields that are common to all types of feeds.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicFeeds"

  /v1/feeds/{id}:
    parameters:
      - $ref: "#/components/parameters/feed_id_path_param"
    get:
      description: Get the specified feed from the Mobility Database.
      tags:
        - "feeds"
      operationId: getFeed
      security:
        - Authentication: []
      responses:
        200:
          description: >
            Successful pull of the feeds common info for the provided ID.
            This info has a reduced set of fields that are common to all types of feeds.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicFeed"

  /v1/gtfs_feeds:
    get:
      description: Get some (or all) GTFS feeds from the Mobility Database.
      tags:
        - "feeds"
      operationId: getGtfsFeeds
      parameters:
        - $ref: "#/components/parameters/limit_query_param"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/provider"
        - $ref: "#/components/parameters/producer_url"
        - $ref: "#/components/parameters/country_code"
        - $ref: "#/components/parameters/subdivision_name"
        - $ref: "#/components/parameters/municipality"
        - $ref: "#/components/parameters/dataset_latitudes"
        - $ref: "#/components/parameters/dataset_longitudes"
        - $ref: "#/components/parameters/bounding_filter_method"
        - $ref: "#/components/parameters/is_official_query_param"

      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the GTFS feeds info.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsFeeds"

  /v1/gtfs_rt_feeds:
    get:
      description: Get some (or all) GTFS Realtime feeds from the Mobility Database.
      tags:
        - "feeds"
      operationId: getGtfsRtFeeds
      parameters:
        - $ref: "#/components/parameters/limit_query_param"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/provider"
        - $ref: "#/components/parameters/producer_url"
        - $ref: "#/components/parameters/entity_types"
        - $ref: "#/components/parameters/country_code"
        - $ref: "#/components/parameters/subdivision_name"
        - $ref: "#/components/parameters/municipality"
        - $ref: "#/components/parameters/is_official_query_param"
      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the GTFS Realtime feeds info.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsRTFeeds"

  /v1/gtfs_feeds/{id}:
    parameters:
      - $ref: "#/components/parameters/feed_id_path_param"
    get:
      description: Get the specified GTFS feed from the Mobility Database. Once a week, we check if the latest dataset has been updated and, if so, we update it in our system accordingly.
      tags:
        - "feeds"
      operationId: getGtfsFeed

      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the requested feed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsFeed"

  /v1/gtfs_rt_feeds/{id}:
    parameters:
      - $ref: "#/components/parameters/feed_id_path_param"
    get:
      description: Get the specified GTFS Realtime feed from the Mobility Database.
      tags:
        - "feeds"
      operationId: getGtfsRtFeed

      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the requested feed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsRTFeed"

  /v1/gtfs_feeds/{id}/datasets:
    parameters:
      - $ref: "#/components/parameters/feed_id_of_datasets_path_param"
    get:
      description: Get a list of datasets related to a GTFS feed. Once a week, we check if the latest dataset has been updated and, if so, we update it in our system accordingly.
      tags:
        - "feeds"
      operationId: getGtfsFeedDatasets
      parameters:
        - $ref: "#/components/parameters/latest_query_param"
        - $ref: "#/components/parameters/limit_query_param"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/downloaded_after"
        - $ref: "#/components/parameters/downloaded_before"

      security:
        -  Authentication: []
      responses:
        200:
          description: Successful pull of the requested datasets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsDatasets"

  /v1/gtfs_feeds/{id}/gtfs_rt_feeds:
    parameters:
      - $ref: "#/components/parameters/feed_id_path_param"
    get:
      description: Get a list of GTFS Realtime related to a GTFS feed.
      tags:
        - "feeds"
      operationId: getGtfsFeedGtfsRtFeeds
      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the GTFS Realtime feeds info related to a GTFS feed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsRTFeeds"

  /v1/datasets/gtfs/{id}:
    get:
      description: Get the specified dataset from the Mobility Database.
      tags:
        - "datasets"
      operationId: getDatasetGtfs
      parameters:
        - $ref: "#/components/parameters/dataset_id_path_param"
      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the requested dataset.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsDataset"

  /v1/metadata:
    get:
      description: Get metadata about this API.
      tags:
        - "metadata"
      operationId: getMetadata
      security:
        - Authentication: []
      responses:
        200:
          description: Successful pull of the metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metadata"

  /v1/search:
    get:
      description: |
        Search feeds on feed name, location and provider's information.
        <br>
        The current implementation leverages the text search functionalities from [PostgreSQL](https://www.postgresql.org/docs/current/textsearch-controls.html), in particulary `plainto_tsquery`.
        <br><br>
        Points to consider while using search endpoint:
        <br>
        - Operators are not currently supported. Operators are ignored as stop-words.
        - Search is based on lexemes(English) and case insensitive. The search_text_query_param is parsed and normalized much as for to_tsvector, then the & (AND) tsquery operator is inserted between surviving words.
        - The search will match all the lexemes with an AND operator. So, all lexemes must be present in the document.
        - Our current implementation only creates English lexemes. We are currently considering adding support to more languages.
        - The order of the words is not relevant for matching. The query __New York__ should give you the same results as __York New__.
        <br><br>
        Example:
        <br>
        Query: New York Transit
        <br>
        Search Executed: 'new' & york & 'transit'
        <br>
        
      operationId: searchFeeds
      tags:
        - "search"
      parameters:
        - $ref: "#/components/parameters/limit_query_param"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/statuses"
        - $ref: "#/components/parameters/feed_id_query_param"
        - $ref: "#/components/parameters/data_type_query_param"
        - $ref: "#/components/parameters/is_official_query_param"
        - $ref: "#/components/parameters/search_text_query_param"
      security:
        - Authentication: []
      responses:
        200:
          description: Successful search feeds using full-text search on feed, location and provider's information, potentially returning a mixed array of different entity types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: The total number of matching entities found regardless the limit and offset parameters.
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/SearchFeedItemResult"

components:
  schemas:
    Redirect:
      type: object
      properties:
        target_id:
          description: The feed ID that should be used in replacement of the current one.
          type: string
          example: mdb-10
        comment:
          description: A comment explaining the redirect.
          type: string
          example: Redirected because of a change of URL.
    BasicFeed:
      type: object
      discriminator:
        propertyName: data_type
        mapping:
          gtfs: '#/components/schemas/GtfsFeed'
          gtfs_rt: '#/components/schemas/GtfsRTFeed'
      properties:
        id:
          description: Unique identifier used as a key for the feeds table.
          type: string
          example: mdb-1210
        data_type:
          type: string
          enum:
            - gtfs
            - gtfs_rt
          example: gtfs
#    Have to put the enum inline because of a bug in openapi-generator
#          $ref: "#/components/schemas/DataType"
        status:
          description: >
            Describes status of the Feed. Should be one of 
              * `active` Feed should be used in public trip planners.
              * `deprecated` Feed is explicitly deprecated and should not be used in public trip planners.
              * `inactive` Feed hasn't been recently updated and should be used at risk of providing outdated information.
              * `development` Feed is being used for development purposes and should not be used in public trip planners.
              * `future` Feed is not yet active but will be in the future.
          type: string
          enum:
            - active
            - deprecated
            - inactive
            - development
            - future
          example: deprecated
#           Have to put the enum inline because of a bug in openapi-generator
#          $ref: "#/components/schemas/FeedStatus"
        created_at:
          description: The date and time the feed was added to the database, in ISO 8601 date-time format.
          type: string
          example: 2023-07-10T22:06:00Z
          format: date-time
        official:
            description: >
                A boolean value indicating if the feed is official or not. 
                Official feeds are provided by the transit agency or a trusted source.
            type: boolean
            example: true
        official_updated_at:
            description: >
                The date and time the official status was last updated, in ISO 8601 date-time format.
            type: string
            example: 2023-07-10T22:06:00Z
            format: date-time
        external_ids:
          $ref: "#/components/schemas/ExternalIds"
        provider:
          description: A commonly used name for the transit provider included in the feed.
          type: string
          example: Los Angeles Department of Transportation (LADOT, DASH, Commuter Express)
        feed_name:
          description: >
            An optional description of the data feed, e.g to specify if the data feed is an aggregate of 
            multiple providers, or which network is represented by the feed.
          type: string
          example: Bus
        note:
         description: A note to clarify complex use cases for consumers.
         type: string
        feed_contact_email:
          description: Use to contact the feed producer.
          type: string
          example: someEmail@ladotbus.com
        source_info:
          $ref: "#/components/schemas/SourceInfo"
        redirects:
          type: array
          items:
            $ref: "#/components/schemas/Redirect"

    GtfsFeed:
      allOf:
        - $ref: "#/components/schemas/BasicFeed"
        - type: object
          properties:
            locations:
              $ref: "#/components/schemas/Locations"
            latest_dataset:
              $ref: "#/components/schemas/LatestDataset"

    GtfsRTFeed:
      allOf:
        - $ref: "#/components/schemas/BasicFeed"
        - type: object
          properties:
            entity_types:
              type: array
              items:
                type: string
                enum:
                  - vp
                  - tu
                  - sa
                example: vp
                description: >
                  The type of realtime entry:
                    * vp - vehicle positions
                    * tu - trip updates
                    * sa - service alerts
#              Have to put the enum inline because of a bug in openapi-generator
#              $ref: "#/components/schemas/EntityTypes"
            feed_references:
              description:
                A list of the GTFS feeds that the real time source is associated with, represented by their MDB source IDs.
              type: array
              items:
                type: string
                example: "mdb-20"
            locations:
              $ref: "#/components/schemas/Locations"

    SearchFeedItemResult:
    # The following schema is used to represent the search results for feeds.
    # The schema is a union of all the possible types(BasicFeed, GtfsFeed and GtfsRTFeed) of feeds that can be returned.
    # This union is not based on its original types due to the limitations of openapi-generator.
    # For the same reason it's not defined as anyOf, but as a single object with all the possible properties.
      type: object
      required:
        - id
        - data_type
        - status
      properties:
        id:
          description: Unique identifier used as a key for the feeds table.
          type: string
          example: mdb-1210
        data_type:
          type: string
          enum:
            - gtfs
            - gtfs_rt
          example: gtfs
#    Have to put the enum inline because of a bug in openapi-generator
#          $ref: "#/components/schemas/DataType"
        status:
          description: >
            Describes status of the Feed. Should be one of
              * `active` Feed should be used in public trip planners.
              * `deprecated` Feed is explicitly deprecated and should not be used in public trip planners.
              * `inactive` Feed hasn't been recently updated and should be used at risk of providing outdated information.
              * `development` Feed is being used for development purposes and should not be used in public trip planners.
              * `future` Feed is not yet active but will be in the future.
          type: string
          enum:
            - active
            - deprecated
            - inactive
            - development
            - future
          example: deprecated
#           Have to put the enum inline because of a bug in openapi-generator
#          $ref: "#/components/schemas/FeedStatus"
        created_at:
          description: The date and time the feed was added to the database, in ISO 8601 date-time format.
          type: string
          example: 2023-07-10T22:06:00Z
          format: date-time
        official:
            description: >
                A boolean value indicating if the feed is official or not. 
                Official feeds are provided by the transit agency or a trusted source.
            type: boolean
            example: true
        external_ids:
          $ref: "#/components/schemas/ExternalIds"
        provider:
          description: A commonly used name for the transit provider included in the feed.
          type: string
          example: Los Angeles Department of Transportation (LADOT, DASH, Commuter Express)
        feed_name:
          description: >
            An optional description of the data feed, e.g to specify if the data feed is an aggregate of 
            multiple providers, or which network is represented by the feed.
          type: string
          example: Bus
        note:
         description: A note to clarify complex use cases for consumers.
         type: string
        feed_contact_email:
          description: Use to contact the feed producer.
          type: string
          example: someEmail@ladotbus.com
        source_info:
          $ref: "#/components/schemas/SourceInfo"
        redirects:
          type: array
          items:
            $ref: "#/components/schemas/Redirect"
        locations:
          $ref: "#/components/schemas/Locations"
        latest_dataset:
          $ref: "#/components/schemas/LatestDataset"
        entity_types:
          type: array
          items:
            type: string
            enum:
              - vp
              - tu
              - sa
            example: vp
            description: >
              The type of realtime entry:
                * vp - vehicle positions
                * tu - trip updates
                * sa - service alerts
#              Have to put the enum inline because of a bug in openapi-generator
#              $ref: "#/components/schemas/EntityTypes"
        feed_references:
          description:
            A list of the GTFS feeds that the real time source is associated with, represented by their MDB source IDs.
          type: array
          items:
            type: string
            example: "mdb-20"

    BasicFeeds:
      type: array
      items:
        $ref: "#/components/schemas/BasicFeed"

    GtfsFeeds:
      type: array
      items:
        $ref: "#/components/schemas/GtfsFeed"

    GtfsRTFeeds:
      type: array
      items:
        $ref: "#/components/schemas/GtfsRTFeed"

    LatestDataset:
      type: object
      properties:
        id:
          description: Identifier of the latest dataset for this feed.
          type: string
          example: mdb-1210-202402121801
        hosted_url:
          description: >
            As a convenience, the URL of the latest uploaded dataset hosted by MobilityData. 
            It should be the same URL as the one found in the latest dataset id dataset.
            An alternative way to find this is to use the latest dataset id to obtain the dataset and then use its hosted_url.
          type: string
          format: url
          example: https://storage.googleapis.com/mobilitydata-datasets-prod/mdb-1210/mdb-1210-202402121801/mdb-1210-202402121801.zip
        bounding_box:
          $ref: "#/components/schemas/BoundingBox"
        downloaded_at:
          description: The date and time the dataset was downloaded from the producer, in ISO 8601 date-time format.
          type: string
          example: 2023-07-10T22:06:00Z
          format: date-time
        hash:
          description: A hash of the dataset.
          type: string
          example: ad3805c4941cd37881ff40c342e831b5f5224f3d8a9a2ec3ac197d3652c78e42
        service_date_range_start:
          description: The start date of the service date range for the dataset in UTC. Timing starts at 00:00:00 of the day.
          type: string
          example: 2023-07-10T06:00:00Z
          format: date-time
        service_date_range_end:
          description: The start date of the service date range for the dataset in UTC. Timing ends at 23:59:59 of the day.
          type: string
          example: 2023-07-10T05:59:59+00Z
          format: date-time
        agency_timezone:
          description: The timezone of the agency.
          type: string
          example: America/Los_Angeles
        validation_report:
          type: object
          properties:
            total_error:
              type: integer
              example: 10
              minimum: 0
            total_warning:
              type: integer
              example: 20
              minimum: 0
            total_info:
              type: integer
              example: 30
              minimum: 0
            unique_error_count:
              type: integer
              example: 1
              minimum: 0
            unique_warning_count:
              type: integer
              example: 2
              minimum: 0
            unique_info_count:
              type: integer
              example: 3
              minimum: 0

#    Have to put the enum inline because of a bug in openapi-generator
#    EntityTypes:
#      type: array
#      items:
#        $ref: "#/components/schemas/EntityType"

#    EntityType:
#      type: string
#      enum:
#        - vp
#        - tu
#        - sa
#      example: vp
#      description: >
#        The type of realtime entry:
#          * vp - vehicle positions
#          * tu - trip updates
#          * sa - service alerts

    ExternalIds:
      type: array
      items:
        $ref: "#/components/schemas/ExternalId"

    ExternalId:
      type: object
      properties:
        external_id:
          description: The ID that can be use to find the feed data in an external or legacy database.
          type: string
          example: 1210
        source:
          description: The source of the external ID, e.g. the name of the database where the external ID can be used.
          type: string
          example: mdb

    SourceInfo:
      type: object
      properties:
        producer_url:
          description: >
            URL where the producer is providing the dataset. 
            Refer to the authentication information to know how to access this URL.
          type: string
          format: url
          example: https://ladotbus.com/gtfs
        authentication_type:
          description: >
            Defines the type of authentication required to access the `producer_url`. Valid values for this field are:
              * 0 or (empty) - No authentication required.
              * 1 - The authentication requires an API key, which should be passed as value of the parameter api_key_parameter_name in the URL. Please visit URL in authentication_info_url for more information.
              * 2 - The authentication requires an HTTP header, which should be passed as the value of the header api_key_parameter_name in the HTTP request.
            When not provided, the authentication type is assumed to be 0.
          type: integer
          enum:
            - 0
            - 1
            - 2
          example: 2
        authentication_info_url:
          description: >
            Contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. 
            This field is required for `authentication_type=1` and `authentication_type=2`.
          type: string
          format: url
          example: https://apidevelopers.ladottransit.com
        api_key_parameter_name:
          type: string
          description: >
            Defines the name of the parameter to pass in the URL to provide the API key.
            This field is required for `authentication_type=1` and `authentication_type=2`.
          example: Ocp-Apim-Subscription-Key
        license_url:
          description: A URL where to find the license for the feed.
          type: string
          format: url
          example: https://www.ladottransit.com/dla.html

    Locations:
      type: array
      items:
        $ref: "#/components/schemas/Location"

    Location:
      type: object
      properties:
        country_code:
          description: >
            ISO 3166-1 alpha-2 code designating the country where the system is located. 
            For a list of valid codes [see here](https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2).
          type: string
          example: US
        country:
            description: The english name of the country where the system is located.
            type: string
            example: United States
        subdivision_name:
          description: >
            ISO 3166-2 english subdivision name designating the subdivision (e.g province, state, region) where the system is located. 
            For a list of valid names [see here](https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2).
          type: string
          example: California
        municipality:
          description: Primary municipality in english in which the transit system is located.
          type: string
          example: Los Angeles

#    Have to put the enum inline because of a bug in openapi-generator
#    FeedStatus:
#      description: >
#        Describes status of the Feed. Should be one of
#          * `active` Feed should be used in public trip planners.
#          * `deprecated` Feed is explicitly deprecated and should not be used in public trip planners.
#          * `inactive` Feed hasn't been recently updated and should be used at risk of providing outdated information.
#          * `development` Feed is being used for development purposes and should not be used in public trip planners.
#          * `future` Feed is not yet active but will be in the future
#      type: string
#      enum:
#        - active
#        - deprecated
#        - inactive
#        - development
#        - future
#      example: active

    BasicDataset:
      type: object
      properties:
        id:
          description: Unique identifier used as a key for the datasets table.
          type: string
          example: mdb-10-202402080058
        feed_id:
          description: ID of the feed related to this dataset.
          type: string
          example: mdb-10

    GtfsDataset:
      allOf:
        - $ref: "#/components/schemas/BasicDataset"
        - type: object
          properties:
            hosted_url:
              description: The URL of the dataset data as hosted by MobilityData. No authentication required.
              type: string
              example: https://storage.googleapis.com/storage/v1/b/mdb-latest/o/us-maine-casco-bay-lines-gtfs-1.zip?alt=media
            note:
              description: A note to clarify complex use cases for consumers.
              type: string
            downloaded_at:
              description: The date and time the dataset was downloaded from the producer, in ISO 8601 date-time format.
              type: string
              example: 2023-07-10T22:06:00Z
              format: date-time
            hash:
              description: A hash of the dataset.
              type: string
              example: 6497e85e34390b8b377130881f2f10ec29c18a80dd6005d504a2038cdd00aa71
            bounding_box:
              $ref: "#/components/schemas/BoundingBox"
            validation_report:
              $ref: "#/components/schemas/ValidationReport"
            service_date_range_start:
              description: The start date of the service date range for the dataset in UTC. Timing starts at 00:00:00 of the day.
              type: string
              example: 2023-07-10T06:00:00Z
              format: date-time
            service_date_range_end:
              description: The start date of the service date range for the dataset in UTC. Timing ends at 23:59:59 of the day.
              type: string
              example: 2023-07-10T05:59:59+00Z
              format: date-time
            agency_timezone:
              description: The timezone of the agency.
              type: string
              example: America/Los_Angeles

    BoundingBox:
      description: Bounding box of the dataset when it was first added to the catalog.
      type: object
      properties:
        minimum_latitude:
          description: The minimum latitude for the dataset bounding box.
          type: number
          example: 33.721601
        maximum_latitude:
          description: The maximum latitude for the dataset bounding box.
          type: number
          example: 34.323077
        minimum_longitude:
          description: The minimum longitude for the dataset bounding box.
          type: number
          example: -118.882829
        maximum_longitude:
          description: The maximum longitude for the dataset bounding box.
          type: number
          example: -118.131748

    GtfsDatasets:
      type: array
      items:
        $ref: "#/components/schemas/GtfsDataset"

    Metadata:
      type: object
      properties:
        version:
          type: string
          example: 1.0.0
        commit_hash:
          type: string
          example: 8635fdac4fbff025b4eaca6972fcc9504bc1552d

    ValidationReport:
      description: Validation report
      type: object
      properties:
        validated_at:
          description: The date and time the report was generated, in ISO 8601 date-time format.
          type: string
          example: 2023-07-10T22:06:00Z
          format: date-time
        features:
          description: An array of features for this dataset.
          type: array
          items:
            type: string
            example: Fares_V1
        validator_version:
          type: string
          example: 4.2.0
        total_error:
          type: integer
          example: 10
          minimum: 0
        total_warning:
          type: integer
          example: 20
          minimum: 0
        total_info:
          type: integer
          example: 30
          minimum: 0
        unique_error_count:
          type: integer
          example: 1
          minimum: 0
        unique_warning_count:
          type: integer
          example: 2
          minimum: 0
        unique_info_count:
          type: integer
          example: 3
          minimum: 0
        url_json:
          type: string
          format: url
          description: JSON validation report URL
          example: https://storage.googleapis.com/mobilitydata-datasets-dev/mdb-10/mdb-10-202312181718/mdb-10-202312181718-report-4_2_0.json
        url_html:
          type: string
          format: url
          description: HTML validation report URL
          example: https://storage.googleapis.com/mobilitydata-datasets-dev/mdb-10/mdb-10-202312181718/mdb-10-202312181718-report-4_2_0.html
#        url_system_errors:
#          type: string
#          format: url
#          description: JSON validation system errors URL
#          example: https://storage.googleapis.com/mobilitydata-datasets-dev/mdb-10/mdb-10-202312181718/mdb-10-202312181718-system-errors-4_2_0.json

#    Have to put the enum inline because of a bug in openapi-generator
#    DataType:
#      type: string
#      enum:
#        - gtfs
#        - gtfs_rt
#      example: gtfs
  parameters:

    status:
      name: status
      in: query
      description: Filter feeds by their status. [Status definitions defined here](https://github.com/MobilityData/mobility-database-catalogs?tab=readme-ov-file#gtfs-schedule-schema)
      required: false
      schema:
        type: string
        enum:
          - active
          - deprecated
          - inactive
          - development
          - future
    statuses:
    # This parameter name is kept as status to maintain backward compatibility.
      name: status
      in: query
      description: Filter feeds by their status. [Status definitions defined here](https://github.com/MobilityData/mobility-database-catalogs?tab=readme-ov-file#gtfs-schedule-schema)
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - active
            - deprecated
            - inactive
            - development
            - future
    provider:
      name: provider
      in: query
      description: List only feeds with the specified value. Can be a partial match. Case insensitive.
      required: false
      schema:
        type: string
        example: Los Angeles Department of Transportation (LADOT, DASH, Commuter Express)
    producer_url:
      name: producer_url
      in: query
      required: false
      description: >
        List only feeds with the specified value. Can be a partial match. Case insensitive.
      schema:
        type: string
        format: url
        example: https://ladotbus.com
    entity_types:
      name: entity_types
      in: query
      description: Filter feeds by their entity type. Expects a comma separated list of all types to fetch.
      required: false
      schema:
        type: string
        example: vp,sa,tu
    country_code:
      name: country_code
      in: query
      description: Filter feeds by their exact country code.
      schema:
        type: string
        example: US
    subdivision_name:
      name: subdivision_name
      in: query
      description: List only feeds with the specified value. Can be a partial match. Case insensitive.
      schema:
        type: string
        example: California
    municipality:
      name: municipality
      in: query
      description: List only feeds with the specified value. Can be a partial match. Case insensitive.
      schema:
        type: string
        example: Los Angeles
    downloaded_after:
      name: downloaded_after
      in: query
      description: Filter feed datasets with downloaded date greater or equal to given date. Date should be in ISO 8601 date-time format.
      schema:
        type: string
        format: date-time
        example: 2023-07-00T22:06:00Z
    downloaded_before:
      name: downloaded_before
      in: query
      description: Filter feed datasets with downloaded date less or equal to given date. Date should be in ISO 8601 date-time format.
      schema:
        type: string
        format: date-time
        example: 2023-07-20T22:06:00Z

    dataset_latitudes:
      name: dataset_latitudes
      in: query
      description: >
       Specify the minimum and maximum latitudes of the bounding box to use for filtering.
        <br>Filters by the bounding box of the `LatestDataset` for a feed.
        <br>Must be specified alongside `dataset_longitudes`.
      required: False
      schema:
        type: string
        example: 33.5,34.5

    dataset_longitudes:
      name: dataset_longitudes
      in: query
      description: >
        Specify the minimum and maximum longitudes of the bounding box to use for filtering.
        <br>Filters by the bounding box of the `LatestDataset` for a feed.
        <br>Must be specified alongside `dataset_latitudes`.
      required: False
      schema:
        type: string
        example: -118.0,-119.0

    bounding_filter_method:
      name: bounding_filter_method
      in: query
      required: False
      schema:
        type: string
        enum:
          - completely_enclosed
          - partially_enclosed
          - disjoint
        default: completely_enclosed
      description: >
        Specify the filtering method to use with the dataset_latitudes and dataset_longitudes parameters.
         * `completely_enclosed` - Get resources that are completely enclosed in the specified bounding box.
         * `partially_enclosed` - Get resources that are partially enclosed in the specified bounding box.
         * `disjoint` - Get resources that are completely outside the specified bounding box.
      example: completely_enclosed

    latest_query_param:
      name: latest
      in: query
      description: If true, only return the latest dataset.
      required: False
      schema:
        type: boolean
        default: false

    is_official_query_param:
      name: is_official
      in: query
      description: If true, only return official feeds.
      required: False
      schema:
        type: boolean
        default: false

    limit_query_param:
      name: limit
      in: query
      description: The number of items to be returned.
      required: False
      schema:
        type: integer
        minimum: 0
        example: 10
        
    offset:
      name: offset
      in: query
      description: Offset of the first item to return.
      required: False
      schema:
        type: integer
        minimum: 0
        default: 0
        example: 0

    search_text_query_param:
      name: search_query
      in: query
      description: General search query to match against transit provider, location, and feed name.
      required: False
      schema:
        type: string

    data_type_query_param:
      name: data_type
      in: query
      description: Unique identifier used as a key for the feeds table.
      required: False
      schema:
        type: string
        enum:
          - gtfs
          - gtfs_rt
        example: gtfs

    feed_id_query_param:
      name: feed_id
      in: query
      description: The feed ID of the requested feed.
      required: False
      schema:
        type: string
        example: mdb-1210

    feed_id_path_param:
      name: id
      in: path
      description: The feed ID of the requested feed.
      required: True
      schema:
        type: string
        example: mdb-1210

    feed_id_of_datasets_path_param:
      name: id
      in: path
      description: The ID of the feed for which to obtain datasets.
      required: True
      schema:
        type: string
        example: mdb-10

    dataset_id_path_param:
      name: id
      in: path
      description: The ID of the requested dataset.
      required: True
      schema:
        type: string
        example: mdb-1210-202402121801

  securitySchemes:
    Authentication:
      $ref: "./BearerTokenSchema.yaml#/components/securitySchemes/Authentication"

security:
  - Authentication: []