Skip to content

reference.md

Latest commit

 

History

History
890 lines (756 loc) · 43.5 KB

reference.md

File metadata and controls

890 lines (756 loc) · 43.5 KB

General On-Demand Feed Specification Reference

This document defines the format and structure of the files that comprise a GOFS dataset.

Table of Contents

  1. Document Conventions
  2. Dataset Files
  3. File Requirements
  4. Field Definitions

Document Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Term Definitions

  • JSON - JavaScript Object Notation is a lightweight format for storing and transporting data. This document uses many terms defined by the JSON standard, including field, array, and object.
  • GeoJSON - GeoJSON is a format for encoding a variety of geographic data structures.

Presence

Presence conditions applicable to fields and files:

  • REQUIRED - The file or the field MUST be included in the dataset, and a value MUST be provided in the field for each record.
  • OPTIONAL - The file or the field MAY be omitted from the dataset, and a value MAY be omitted in the field for any record.
  • Conditionally REQUIRED - The file or the field is REQUIRED under certain conditions, which are outlined in the file or field description. Outside of these conditions, the file or the field is OPTIONAL.

Field Types

  • Array - A JSON element consisting of an ordered sequence of zero or more values.
  • Color - A color encoded as a six-digit hexadecimal number. Refer to https://htmlcolorcodes.com to generate a valid value (the leading "#" must not be included).
    Example: FFFFFF for white or 000000 for black.
  • Date - Service day in the YYYYMMDD format. Since time within a service day may be above 24:00:00, a service day may contain information for the subsequent day(s).
    Example: 20211109 for November 9th, 2021.
  • Email - An email address.
    Example: example@example.com
  • Enum - An option from a set of predefined constants listed in the "Description" column.
    Example: If provided, the wheelchair_boarding field MUST indicate either boarding_accessible, boarding_inacessible, or any other options available in the list.
  • GeoJSON FeatureCollection - A FeatureCollection as described by the IETF RFC 7946-3.3.
  • GeoJSON Polygon - A Geometry Object as described by the IETF RFC 7946-3.1.6.
  • ID - Should be represented as a string that identifies that particular entity. An ID:
    • MUST be unique within like fields (e.g. id MUST be unique among zones)
    • does not have to be globally unique, unless otherwise specified
    • MUST NOT contain spaces
    • MUST be persistent for a given entity (zone, plan, etc).
  • Language - An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/.
    Example: en for English, en-US for American English or de for German.
  • Non-negative Integer - An integer greater than or equal to 0.
  • Float - A floating point number.
  • Object - A JSON element consisting of key-value pairs (fields).
  • Phone number - A phone number. The phone number MUST include the country calling code. The phone number MUST NOT include any punctuation marks or dialable text.
    Example: the North American phone number "(987) 654-3210" MUST be provided as +19876543210; the French phone number "01.23.45.67.89" MUST be provided as +33123456789.
  • String - A text string of UTF-8 characters, which is aimed to be displayed and which must therefore be human readable.
  • Time - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
    Example: 14:30:00 for 2:30PM or 25:35:00 for 1:35AM on the next day.
  • Timezone - TZ timezone from the https://www.iana.org/time-zones. Timezone names never contain the space character but may contain an underscore. Refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values.
    Example: Asia/Tokyo, America/Los_Angeles or Africa/Cairo.
  • URL - A fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See the following http://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values.
  • Currency code - String containing 3 letters currency code as defined by ISO 4217. Ex: "CAD", "USD".
  • Latitude - WGS84 latitude in decimal degrees. The value MUST be greater than or equal to -90.0 and less than or equal to 90.0. Example: 41.890169 for the Colosseum in Rome.
  • Longitude - WGS84 longitude in decimal degrees. The value MUST be greater than or equal to -180.0 and less than or equal to 180.0. Example: 12.492269 for the Colosseum in Rome.
  • Timestamp - An integer representing the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970 (Unix epoch).

Dataset Files

By default, on-demand services are not available anywhere. To represent on-demand services in operation, at least one zone and one operating rule MUST be defined respectively in zones.json and operating_rules.json.

File Name Presence Description
gofs.json REQUIRED Auto-discovery file that links to all of the other files published by the data producer of the on-demand service system.
gofs_versions.json OPTIONAL Shows the different versions available for the same GOFS feed.
system_information.json REQUIRED Defines the attributes of the on-demand service system (e.g. operator, location, year implemented, URL, contact info, timezone, etc.).
service_brands.json REQUIRED Details the different on-demand service brands available to the riders.
vehicle_types.json Conditionally REQUIRED Describes the vehicle types used for operating the on-demand services. This file is REQUIRED if any vehicle types are referenced in operating_rules.json.
zones.json REQUIRED Geographically defines zones where on-demand services are available to the riders.
operating_rules.json REQUIRED Defines rules for intra-zone and inter-zone trips as well as operating times.
calendars.json REQUIRED Defines dates and days when on-demand services are available to the riders.
fares.json OPTIONAL Defines static fare rules for a system.
wait_time Conditionally REQUIRED Returns a wait time for queried areas. Either wait_time or realtime_booking MUST be provided if there are no booking_rules or at least one booking_rule is booking_type=real-time.
booking_rules.json OPTIONAL Returns rules for booking in queried areas.
realtime_booking OPTIONAL Returns details for available booking when static booking details can't be provided. Either wait_time or realtime_booking MUST be provided if there are no booking_rules or at least one booking_rule is booking_type=real-time.

