swagger: "2.0"
schemes:
  - https
host: api.transitfeeds.com
basePath: /v1
info:
  contact:
    email: support@transitfeeds.com
    name: TransitFeeds.com
    url: https://transitfeeds.com/issues
    x-twitter: openmobilityorg
  description: |
    API to view feed information and download feeds from TransitFeeds.com
  title: TransitFeeds API
  version: 1.0.0
  x-apisguru-categories:
    - location
  x-logo:
    url: https://twitter.com/openmobilityorg/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://transitfeeds.com/api/transitfeeds-api.yaml
      version: "2.0"
  x-providerName: transitfeeds.com
produces:
  - application/json
paths:
  /getFeedVersions:
    get:
      description: |
        This API call allows you to easily see every single feed update in the TranstiFeeds.com system. Since this can be quite
        long, it's also possible to filter this list by a single feed ID.
      operationId: getFeedVersions
      parameters:
        - default: YOUR_API_KEY
          description: Your personal API key, used for authentication.
          in: query
          name: key
          required: true
          type: string
        - description: If you only want to retrieve feed versions for a particular feed, include its ID here. You can use the `/getFeeds` call to discover feed IDs.
          in: query
          name: feed
          required: false
          type: string
        - default: 1
          description: |
            The page number of results to return. For example, if you specify a `page` of `2` with a `limit` of 10, then results 11-20 are returned.
            The number of pages available is included in the response.
          in: query
          name: page
          required: false
          type: integer
        - default: 10
          description: The maximum number of results to return..
          in: query
          name: limit
          required: false
          type: integer
        - default: 1
          description: To include any errors detected when importing this feed in the response, specify a valud of `1`.
          enum:
            - 0
            - 1
          in: query
          name: err
          required: false
          type: integer
        - default: 1
          description: To include any warnings detected when importing this feed in the response, specify a valud of `1`.
          enum:
            - 0
            - 1
          in: query
          name: warn
          required: false
          type: integer
      responses:
        "200":
          description: The response for a valid `/getFeedVersions` API call.
          schema:
            $ref: "#/definitions/GetFeedVersionsResponse"
      summary: Retrieve a list of versions of specified (or all) feeds.
  /getFeeds:
    get:
      description: |
        Used this API to retrieve a list of feeds in the system. Doing so can be usedful to discover feed IDs that
        can be used in other API calls.
      operationId: getFeeds
      parameters:
        - default: YOUR_API_KEY
          description: Your personal API key, used for authentication.
          in: query
          name: key
          required: true
          type: string
        - description: |
            This is the unique ID of a location. If specified, feeds will only be returned that belong to this location
            (and perhaps sub-locations too, depending on the `descendants` value). You can use the `/getLocations` API
            endpoint to determine location IDs.
          in: query
          name: location
          required: false
          type: integer
        - default: 1
          description: If a location is specified in `location`, this flag can be used to control if returned feeds must be assigned directly to the location, or if feeds belonging to sub-locations can also be returned. If `0`, then feeds must be assigned directly to the specified location.
          enum:
            - 0
            - 1
          in: query
          name: descendants
          required: false
          type: integer
        - default: 1
          description: |
            The page number of results to return. For example, if you specify a `page` of `2` with a `limit` of 10, then results 11-20 are returned.
            The number of pages available is included in the response.
          in: query
          name: page
          required: false
          type: integer
        - default: 10
          description: The maximum number of results to return..
          in: query
          name: limit
          required: false
          type: integer
        - description: The type of feeds to return. If unspecified, feeds of all types are returned.
          enum:
            - gtfs
            - gtfsrealtime
          in: query
          name: type
          required: false
          type: string
      responses:
        "200":
          description: The response for a valid `/getFeeds` API call.
          schema:
            $ref: "#/definitions/GetFeedsResponse"
      summary: Retrieve a list of feeds.
  /getLatestFeedVersion:
    get:
      description: |
        Once you have used `/getFeeds` to discover a feed's URL, you can use this endpoint to download its latest version from TranstiFeeds.
        It will be unmodified in the original format from the provider.
      operationId: getLatestFeedVersion
      parameters:
        - default: YOUR_API_KEY
          description: Your personal API key, used for authentication.
          in: query
          name: key
          required: true
          type: string
        - description: The ID of the feed to retrieve the latest feed version for. You can use the `/getFeeds` call to discover feed IDs.
          in: query
          name: feed
          required: true
          type: string
      responses:
        "200":
          description: The response for a `/getLatestFeedVersion` API call that includes invalid request parameters.
          schema:
            $ref: "#/definitions/GetLatestFeedVersionResponse"
        "302":
          description: |
            If a `/getLatestFeedVersion` request is valid, then a HTTP 302 Temporary Redirect is issued to the download location.
            For example, if the requested feed is a GTFS feed, then this will redirect to the URL of the latest zip file for
            this feed.
          headers:
            Location:
              type: string
      summary: Retrieve the download URL for the latest version of a feed.
  /getLocations:
    get:
      description: |
        Retrieve a list of locations. Each location (except for the root) has a parent location, and each
        location has zero or more child locations. This hierarchy is generally structured so countries contain
        states, states contain cities (although this typically depends on the country).
      operationId: getLocations
      parameters:
        - default: YOUR_API_KEY
          description: Your personal API key, used for authentication.
          in: query
          name: key
          required: true
          type: string
      responses:
        "200":
          description: The response for a valid `getLocations` API call.
          schema:
            $ref: "#/definitions/GetLocationsResponse"
        "401":
          description: The response for invalid key or permission denied.
          schema:
            $ref: "#/definitions/API401Response"
        "404":
          description: The response for invalid API method.
          schema:
            $ref: "#/definitions/API404Response"
      summary: Retrieve a list of locations.
