Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Open Mobility Foundation Reports 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 Reports 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: Reports
paths:
/reports:
post:
operationId: post-reports
description: Allows an agency to register aggregated report counts in CSV structure.
summary: /reports
requestBody:
required: true
content:
text/csv:
schema:
$ref: '#/components/schemas/report'
responses:
'201':
description: Report 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:
allOf:
- $ref: '#/components/schemas/response_error_bad_param'
- properties:
item:
$ref: '#/components/schemas/report'
'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:
- Reports
/reports/{filename}:
parameters:
- name: filename
schema:
type: string
pattern: \d{4}-\d{2}\.csv
examples:
- 2023-12.csv
in: path
required: true
description: The name of the report to retrieve, formatted by year and month like `YYYY-MM.csv`
get:
operationId: get-reports-filename
description: Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders.
summary: /reports/{filename}
responses:
'200':
description: Report found.
content:
text/csv:
schema:
$ref: '#/components/schemas/report'
'401':
description: 'Unauthorized: Invalid, expired, or insufficient scope of token.'
'404':
description: Report not found.
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/response_error'
tags:
- Reports
components:
schemas:
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
report:
title: models/report
type: string
description: 'Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS endpoints.
The authenticated reports are monthly, historic flat files that may be pre-generated by the provider.'
x-stoplight:
id: wb2h7rhv8xtur
pattern: ^provider_id,start_date,duration,special_group_type,geography_id,vehicle_type,trip_count,rider_count
examples:
- 'provider_id,start_date,duration,special_group_type,geography_id,vehicle_type,trip_count,rider_count
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,scooter,1302,983
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,scooter,201,104
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,530,200
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,44428624-186b-4fc3-a7fb-124f487464a1,bicycle,75,26
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,687,450
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,scooter,98,45
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,256,104
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,03db06d0-3998-406a-92c7-25a83fc2784a,bicycle,41,16
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,201,140
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,scooter,35,21
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,all_riders,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,103,39
48415839-3e38-4ba5-a557-e45fb4e6a0a3,2019-09-01,P1M,low_income,8ad39dc3-005b-4348-9d61-c830c54c161b,bicycle,15,-1'
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:
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_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
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