File Requirements

Auto-Discovery

Publishers SHOULD implement auto-discovery of GOFS feeds by linking to the location of the gofs.json auto-discovery endpoint.

  • The location of the auto-discovery file SHOULD be provided in the HTML area of the on-demand service's landing page hosted at the URL specified in the URL field of the system_information.json file.
  • This is referenced via a link tag with the following format:

Versioning

To enable the evolution of GOFS, including changes that would otherwise break backwards-compatibility with consuming applications, GOFS documentation is versioned. The GOFS versions are named "vX.Y" where X.Y is the version number.

  • The current release is v1.0.

Localization

Each set of data files SHOULD be distributed in a single language as defined in system_information.json. A system that wants to publish feeds in multiple languages SHOULD do so by publishing multiple distributions, such as:

  • https://www.example.com/data/en/system_information.json
  • https://www.example.com/data/fr/system_information.json

Output Format

Every JSON file presented in this specification contains the same common header information at the top level of the JSON response object:

Field Name Presence Type Description
last_updated REQUIRED Timestamp Indicates the last time data in the feed was updated. This timestamp represents the publisher's knowledge of the current state of the system at this point in time.
ttl REQUIRED Non-negative integer Number of seconds before the data in the feed will be updated again. If the data should always be refreshed, the value SHOULD be 0.
version REQUIRED String GOFS version number to which the feed confirms, according to the versioning framework.
data REQUIRED Object Response data in the form of name:value pairs.
Example:
{
  "last_updated": 1609866247,
  "ttl": 3600,
  "version": "1.0",
  "data": {
    "language": "en",
    "timezone": "US/Central",
    "name": "Example MicroTransit"
  }
}

Field Definitions

gofs.json

The gofs.json discovery file SHOULD represent a single system or geographic area in which vehicles are operated. The location (URL) of the gofs.json file SHOULD be made available to the public using the specification's auto-discovery function.

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Description
language REQUIRED Language The language that will be used throughout the rest of the files. It MUST match the value in the system_information.json file.
- feeds REQUIRED Array An array of all of the feeds that are published by this auto-discovery file. Each element in the array is an object with the keys below.
 - name REQUIRED String Key identifying the type of feed this is. The key MUST be the base file name defined in the spec for the corresponding feed type (zones for zones.json file, operating_rules for operating_rules.json file).
 - url REQUIRED URL URL for the feed. Note that the actual feed endpoints (urls) MAY NOT be defined in the file_name.json format. For example, a valid feed endpoint could end with zones instead of zones.json.
Example:
{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "1.0",
  "data": {
    "en": {
      "feeds": [
        {
          "name": "system_information",
          "url": "https://www.example.com/gofs/1/en/system_information"
        },
        {
          "name": "zones",
          "url": "https://www.example.com/gofs/1/en/zones"
        }
      ]
    },
    "fr" : {
      "feeds": [
        {
          "name": "system_information",
          "url": "https://www.example.com/gofs/1/fr/system_information"
        },
        {
          "name": "zones",
          "url": "https://www.example.com/gofs/1/fr/zones"
        }
      ]
    }
  }
}

gofs_versions.json

The gofs_versions.json SHOULD include all the versions available for the same GOFS feed representing the on-demand service system.

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Defines
versions REQUIRED Array Contains one object, as defined below, for each of the available versions of a feed. The array MUST be sorted by increasing version numbers.
- version REQUIRED String Version number of the feed.
- url REQUIRED URL URL of the corresponding gofs.json endpoint.
Example:
{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "1.0",
  "data": {
    "versions": [
      {
        "version": "1.0",
        "url": "https://www.example.com/gofs/2/gofs"
      },
      {
        "version": "X.Y",
        "url": "https://www.example.com/gofs/3/gofs"
      }
    ]
  }
}

system_information.json

