API 2.0 documentation for Modo

Index

Overview
Authentication
Response Formats
Functions

Car List
Location List
Nearby
Configuration

Errors, Warnings, Notices

Overview

Modo's API is made available for software developers to use and display public car, location, and configuration information. This API currently does not provide availability or cost information, allow member login, booking creation or modification, or any other action that requires authentication. Members must be forwarded to bookit.modo.coop to manually complete these actions.

All functions accept parameters with GET or POST, or a combination of the two.

Authentication

User Authentication

Modo user authentication is not supported by this API. This means:

Users cannot create or modify bookings, personal information, settings, etc. via this API. They must be forwarded to bookit.modo.coop to manually complete these actions.

Note: The Modo app currently does not support Universal/App/Deeplinks and will not open through other apps. Forwarding to bookit.modo.coop is the only valid option.

All routes return public data only.

API Authentication

Authentication with this API in the form of tokens, keys, etc. is not implemented, and thus, not required. All routes are publicly available.

Response Formats

All responses follow a standard format as outlined below. If any base objects do not contain data, they will not appear in the result. For example: a successful request without errors would result in "Status" : "Success", and no "Errors" object present. Only certain routes will result in a "Checksum" or "Request" being returned - see specific route definitions for more information.

Generic Response Template

{
  "Status" : "Success", // also returns "Failure"
  "Errors" : [
    ... // contains errors in the event of a request failure
  ],
  "Warnings" : [
    ... // contains warnings, typically when parameters are reverted to route defaults
  ],
  "Notices" : [
    ... // contains notices that provide general information
  ],
  "Checksum" : "...", // generated from response data
                      // useful for checking if stored data is outdated
  "Request" : {
    ... // includes parameters used to generate the response data
        // especially useful when request parameters revert to route defaults
  },
  "Response" : {
    ... // contains response data in the event of a request success
  }
}

Example Failure Response

Route: https://bookit.modo.coop/api/v2/car_list?car_id=abc

{
  "Status" : "Failure",
  "Errors" : [
    "Car ID is an optional parameter; however, if it is supplied, it must be a numeric value."
  ]
}

Example Success Response

Route: https://bookit.modo.coop/api/v2/configuration

{
  "Status" : "Success",
  "Response" : {
    "Configuration" : {
      "BusinessName" : "CarShare Company",
      "ShortName" : "CSC",
      "Address" : "123 Fake Street" 
    }
  }
}

Functions

Car List

Function Info

Route:	https://bookit.modo.coop/api/v2/car_list
Response Format:	JSON
Parameters Accepted By:	GET or POST

Parameters

Parameter	Status	Usage	Example
car_id	Optional	Supply a numeric car ID to only return one car's information.	car_id=289
checksum	Optional	Supply a checksum to compare against the data set being returned. If it matches the checksum generated from the returned data set, only the checksum is returned. If it does not match, a new checksum is returned with the full data set.	checksum=abc123
output	Optional	If no format name is supplied, JSON is returned. Currently, the only other option is 'human', which returns an HTML-formatted page for human analysis.	output=human

Usage Notes

The Car List route returns a list of all active cars and their attributes by default, or a single car and its attributes if a car_id is supplied.

A checksum is always returned. If the optional checksum parameter is supplied, it will be evaluated against the checksum generated from the response data. If the checksums match, only the checksum itself is returned. This is useful when checking to see if locally stored data is still up to date.
Individual cars are returned as attributes of the base object, "Cars". Cars are indexed by their ID within the "Cars" object.
Included in a single car's attributes are two lists: "Accessories" and "Location".

"Accessories" contains a list of strings describing various accessories or features of the car.
"Location" contains a lists of objects that describe the location of the car from the request timestamp until one year in the future.
"LocationID" can be matched to responses from the location_list route for more detailed location information.
The "StartTime" and "EndTime" timestamps will contain null if they match the start and end timestamps in the request.
If they don't match, the "StartTime" and "EndTime" timestamps will contain an Epoch timestamp that indicates when the car arrives at or leaves the location.

Example Request

https://bookit.modo.coop/api/v2/car_list?car_id=289&checksum=ab613d91137e1f831796aae6e0d663fe

Example Response

{
  "Status" : "Success",
  "Checksum" : "ab613d91137e1f831756aae6e0c663ee",
  "Response" : {
    "CarCount" : "2",
    "Cars" : {
      "289" : {
        "ID" : "289",
        "Make" : "Tesla",
        "Model" : "Model S",
        "Year" : "2015",
        "Colour" : "Grey",
        "Identifier" : null,
        "Category" : "4-door Sedan",
        "Class" : "Car",
        "ExceptionClass" : "Premium",
        "Seats" : "5",
        "Accessories" : [
          "audio: CD player"
        ],
        "Location" : [
          {
            "LocationID" : "334",
            "StartTime" : null,
            "EndTime" : null
          }
        ]
      },
      "764" : {
        "ID" : "764",
        "Make" : "Honda",
        "Model" : "Fit",
        "Year" : "2016",
        "Colour" : "Red",
        "Identifier" : "Caroline",
        "Category" : "4-door Hatchback",
        "Class" : "Car",
        "ExceptionClass" : null,
        "Seats" : "5",
        "Accessories" : [
          "audio: aux audio input",
          "audio: MP3 CD player",
          "cruise control"
        ],
        "Location" : [
          {
            "LocationID" : "182",
            "StartTime" : null,
            "EndTime" : "1482285600"
          },
          {
            "LocationID" : "49",
            "StartTime" : "1482292800",
            "EndTime" : null
          }
        ]
      }
    }
  }
}

