Following the [right-hand rule](https://tools.ietf.org/html/rfc7946#section-3.1.6), a clockwise arrangement of points defines the area enclosed by the polygon, where pickup and drop off MAY occur; while a counterclockwise order defines the area outside the polygon, where pickup and drop off MAY NOT occur. |
- \- `properties` | REQUIRED | Object | Location property keys. |
- \- \- `name` | OPTIONAL | String | Indicates the name of the zone as displayed to the riders. |
##### Example:
```jsonc
{
"last_updated": 1609866247,
"ttl": 0,
"version": "1.0",
"data": {
"zones": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"zone_id": "zoneA",
"properties": {
"name": "Montréal Area"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-74.10,
45.35
],
[
-73.30,
45.35
],
[
-73.30,
45.75
],
[
-74.10,
45.75
],
[
-74.10,
45.35
]
],
[
[
-73.60,
45.55
],
[
-73.60,
45.65
],
[
-73.50,
45.65
],
[
-73.50,
45.55
],
[
-73.60,
45.55
]
]
]
}
}
]
}
}
}
```
### operating_rules.json
This file contains operating rules enabling on-demand services between zones or within the same zone, according to time windows and calendars. At least one operating rule MUST be defined. If `start_pickup_window`, `end_pickup_window`, and `end_dropoff_window` are not provided, it is assumed that the on-demand service is available at any hours of the day.
The following fields are all attributes within the main "data" object for this feed.
Field Name | Presence | Type | Description
---|---|---|---
`operating_rules` | REQUIRED | Array | Array that contains one object per operating rule as defined below.
\- `from_zone_id` | REQUIRED | ID | ID from a zone defined in `zones.json` representing the boarding zone for the current rule.
\- `to_zone_id` | REQUIRED | ID | ID from a zone defined in `zones.json` representing the alighting zone for the current rule. `from_zone_id` and `to_zone_id` MAY reference the same zone.
\- `start_pickup_window` | conditionally REQUIRED | Time | Time at which the pickup starts being available in `from_zone_id` defined in this array. If `start_pickup_window` is provided, either `end_pickup_window` or `end_dropoff_window` MUST also be provided.
\- `end_pickup_window` | conditionally REQUIRED | Time | Time at which the pickup stops being available in `from_zone_id` defined in this array. If `end_pickup_window` is provided, `start_pickup_window` MUST be provided.
\- `end_dropoff_window` | conditionally REQUIRED | Time | Time at which the drop off stops being available in `to_zone_id` defined in this array. Some services differ the end of the pickup time and the end of the drop off time (e.g.: The pickup time ends at 10PM in the origin zone but it is still possible to be dropped off in the destination zone until 10:30PM). If `end_dropoff_window` is provided, `start_pickup_window` MUST be provided.
\- `calendars` | REQUIRED | Array | Array of calendar IDs from `calendars.json` defining the dates and days when the pickup and drop off occur.
\- `brand_id` | OPTIONAL | ID | ID from a service brand defined in `service_brands.json`. If this field is not provided, the operating rule applies to every service brand defined in `service_brands.json`.
\- `vehicle_type_id` | REQUIRED | Array | Array of vehicle types used for delivering the on-demand service.
\- `fare_id` | OPTIONAL | ID | Unique identifier of a fare. Used to determine the price of the on-demand service.
##### Example:
```jsonc
{
"last_updated": 1609866247,
"ttl": 0,
"version": "1.0",
"data": {
"operating_rules" : [
{
"from_zone_id": "zoneA",
"to_zone_id": "zoneA",
"start_pickup_window" : "06:00:00",
"end_pickup_window": "09:00:00",
"end_dropoff_window": "09:30:00",
"calendars": ["weekend", "labor_day"],
"brand_id": "large_ride",
"vehicle_type_id": ["large_van"],
"fare_id": "RegularPrice"
}
]
}
}
```
### calendars.json
This file defines the dates and days when on-demand services are available to the riders.
The following fields are all attributes within the main "data" object for this feed.
Field Name | Presence | Type | Description
---|---|---|---
`calendars` | REQUIRED | Array | Array that contains one object per calendar as defined below.
\- `calendar_id` | REQUIRED | ID | Unique identifier of the calendar.
\- `days` | OPTIONAL | Array | Array of abbreviations (first 3 letters) of English names of the days of the week for which this object applies (e.g. `["mon", "tue", "wed", "thu", "fri", "sat, "sun"]`). If days are not defined, it is assumed that the on-demand service is available all days of the week.
\- `start_date` | REQUIRED | Date | Start date for the calendar.
\- `end_date` | REQUIRED | Date | End date for the calendar. The end date MUST be subsequent or equal to the start date.
\- `excepted_dates` | OPTIONAL | Array | Array of dates removing service availability from the calendar.
##### Example:
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"calendars": [
{
"calendar_id": "weekday",
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start_date": "20210901",
"end_date": "20211031",
"excepted_dates": [
"20210906"
]
},
{
"calendar_id": "weekend",
"days": [
"sat",
"sun"
],
"start_date": "20210901",
"end_date": "20211031"
},
{
"calendar_id": "labor_day",
"start_date": "20210906",
"end_date": "20210906"
}
]
}
}
```
### fares.json
This file defines fare calculations for a system.
The following fields are all attributes within the main "data" object for this feed.
Field Name | Presence | Type | Description
---|---|---|---
`fares` | REQUIRED | Array | Array that contains one object per fare defintion as defined below.
\- `fare_id` | REQUIRED | ID | Unique identifier of the fare.
\- `currency` | REQUIRED | Currency code | The currency of the fare.
\- `kilometer` | OPTIONAL | Array | Array of Fare objects defining the price of the service per kilometer. Total cost per rider is the base cost defined in `rider`, plus the addition of all segments in `kilometer`, `minute`, `active_minute`, and `idle_minute`.
\- `minute` | OPTIONAL | Array | Array of Fare objects defining the price of the service per minute, regardless of whether the vehicle is moving or not. Total cost per rider is the base cost defined in `rider`, plus the addition of all relevant segments in `kilometer`, `minute`, `active_minute`, and `idle_minute`.
\- `active_minute` | OPTIONAL | Array | Array of Fare objects defining the price of the service per minute, while the vehicle is actively moving. Total cost per rider is the base cost defined in `rider`, plus the addition of all relevant segments in `kilometer`, `minute`, `active_minute`, and `idle_minute`.
\- `idle_minute` | OPTIONAL | Array | Array of Fare objects defining the price of the service per minute, while the vehicle is stopped or not moving. Total cost per rider is the base cost defined in `rider`, plus the addition of all relevant segments in `kilometer`, `minute`, `active_minute`, and `idle_minute`.
\- `rider` | OPTIONAL | Array | Array of Fare objects defining the base cost per rider.
\- `luggage` | OPTIONAL | Array | Array of Fare objects defining the cost of luggage as a surcharge per piece of luggage.
The following is the structure of the "Fares" object.
Field Name | Presence | Type | Description
---|---|---|---
`interval` | OPTIONAL | Float | Interval, in units of the parent key, at which the `amount` of the row is applied, from start to end.
`start` | OPTIONAL | Non-negative Integer | The value, in units of the parent key, at which the `amount` defined in the object starts being charged.
`end` | OPTIONAL | Non-negative Integer | The value, in units of the parent key, at which the `amount` defined in the object stops being charged.
`amount` | OPTIONAL | Non-negative currency amount | The fare cost per each unit of the parent key.
##### Example 1: Distance-based fare
The first 10 kilometers cost 3.30 CAD per kilometer, and are charged every 250 meters. All other kilometers cost 4.30 CAD, and are charged every 500 meters.
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"fares": [
{
"fare_id": "RegularPrice",
"currency": "CAD",
"kilometer": [
{
"interval": 0.25,
"end": 10,
"amount": 3.30
},
{
"interval": 0.5,
"start": 10,
"amount": 4.30
}
]
}
]
}
}
```
##### Example 2: Time-based fare
The first 20 minutes cost $1.00 CAD per minute, and are charged every minute. After 20 minutes, the user pays $1.50 per minute, charged every 30 seconds.
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"fares": [
{
"fare_id": "RegularPrice",
"currency": "CAD",
"minute": [
{
"interval": 1,
"end": 20,
"amount": 1.0
},
{
"interval": 0.5,
"start": 20,
"amount": 1.5
}
]
}
]
}
}
```
##### Example 3: Mixed pricing
The user does not pay more than the base price of $2.50 CAD for the first 10km. After 10km, the user pays $1.00 CAD per km. After 25km, the user pays an additional extension price of $3.00 CAD per 5km on top of the $1.00/km. Users are allowed 2 pieces of free luggage, and are charged $5 per additional piece of luggage.
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"fares": [
{
"fare_id": "RegularPrice",
"currency": "CAD",
"kilometer": [
{
"interval": 1.0,
"start": 10,
"amount": 1.0
},
{
"interval": 5,
"start": 25,
"amount": 3.0
}
],
"rider": [
{
"amount": 2.5
}
],
"luggage": [
{
"start": 3,
"amount": 5
}
]
}
]
}
}
```
### wait_time
This dynamic query returns the wait time for a specific location. A `wait_time` request must be made for each user interaction.
The request must have the following query parameters.
Field Name | Presence | Type | Description
---|---|---|---
`pickup_lat` | REQUIRED | Latitude | Latitude of the location where the user will be picked up.
`pickup_lon` | REQUIRED | Longitude | Longitude of the location where the user will be picked up.
`drop_off_lat` | Conditionally REQUIRED | Latitude | Latitude of the location where the user will be dropped off. Required if `drop_off_lon` is provided. FORBIDDEN otherwise.
`drop_off_lon` | Conditionally REQUIRED | Longitude | Longitude of the location where the user will be dropped off. Required if `drop_off_lat` is provided. FORBIDDEN otherwise.
`brand_id` | Conditionally REQUIRED | ID | Array | Array of service brand Ids defined in `service_brands.json`. REQUIRED if more than one service brand is available.
The following fields are all attributes within the main "data" object for this query response.
Field Name | Presence | Type | Description
---|---|---|---
`wait_times` | REQUIRED | Array | An array that contains one object per `brand_id`. Should be empty if no wait time is available for the requested location.
\- `brand_id` | REQUIRED | ID | ID from a service brand defined in `service_brands.json`
\- `wait_time` | REQUIRED | Non-negative Integer | Wait time in seconds the rider will need to wait in the location before pickup.
##### Examples:
###### Query:
`https://www.example.com/gofs/1/en/wait_time?pickup_lat=45.60&pickup_lon=-73.30&brand_id=regular_ride,large_ride`
###### Response:
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"wait_times": [
{
"brand_id": "regular_ride",
"wait_time": 300
},
{
"brand_id": "large_ride",
"wait_time": 600
}
]
}
}
```
### booking_rules.json
This file defines rules about how to book a ride. If available, users can either book a ride in real-time, for the same day with an advance notice or for a future day.
The following fields are all attributes within the main "data" object for this feed.
| Field Name | Presence | Type |Description |
---------- | ---- | -------- | ----------- |
`booking_rules` | REQUIRED | Array | Array that contains one object per booking rules as defined below. |
\- `from_zone_ids` | REQUIRED | Array | One or many ID from a zone defined in `zones.json` that cover the area of the wait time update.
\- `to_zone_ids` | OPTIONAL | Array | One or many ID from a zone defined in `zones.json` that cover the area of the destination.
\- `booking_type` | REQUIRED | Enum | Indicates how far in advance booking can be made.
Valid options are:
`0` - Real-time booking. To be used with `wait_time`.
`1` - Up to same-day booking with advance notice.
`2` - Up to prior day(s) booking. ||
\- `prior_notice_duration_min` | Conditionally REQUIRED | Integer | Minimum number of minutes before travel to make the request. REQUIRED for `booking_type=1`. FORBIDDEN otherwise. |
\- `prior_notice_duration_max` | OPTIONAL | Integer | Maximum number of minutes before travel to make the booking request. OPTIONAL for `booking_type=1`. FORBIDDEN otherwise.|
\- `prior_notice_last_day` | Conditionally REQUIRED | Integer | Last day before travel to make the booking request (e.g. “Ride must be booked 1 day in advance before 5PM” will be encoded as `prior_notice_last_day=1`). REQUIRED for `booking_type=2`. FORBIDDEN otherwise.|
\- `prior_notice_last_time` | Conditionally REQUIRED | Time | Last time on the last day before travel to make the booking request (e.g. “Ride must be booked 1 day in advance before 5PM” will be encoded as `prior_notice_last_time=17:00:00`). REQUIRED if `prior_notice_last_day` is defined. FORBIDDEN otherwise. |
\- `prior_notice_start_day` | OPTIONAL | Integer | Earliest day before travel to make the booking request (e.g.: “Ride can be booked at the earliest one week in advance at midnight” will be encoded as `prior_notice_start_day=7`). FORBIDDEN for `booking_type=0`. FORBIDDEN for `booking_type=1` if `prior_notice_duration_max` is defined. OPTIONAL otherwise. |
\- `prior_notice_start_time` | Conditionally REQUIRED | Time | Earliest time on the earliest day before travel to make the booking request (e.g. : “Ride can be booked at the earliest one week in advance at midnight” will be encoded as `prior_notice_start_time=00:00:00`). FORBIDDEN for `booking_type=0`. REQUIRED if `prior_notice_start_day` is defined. FORBIDDEN otherwise. |
\- `prior_notice_calendar_id` | OPTIONAL | ID referencing a `calendar_id` from `calendars.json` | Indicates the service days on which `prior_notice_last_day` or `prior_notice_start_day` are counted (e.g. : If empty, `prior_notice_start_day=2` will be two calendar days in advance. If defined as a `calendar_id` containing only business days (weekdays without holidays), `prior_notice_start_day=2` will be two business days in advance). OPTIONAL if `booking_type=2`. FORBIDDEN otherwise. |
\- `message` | OPTIONAL | String | Message to riders utilizing service inside a zone when booking on-demand pickup and drop off. Meant to provide minimal information to be transmitted within a user interface about the action a rider must take in order to utilize the service. |
\- `pickup_message` | OPTIONAL| String | Functions in the same way as `message` but used when riders have on-demand pickup only. |
\- `drop_off_message` | OPTIONAL| String | Functions in the same way as `message` but used when riders have on-demand drop off only. |
\- `phone_number` | OPTIONAL| Phone number | Phone number to call to make the booking request. |
\- `info_url` | OPTIONAL| URL | URL providing information about the booking rule. |
\- `booking_url` | OPTIONAL| URL | URL to an online interface or app where the booking request can be made. |
##### Example:
```jsonc
{
"last_updated": 1609866247,
"ttl": 86400,
"version": "1.0",
"data": {
"booking_rules": [
{
"from_zone_ids": ["zoneA"],
"to_zone_ids": null,
"booking_type": 1,
"prior_notice_duration_min": 30,
"prior_notice_duration_max": 180
},
{
"from_zone_ids": ["zoneA"],
"to_zone_ids": ["zoneB"],
"booking_type": 2,
"prior_notice_start_day": 2,
"prior_notice_last_time": "17:00:00"
}
]
}
}
}
```
### realtime_booking
This dynamic query provides time/cost estimates and realtime_booking information for specific location. It can be used in situations where a provider expects to have more fine-grained or accurate booking information for a given trip, compared to what is available via other endpoints.
For example, a provider may be able to give more accurate pricing information for a specific trip, compared to the broader rules-based pricing information available from `fares.json`.
The request must have the the same query parameters as `wait_time`. Additionally, these two optional parameters can be provided to make sure the pick up and drop off adresses do not get lost during reverse geocoding.
Field Name | Presence | Type | Description
---|---|---|---
`pickup_address` | OPTIONAL | String | Full address of the location where the user will be picked up.
`drop_off_address` | OPTIONAL | String | Full address of the location where the user will be dropped off.
The following fields are all attributes within the main "data" object for this query response.
Field Name | Presence | Type | Description
---|---|---|---
`realtime_booking` | REQUIRED | Array | An array that contains one object per `brand_id`. Should be empty if no realtime booking is available for the requested location.
\- `brand_id` | REQUIRED | ID | ID from a service brand defined in `service_brands.json`
\- `wait_time` | REQUIRED | Non-negative Integer | Wait time in seconds the rider will need to wait in the location before pickup.
\- `travel_time` | OPTIONAL | Non-negative Integer | The estimated travel time in seconds from the pickup to dropoff location. Cannot be provided if a drop off location is not provided.
\- `travel_cost` | OPTIONAL | Non-negative currency amount | The estimated fare cost of the trip from the pickup to dropoff location. Cannot be provided if a drop off location is not provided.
\- `travel_cost_currency` | Conditionally REQUIRED | Currency code | Currency of the `estimated_travel_cost`. REQUIRED if `estimated_travel_cost` is provided.
\- `booking_detail` | OPTIONAL | Object | Optionally, an object with real time booking details can be provided.
- \- `service_name` | OPTIONAL | String | If the service name needs to change due to real time booking changes, `service_name` can be provided to update the name of the on-demand service system to be displayed to the riders.
- \- `android_uri` | Conditionally REQUIRED | URL | Android App Links that can open the booking app on Android. At least of one `android_uri`, `ios_uri`, `web_uri`, or `phone_number` needs to be provided.
- \- `ios_uri` | Conditionally REQUIRED | URL | iOS Universal Links that can open the booking app on iOS. At least of one `android_uri`, `ios_uri`, `web_uri`, or `phone_number` needs to be provided.
- \- `web_uri` | Conditionally REQUIRED | URL | Web url to browse to in order to make the booking request. At least of one `android_uri`, `ios_uri`, `web_uri`, or `phone_number` needs to be provided.
- \- `phone_number` | Conditionally REQUIRED | Phone Number | Phone number to call to make the booking request. At least of one `android_uri`, `ios_uri`, `web_uri`, or `phone_number` needs to be provided.
##### Examples:
###### Query:
`https://www.example.com/gofs/1/en/realtime_booking?pickup_lat=45.60&pickup_lon=-73.30&brand_id=regular_ride,large_ride`
###### Response:
```jsonc
{
"last_updated": 1609866247,
"ttl": 300,
"version": "1.0",
"data": {
"realtime_booking": [
{
"brand_id": "regular_ride",
"wait_time": 300,
"travel_time": 300,
"travel_cost": 30,
"travel_cost_currency": "CAD",
"booking_detail": {
"service_name": "Taxi",
"android_uri": "https://www.example.com/app?service_type=REG&platform=android",
"ios_uri": "https://www.example.com/app?service_type=REG&platform=ios",
"web_uri": "https://www.example.com/app?service_type=REG",
"phone_number": "+18005551234"
}
},
{
"brand_id": "large_ride",
"wait_time": 450,
"travel_time": 300,
"travel_cost": 45,
"travel_cost_currency": "CAD",
"booking_detail": {
"service_name": "Taxi Van",
"android_uri": "https://www.example.com/app?service_type=XL&platform=android",
"ios_uri": "https://www.example.com/app?service_type=XL&platform=ios",
"web_uri": "https://www.example.com/app?service_type=XL",
"phone_number": "+18005551234"
}
}
]
}
}
```
### deeplink with query params
The uris provided in `realtime_booking` (`android_uri`, `ios_uri`, `web_uri`) and `booking_rules` (`booking_url`) should support a specific set of query params:
Param | Presence | Type | Description
---|---|---|---
`pickup_lat` | REQUIRED | Latitude | Latitude of the location where the user will be picked up.
`pickup_lon` | REQUIRED | Longitude | Longitude of the location where the user will be picked up.
`pickup_address` | OPTIONAL | String | Full address of the location where the user will be picked up.
`drop_off_lat` | REQUIRED | Latitude | Latitude of the location where the user will be dropped off.
`drop_off_lon` | REQUIRED | Longitude | Longitude of the location where the user will be dropped off.
`drop_off_address` | OPTIONAL | String | Full address of the location where the user will be dropped off.
`pickup_time` | OPTIONAL | Timestamp | Indicates, in seconds since the Unix epoch, when the user will be picked up.
`drop_off_time` | OPTIONAL | Timestamp | Indicates, in seconds since the Unix epoch, when the user will be dropped off.
#### Example
```
https://www.example.com?pickup_lat=45.52585187926036&pickup_lon=-73.59502716927499&drop_off_lat=45.53614412053443&drop_off_lon=-73.5130921428607&pick_up_time=1726173300000&drop_off_time=1726173600000
```