This file defines the attributes of the on-demand service system.

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Description
language REQUIRED Language Language used throughout the rest of the files.
timezone REQUIRED Timezone Timezone where the on-demand service system is located.
name REQUIRED String Name of the on-demand service system to be displayed to the riders.
short_name OPTIONAL String Abbreviation commonly used to name the on-demand service system.
operator OPTIONAL String Name of the on-demand service operator. The operator name MAY be the same as the system name.
url OPTIONAL URL URL of the on-demand service system.
subscribe_url OPTIONAL URL URL where riders can subscribe to the on-demand services.
start_date OPTIONAL Date Date that the system began operations.
phone_number OPTIONAL Phone Number Voice telephone number for the specified system's customer service department.
email OPTIONAL Email Contact email address actively monitored by the operator's customer service department. This email address SHOULD be a direct contact point where riders can reach a customer service representative.
feed_contact_email OPTIONAL Email Contact email for feed consumers to report technical issues with the feed.
Example:
{
  "last_updated": 1611598155,
  "ttl": 1800,
  "version": "1.0",
  "data": {
    "language": "en",
    "timezone": "America/Toronto",
    "name": "Example MicroTransit",
    "short_name": "Micro",
    "operator": "MicroTransit, Inc",
    "url": "https://www.example.com",
    "subscribe_url": "https://www.example.com",
    "start_date": "20100610",
    "phone_number": "+18005551234",
    "email": "customerservice@example.com",
    "feed_contact_email": "datafeed@example.com"
  }
}

service_brands.json

This file defines the on-demand service brands available to the riders. One feed MAY contain multiple service brands with different features and amenities (e.g. A ridehail service system MAY offer the 'Regular Ride', 'Large Ride' and 'Shared Ride' services).

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Description
service_brands REQUIRED Array Array that contains one object per service brand as defined below.
- brand_id REQUIRED ID Unique identifier of the service brand. This value SHOULD remain the same over the availability of the service.
- brand_name REQUIRED String Name of the service brand to be displayed to the riders.
- brand_color OPTIONAL Color Color identifying the service brand to be displayed to the riders
- brand_text_color OPTIONAL Color Color used for displaying text over the brand_color. For visual-accessibility reasons, the brand_text_color MUST highly contrast with the brand_color (e.g. a dark brand_color SHOULD be paired with a white brand_text_color; a light brand_color SHOULD be paired with a black brand_text_color).
Example:
{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "1.0",
  "data": {
    "service_brands": [
      {
        "brand_id": "regular_ride",
        "brand_name": "Regular Ride",
        "brand_color": "1C7F49",
        "brand_text_color": "FFFFFF"
      },
      {
        "brand_id": "large_ride",
        "brand_name": "Large Ride",
        "brand_color": "1C7F49",
        "brand_text_color": "FFFFFF"
      },
      {
        "brand_id": "shared_ride",
        "brand_name": "Shared Ride",
        "brand_color": "1C7F49",
        "brand_text_color": "FFFFFF"
      }
    ]
  }
}

vehicle_types.json

This file defines the vehicle types used for operating the on-demand services. This file is REQUIRED if any vehicle types are referenced in operating_rules.json.

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Description
vehicle_types REQUIRED Array Array that contains one object per vehicle type as defined below.
-  vehicle_type_id REQUIRED ID Unique identifier of the vehicle type.
-  max_capacity OPTIONAL Non-Negative Integer Maximum number of riders that the vehicle can legally carry.
-  wheelchair_boarding OPTIONAL Enum Possibility for riders with a wheelchair to board the vehicle. Valid options are:
  • boarding_accessible
  • boarding_inaccessible
  • boarding_accessible_with_assistance
Example:
{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "1.0",
  "data": {
    "vehicle_types": [
      {
        "vehicle_type_id": "large_van",
        "max_capacity": 7,
        "wheelchair_boarding": "boarding_accessible"
      }
    ]
  }
}

zones.json

This file geographically defines the zones where the on-demand services are available to the riders. The zones are delineated with a "FeatureCollection" GeoJSON file, in accordance with RFC 7946. At least one zone MUST be defined.

All zones defined in this file are public information (i.e. all zones can be displayed on a map available to anyone).

Geolocalization operates in two dimensions: if the pickup or drop off is allowed on an overpass or bridge, it will also be allowed to the roadway or path beneath. Location data from GPS, cellular and Wi-Fi signals are subject to interference resulting in accuracy levels in the tens of meters or greater.

The following fields are all attributes within the main "data" object for this feed.

Field Name Presence Type Description
zones REQUIRED GeoJSON FeatureCollection Object as per RFC 7946.
- type REQUIRED String FeatureCollection as per RFC 7946.
- features REQUIRED Array Array of objects where each object represent a zone, as defined below.
- - type REQUIRED String Feature as per RFC 7946.
- - zone_id REQUIRED ID Unique identifier of the zone.
- - geometry REQUIRED GeoJSON Polygon A polygon that describes where riders can be picked up or dropped off.

Following the right-hand rule, 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:
{
  "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:
{
  "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:
{
  "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.

{
  "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.

{
  "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.

{
  "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

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:
{
  "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:
{
  "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:
{
  "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