Location List

Function Info

Route:	https://bookit.modo.coop/api/v2/location_list
Response Format:	JSON
Parameters Accepted By:	GET or POST

Parameters

Parameter	Status	Usage	Example
location_id	Optional	Supply a numeric location ID to only return one car's information.	location_id=4
checksum	Optional	Supply a checksum to compare against the data set being returned. If it matches the checksum generated from the returned data set, only the checksum is returned. If it does not match, a new checksum is returned with the full data set.	checksum=abc123
output	Optional	If no format name is supplied, JSON is returned. Currently, the only other option is 'human', which returns an HTML-formatted page for human analysis.	output=human

Usage Notes

The Location List route returns a list of all active locations, basic location information, and their GPS coordinates. A single location is returned if a location_id is supplied.

A checksum is always returned. If the optional checksum parameter is supplied, it will be evaluated against the checksum generated from the response data. If the checksums match, only the checksum itself is returned. This is useful when checking to see if locally stored data is still up to date.
Individual locations are returned as attributes of the base object, "Locations". Locations are indexed by their ID within the "Locations" object.
Location objects contain information about the "Neighbourhood", "City", and "Region" they reside in for ease of sorting.
Each location "ID" can be matched to the "LocationID" in responses from the car_list route for more detailed fleet information.

Example Request

https://bookit.modo.coop/api/v2/location_list?location_id=4&checksum=08abb19c9ead5990c8445192383bf643

Example Response

{
  "Status" : "Success",
  "Checksum" : "829b48a5b3c3db97d2e0c34d1f44122d",
  "Response" : {
    "Locations" : {
      "4" : {
        "ID" : "4",
        "Name" : "Main Street Skytrain",
        "ShortDescription" : "Vancouver - Terminal Avenue & Quebec Street",
        "Region" : "Lower Mainland",
        "City" : "Vancouver",
        "Neighbourhood" : "False Creek",
        "Latitude" : "49.272521",
        "Longitude" : "-123.100764",
        "ExceptionClass" : null
      }
    }
  }
}

Nearby

Function Info

Route:	https://bookit.modo.coop/api/v2/nearby
Response Format:	JSON
Parameters Accepted By:	GET or POST

Parameters

Parameter	Status	Usage	Example
lat	Required	The numerical latitude value of the coordinate to search from.	lat=49.284710
long	Required	The numerical longitude value of the coordinate to search from.	long=-123.114464
distance	Optional	Numerical distance in meters. If no distance is supplied, a default of 1000m is used.	distance=500
output	Optional	If no format name is supplied, JSON is returned. Currently, the only other option is 'human', which returns an HTML-formatted page for human analysis.	output=human

Usage Notes

The Nearby route returns a list of objects that contain a "LocationID" and the distance from that location to the supplied GPS coordinate.

Supplied distances are required to be in meters. Returned distances are also in meters.
Matching the "LocationID" to the location "ID" returned by the car_list route will provide the GPS location of individual cars.

Example Request

https://bookit.modo.coop/api/v2/nearby?lat=49.284710&long=-123.114464

Example Response

{
  "Status" : "Success",
  "Request" : {
    "lat" : "49.284710",
    "long" : "-123.114464",
    "distance" : "200",
  },
  "Response" : {
    "Locations" : [
      {
        "LocationID" : "208",
        "Distance" : "83.2060718910015",
        "Latitude" : "49.284142",
        "Longitude" : "-123.113716"
      },
      {
        "LocationID" : "47",
        "Distance" : "180.413097682836",
        "Latitude" : "49.285728",
        "Longitude" : "-123.112525"
      }
    ]
  }
}

Configuration

Function Info

Route:	https://bookit.modo.coop/api/v2/configuration
Response Format:	JSON
Parameters Accepted By:	GET or POST

Parameters

Parameter	Status	Usage	Example
output	Optional	If no format name is supplied, JSON is returned. Currently, the only other option is 'human', which returns an HTML-formatted page for human analysis.	output=human

Usage Notes

The Configuration route returns essential information about Modo's business and operating environment.

Configuration is returned within a "Configration" object.
Basic information about the business is provided, including name, address, contact information, web address, etc.
Further information is provided about the fleet's operation, including the number of cars, the booking increment, minimum and maximum booking times, and time zone.
Additionally, colours are returned for accurate branding and styling.

Example Request

https://bookit.modo.coop/api/v2/configuration

Example Response

{
  "Status" : "Success",
  "Response" : {
    "Configuration" : {
      "BusinessName" : "CarShare Company",
      "ShortName" : "CSC",
      "Address" : "123 Fake Street",
      "PhoneNumber" : "111-111-1111",
      "Email" : "info@csc.fake",
      "Website" : "www.csc.fake",
      "CarCount" : "257",
      "BookingIncrement" : "900",
      "MinimumDuration" : "1800",
      "MaximumDuration" : "864000",
      "TimeZone" : "America/Vancouver",
      "Colour1" : "0099cc",
      "Colour2" : "ef3f3f",
      "Colour3" : "8BC53F",
      "Colour4" : "f16639",
    }
  }
}

Errors, Warnings, Notices

Coming soon.

Last updated 2019-10-16