Urban Sharing - Provider (2.0)
Download OpenAPI specification:
Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com
The Provider API endpoints are intended to be implemented by mobility providers and consumed by regulatory agencies. Data is pulled from providers by agencies. When a municipality queries information from a mobility provider, the Provider API has a historical view of operations in a standard format. This specification contains a data standard for mobility as a service providers to define a RESTful API for municipalities to access on-demand. 
/vehicles
Get a list of known vehicles, with properties that do not change often.
Authorizations:
bearer
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "links": { },
- "last_updated": 0,
- "ttl": 0,
- "vehicles": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "vehicle_id": "string",
- "vehicle_type": "bicycle",
- "vehicle_attributes": { },
- "propulsion_types": [
- "human"
], - "accessibility_attributes": "string",
- "battery_capacity": 0,
- "fuel_capacity": 0,
- "maximum_speed": 0
}
]
]
}/vehicles/status
Get a list of known vehicles, with specific vehicle status records that are updated frequently.
Authorizations:
bearer
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "links": { },
- "last_updated": 0,
- "ttl": 0,
- "vehicles_status": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "last_event": {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "event_id": "string",
- "vehicle_state": "removed",
- "event_types": [
- "agency_drop_off"
], - "timestamp": 0,
- "publication_time": 0,
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "event_geographies": [
- "string"
], - "battery_percent": 0,
- "fuel_percent": 0,
- "trip_ids": [
- "string"
], - "associated_ticket": "string"
}, - "last_telemetry": {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "telemetry_id": "string",
- "timestamp": 0,
- "trip_ids": "string",
- "journey_id": "string",
- "stop_id": "string",
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "location_type": "street",
- "battery_percent": 0,
- "fuel_percent": 0,
- "tipped_over": true
}
}
]
]
}/vehicles/status/{device_id}
Get the specified vehicle, with specific vehicle status records that are updated frequently.
Authorizations:
bearer
path Parameters
| device_id required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "last_updated": 0,
- "ttl": 0,
- "vehicles_status": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "last_event": {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "event_id": "string",
- "vehicle_state": "removed",
- "event_types": [
- "agency_drop_off"
], - "timestamp": 0,
- "publication_time": 0,
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "event_geographies": [
- "string"
], - "battery_percent": 0,
- "fuel_percent": 0,
- "trip_ids": [
- "string"
], - "associated_ticket": "string"
}, - "last_telemetry": {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "telemetry_id": "string",
- "timestamp": 0,
- "trip_ids": "string",
- "journey_id": "string",
- "stop_id": "string",
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "location_type": "street",
- "battery_percent": 0,
- "fuel_percent": 0,
- "tipped_over": true
}
}
]
]
}/vehicles/{device_id}
Get the specified vehicle, with properties that do not change often.
Authorizations:
bearer
path Parameters
| device_id required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "last_updated": 0,
- "ttl": 0,
- "vehicles": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "vehicle_id": "string",
- "vehicle_type": "bicycle",
- "vehicle_attributes": { },
- "propulsion_types": [
- "human"
], - "accessibility_attributes": "string",
- "battery_capacity": 0,
- "fuel_capacity": 0,
- "maximum_speed": 0
}
]
]
}/trips
Get all trips with an end time occurring within the hour.
Authorizations:
bearer
query Parameters
| end_time required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "trips": [
- [
- {
- "provider_id": "string",
- "data_provider_id": "string",
- "device_id": "string",
- "trip_id": "string",
- "trip_type": "string",
- "trip_attributes": { },
- "fare_attributes": { },
- "start_time": 0,
- "end_time": 0,
- "start_location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "end_location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "duration": 0,
- "distance": 0,
- "publication_time": 0,
- "accessibility_attributes": "string",
- "parking_verification_url": "string",
- "parking_category": "corral",
- "standard_cost": "string",
- "actual_cost": "string",
- "currency": "string"
}
]
]
}/telemetry
Get all telemetry with timestamp occurring within the hour.
Authorizations:
bearer
query Parameters
| telemetry_time required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "telemetry": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "telemetry_id": "string",
- "timestamp": 0,
- "trip_ids": "string",
- "journey_id": "string",
- "stop_id": "string",
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "location_type": "street",
- "battery_percent": 0,
- "fuel_percent": 0,
- "tipped_over": true
}
]
]
}/events/historical
Get all status changes with an event time occurring within the hour.
Authorizations:
bearer
query Parameters
| event_time required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "events": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "event_id": "string",
- "vehicle_state": "removed",
- "event_types": [
- "agency_drop_off"
], - "timestamp": 0,
- "publication_time": 0,
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "event_geographies": [
- "string"
], - "battery_percent": 0,
- "fuel_percent": 0,
- "trip_ids": [
- "string"
], - "associated_ticket": "string"
}
]
]
}/events/recent
Get all status changes at most two weeks old.
Authorizations:
bearer
query Parameters
| start_time required | number |
| end_time required | number |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "links": { },
- "events": [
- [
- {
- "device_id": "string",
- "provider_id": "string",
- "data_provider_id": "string",
- "event_id": "string",
- "vehicle_state": "removed",
- "event_types": [
- "agency_drop_off"
], - "timestamp": 0,
- "publication_time": 0,
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "event_geographies": [
- "string"
], - "battery_percent": 0,
- "fuel_percent": 0,
- "trip_ids": [
- "string"
], - "associated_ticket": "string"
}
]
]
}/stops
Stop information should be updated on a near-realtime basis by providers who operate docked mobility devices in a given municipality.
Authorizations:
bearer
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "last_updated": 0,
- "ttl": 0,
- "stops": [
- [
- {
- "name": "string",
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "capacity": { },
- "provider_id": "string",
- "data_provider_id": "string",
- "geography_id": "string",
- "region_id": "string",
- "short_name": "string",
- "address": "string",
- "post_code": "string",
- "cross_street": "string",
- "parent_stop": "string",
- "image_url": "string",
- "stop_id": "string",
- "last_updated": 0,
- "status": { },
- "num_vehicles_available": { },
- "num_vehicles_disabled": { },
- "rental_methods": [
- "key"
], - "num_places_available": { },
- "num_places_disabled": { },
- "devices": [
- "string"
]
}
]
]
}/stops/{stop_id}
Stop information should be updated on a near-realtime basis by providers who operate docked mobility devices in a given municipality.
Authorizations:
bearer
path Parameters
| stop_id required | string |
Responses
Response samples
- 200
- 500
Content type
application/json
{- "version": "string",
- "last_updated": 0,
- "ttl": 0,
- "stops": [
- [
- {
- "name": "string",
- "location": {
- "altitude": 0,
- "heading": 0,
- "horizontal_accuracy": 0,
- "lat": 0,
- "lng": 0,
- "satellites": 0,
- "speed": 0,
- "vertical_accuracy": 0
}, - "capacity": { },
- "provider_id": "string",
- "data_provider_id": "string",
- "geography_id": "string",
- "region_id": "string",
- "short_name": "string",
- "address": "string",
- "post_code": "string",
- "cross_street": "string",
- "parent_stop": "string",
- "image_url": "string",
- "stop_id": "string",
- "last_updated": 0,
- "status": { },
- "num_vehicles_available": { },
- "num_vehicles_disabled": { },
- "rental_methods": [
- "key"
], - "num_places_available": { },
- "num_places_disabled": { },
- "devices": [
- "string"
]
}
]
]
}/reports/{filename}
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.
Authorizations:
bearer
path Parameters
| filename required | string |
Responses
Response samples
- 500
Content type
application/json
{- "error": "string",
- "error_description": "string",
- "error_details": [
- "string"
]
}