definitions:
  API401Response:
    description: This element contains information about a 401 Unauthorized error.
    properties:
      msg:
        description: Description of the error.
        type: string
      status:
        description: Indicates the status of this request.
        enum:
          - INVALIDKEY
          - PERMISSIONDENIED
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  API404Response:
    description: This element contains information about a 404 File Not Found error.
    properties:
      msg:
        description: Description of the error.
        type: string
      status:
        description: Indicates the status of this request.
        enum:
          - INVALIDMETHOD
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  Feed:
    description: Contains the information about a single feed.
    properties:
      id:
        description: |
          The unique ID for this feed. This is constructed using the ID of the feed's provider and an internal ID. This ID
          can be used in other calls, such as `/getFeedVersions` or `/getLatestFeedVersion`.
        type: string
      l:
        $ref: "#/definitions/Location"
        description: The location to which this feed is assigned. The location ID can subsequently be used in calls to `/getFeeds`.
      latest:
        description: |
          If available, contains information about the latest version of this feed. This can help to determine if you need to call
          `/getLatestFeedVersion` to retrieve a newer version of a feed.
        properties:
          ts:
            description: Indicates the timestamp of the latest feed version (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
            type: integer
        type: object
      t:
        description: The title of the feed as it appears on TransitFeeds.com
        type: string
      ty:
        description: The type of feed (such as GTFS or GTFS-realtime).
        enum:
          - gtfs
          - gtfsrealtime
        type: string
      u:
        description: Contains URLs with additional information about this feed.
        properties:
          d:
            description: |
              If available, this contains a URL to download the feed directly from the provider (as opposed to downloading from TransitFeeds.com).
            type: string
          i:
            description: |
              If available, this contains a URL with additional information about registering or downloading the feed from the provider.
            type: string
        type: object
    required:
      - id
      - ty
      - t
      - l
    type: object
  FeedVersion:
    description: Contains the information about a single feed version.
    properties:
      d:
        description: |
          Contains the start/finish dates for this feed version, if available.
        properties:
          f:
            description: The start date of the feed version, in `YYYYMMDD` format.
            type: string
          s:
            description: The start date of the feed version, in `YYYYMMDD` format.
            type: string
        type: object
      err:
        description: If you have included an `err` value of `1` in your request, then any errors detected when importing this feed version are included.
        items:
          $ref: "#/definitions/FeedVersionIssue"
        type: array
      f:
        $ref: "#/definitions/Feed"
        description: The feed to which this feed version belongs.
      id:
        description: The unique ID for this feed. This is constructed using the feed ID and an internal ID (generally the date it was imported, but not always, so do not rely on this).
        type: string
      size:
        description: The filesize in bytes of the feed version when compressed.
        type: integer
      ts:
        description: The timestamp of when this feed version was registered in the TransitFeeds.com system (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
      url:
        description: |
          This is the URL to directly download the feed version via the TranstiFeeds.com web site (and not via the API). In other words,
          you can provide a download URL without exposing your API key to others.
        type: string
      warn:
        description: If you have included a `warn` value of `1` in your request, then any warnings detected when importing this feed version are included.
        items:
          $ref: "#/definitions/FeedVersionIssue"
        type: array
    required:
      - id
      - f
      - ts
      - size
      - url
    type: object
  FeedVersionIssue:
    description: Contains the information about a single error or warning associated with a feed version.
    properties:
      c:
        description: The column name (if referring to a GTFS file / CSV file) associated with the issue.
        type: string
      f:
        description: The filename associated with this issue.
        type: string
      l:
        description: The line number in the given file associated with the issue.
        type: string
      m:
        description: A description of the issue.
        type: string
    type: object
  GetFeedVersionsResponse:
    description: This element contains the response for a `/getFeedVersions` request.
    properties:
      msg:
        description: Description of the error, if the `status` value was not `OK`.
        type: string
      results:
        description: Contains requested data for a valid request.
        properties:
          feeds:
            description: An array of zero or more feed versions.
            items:
              $ref: "#/definitions/FeedVersion"
            type: array
          input:
            description: If the status value is `MISSINGINPUT` or `INVALIDINPUT`, this field contains the name of the offending field.
            type: string
          limit:
            description: |
              The maximum number of feed versions that can be returned in this response. If the final page is being
              requested then this number may be larger than the number of feed versions returned in `versions`.
            type: integer
          numPages:
            description: The number of pages available, based on the `total` and `limit`.
            type: integer
          page:
            description: The page number being requested, based on the maximum number than can be returned from in `limit`.
            type: integer
          total:
            description: |
              The total number of feed versions found based on the request input. Note that this number may be larger
              than the number of feed versions returned in `versions`, based on the values for `limit` and `page`.
            type: integer
        type: object
      status:
        description: |
          Indicates the success status of this request. The following values are possible:

          * `OK` - Request was valid.
          * `DEPRECATED` - Request resolved to a deprecated resource which will not be returned.
          * `EMPTYKEY` - Request was missing API key.
          * `MISSINGINPUT` - A required request parameter was missing.
          * `INVALIDINPUT` - A request parameter was invalid.
        enum:
          - OK
          - DEPRECATED
          - EMPTYKEY
          - MISSINGINPUT
          - INVALIDINPUT
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  GetFeedsResponse:
    description: This element contains the response for a `/getFeeds` request.
    properties:
      msg:
        description: Description of the error, if the `status` value was not `OK`.
        type: string
      results:
        description: Contains requested data for a valid request.
        properties:
          feeds:
            description: An array of zero or more feeds.
            items:
              $ref: "#/definitions/Feed"
            type: array
          input:
            description: If the status value is `MISSINGINPUT` or `INVALIDINPUT`, this field contains the name of the offending field.
            type: string
          limit:
            default: 10
            description: |
              The maximum number of feeds that can be returned in this response. If the final page is being
              requested then this number may be larger than the number of feeds returned in `feeds`.
            type: integer
          numPages:
            description: The number of pages available, based on the `total` and `limit`.
            type: integer
          page:
            description: The page number being requested, based on the maximum number than can be returned from in `limit`.
            type: integer
          total:
            description: |
              The total number of feeds found based on the request input. Note that this number may be larger
              than the number of feeds returned in `feeds`, based on the values for `limit` and `page`.
            type: integer
        type: object
      status:
        description: |
          Indicates the success status of this request. The following values are possible:

          * `OK` - Request was valid.
          * `EMPTYKEY` - Request was missing API key.
          * `MISSINGINPUT` - A required request parameter was missing.
          * `INVALIDINPUT` - A request parameter was invalid.
        enum:
          - OK
          - EMPTYKEY
          - MISSINGINPUT
          - INVALIDINPUT
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  GetLatestFeedVersionResponse:
    description: This element contains the response for a `/getLatestFeedVersion` request.
    properties:
      msg:
        description: Description of the error, if the `status` value was not `OK`.
        type: string
      results:
        description: Contains requested data for a valid request.
        properties:
          feeds:
            description: An array of zero or more feed versions.
            items:
              $ref: "#/definitions/FeedVersion"
            type: array
          input:
            description: If the status value is `MISSINGINPUT` or `INVALIDINPUT`, this field contains the name of the offending field.
            type: string
          limit:
            default: 10
            description: |
              The maximum number of feed versions that can be returned in this response. If the final page is being
              requested then this number may be larger than the number of feed versions returned in `versions`.
            type: integer
          numPages:
            description: The number of pages available, based on the `total` and `limit`.
            type: integer
          page:
            description: The page number being requested, based on the maximum number than can be returned from in `limit`.
            type: integer
          total:
            description: |
              The total number of feed versions found based on the request input. Note that this number may be larger
              than the number of feed versions returned in `versions`, based on the values for `limit` and `page`.
            type: integer
        type: object
      status:
        description: |
          Indicates the success status of this request. The following values are possible:

          * `OK` - Request was valid.
          * `DEPRECATED` - Request resolved to a deprecated resource which will not be returned.
          * `EMPTYKEY` - Request was missing API key.
          * `MISSINGINPUT` - A required request parameter was missing.
          * `INVALIDINPUT` - A request parameter was invalid.
          * `OTHER` - Some other error occurred.
        enum:
          - OK
          - DEPRECATED
          - EMPTYKEY
          - MISSINGINPUT
          - INVALIDINPUT
          - OTHER
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  GetLocationsResponse:
    description: This element contains the response for a `/getLocations` request.
    properties:
      msg:
        description: Description of the error, if the `status` value was not `OK`.
        type: string
      results:
        description: Contains requested data for a valid request.
        properties:
          input:
            description: If the status value is `MISSINGINPUT` or `INVALIDINPUT`, this field contains the name of the offending field.
            type: string
          locations:
            description: An array of zero or more locations.
            items:
              $ref: "#/definitions/Location"
            type: array
        type: object
      status:
        description: |
          Indicates the success status of this request. The following values are possible:

          * `OK` - Request was valid.
          * `EMPTYKEY` - Request was missing API key.
          * `MISSINGINPUT` - A required request parameter was missing.
          * `INVALIDINPUT` - A request parameter was invalid.
        enum:
          - OK
          - EMPTYKEY
          - MISSINGINPUT
          - INVALIDINPUT
        type: string
      ts:
        description: Indicates the timestamp (in number of seconds since the epoch (January 1 1970 00:00:00 GMT).
        type: integer
    type: object
  Location:
    description: Contains the information about a single location.
    properties:
      id:
        description: The unique ID for this location.
        type: integer
      lat:
        description: The latitude of the approximate point of this location.
        format: double
        type: number
      lng:
        description: The longitude of the approximate point of this location.
        format: double
        type: number
      n:
        description: The title of this location on its own (i.e. without any state or country information).
        type: string
      pid:
        description: The ID for the parent location. If a location has no parent this value is `0`.
        type: integer
      t:
        description: |
          The title of this location. This may include state/province and country, depending
           on the location of type it refers to.
        type: string
    required:
      - id
      - pid
      - t
      - n
      - lat
      - lng
    type: object
