Roadents API v0.0.1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Roadents API describes a group of HTTP endpoints to run a variety of public transit routing algorithms. These include things like finding possible round trips in time constraints, finding reachable areas, optimizing routes, etc. Methods are called using the HTTP GET method. Arguements are passed directly in the URL as URL Query Parameters. Most methods rely on some sort of branching algorithm; as such, most of them take some sort of initial location and initial time. Locations are always passed using 2 separate parameters, latitude and longitude. These are passed as signed floating point numbers; latitude ranges from -90.0 to 90.0 and longitude ranges from -180.0 to 180.0. Values like 90.0 E do not work. All values representing lengths of time are passed in seconds. If passed as a float they will be truncated to the nearest integer second value. All values representing specific points in time are passed as seconds since January 1st, 1970 GMT.

Base URLs:

• [URL PATH HERE]

API Methods

Donut

Code samples

# You can also use wget
curl -X GET [URL PATH HERE]/donut?latitude=-90&longitude=-180&query=string&total_time=60 \
  -H 'Accept: application/json'

GET [URL PATH HERE]/donut?latitude=-90&longitude=-180&query=string&total_time=60 HTTP/1.1
Host: null

Accept: application/json

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: '[URL PATH HERE]/donut',
  method: 'get',
  data: '?latitude=-90&longitude=-180&query=string&total_time=60',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('[URL PATH HERE]/donut?latitude=-90&longitude=-180&query=string&total_time=60',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get '[URL PATH HERE]/donut',
  params: {
  'latitude' => 'number(double)',
'longitude' => 'number(double)',
'query' => 'string',
'total_time' => 'integer(int64)'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('[URL PATH HERE]/donut', params={
  'latitude': '-90',  'longitude': '-180',  'query': 'string',  'total_time': '60'
}, headers = headers)

print r.json()

URL obj = new URL("[URL PATH HERE]/donut?latitude=-90&longitude=-180&query=string&total_time=60");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "[URL PATH HERE]/donut", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /donut

Finds all desired locations reachable in a given time.

The Donut algorithm finds routes reachable in a given time. The user passes their starting location, how long they would like to travel, and what they are looking for and the Donut algorithms gives them all the places they can reach and the steps to get to them. The algorithm also allows for a variety of filters to allow the caller to only get the routes they want and nothing they do not.

Parameters

Example responses

200 undefined

[
  {
    "start_point": {
      "latitude": -90,
      "longitude": -180,
      "location_type": "input"
    },
    "end_point": {
      "latitude": -90,
      "longitude": -180,
      "location_type": "input"
    },
    "start_time": 0,
    "total_time": 0,
    "steps": [
      {
        "total_time": 0,
        "step_type": "transit",
        "start_point": {
          "latitude": -90,
          "longitude": -180,
          "location_type": "input"
        },
        "end_point": {
          "latitude": -90,
          "longitude": -180,
          "location_type": "input"
        }
      }
    ]
  }
]

Responses

Response Schema

Status Code 200

The routes meeting the query.

|anonymous|[Route]|true|The routes meeting the query.|

Status Code 5XX

An HTTP error.

|» message|string|true|The text of the error.|

Weasel

Code samples

# You can also use wget
curl -X GET [URL PATH HERE]/weasel?latitude=-90&longitude=-180&query=string&total_time=60&arrival_time=-1 \
  -H 'Accept: application/json'

GET [URL PATH HERE]/weasel?latitude=-90&longitude=-180&query=string&total_time=60&arrival_time=-1 HTTP/1.1
Host: null

Accept: application/json

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: '[URL PATH HERE]/weasel',
  method: 'get',
  data: '?latitude=-90&longitude=-180&query=string&total_time=60&arrival_time=-1',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('[URL PATH HERE]/weasel?latitude=-90&longitude=-180&query=string&total_time=60&arrival_time=-1',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get '[URL PATH HERE]/weasel',
  params: {
  'latitude' => 'number(double)',
'longitude' => 'number(double)',
'query' => 'string',
'total_time' => 'integer(int64)',
'arrival_time' => 'integer(int64)'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('[URL PATH HERE]/weasel', params={
  'latitude': '-90',  'longitude': '-180',  'query': 'string',  'total_time': '60',  'arrival_time': '-1'
}, headers = headers)

print r.json()

URL obj = new URL("[URL PATH HERE]/weasel?latitude=-90&longitude=-180&query=string&total_time=60&arrival_time=-1");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "[URL PATH HERE]/weasel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /weasel

Finds all desired locations that can reach a given location in a given time.

The Weasel algorithm finds routes that allow the user to reach a given location by a certain time. The user passes in the location they want to eventually reach, when they want to reach the location by, how long they want to take to get there, and the kind of places they want to start at. The algorithm will then return routes starting at a location meeting their request and ending at their given location before the end time and taking less time than the maximum specified. Currently the algorithm will attempt to end the route as close to the end time as possible, however due the nature of public transit systems it is unlikely that many if any routes end at the provided end time. The algorithm provides all the same filters that Donut does, though some may behave slightly differently due to Weasel's "reversed" nature.

Parameters

Example responses

200 undefined

[
  {
    "start_point": {
      "latitude": -90,
      "longitude": -180,
      "location_type": "input"
    },
    "end_point": {
      "latitude": -90,
      "longitude": -180,
      "location_type": "input"
    },
    "start_time": 0,
    "total_time": 0,
    "steps": [
      {
        "total_time": 0,
        "step_type": "transit",
        "start_point": {
          "latitude": -90,
          "longitude": -180,
          "location_type": "input"
        },
        "end_point": {
          "latitude": -90,
          "longitude": -180,
          "location_type": "input"
        }
      }
    ]
  }
]

Responses

Response Schema

Status Code 200

The routes meeting the query.

|anonymous|[Route]|true|The routes meeting the query.|

Status Code 5XX

An HTTP error.

|» message|string|true|The text of the error.|

Schemas

Route

A series of steps a user can take to reach a destination.

{
  "start_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "end_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "start_time": 0,
  "total_time": 0,
  "steps": [
    {
      "total_time": 0,
      "step_type": "transit",
      "start_point": {
        "latitude": -90,
        "longitude": -180,
        "location_type": "input"
      },
      "end_point": {
        "latitude": -90,
        "longitude": -180,
        "location_type": "input"
      }
    }
  ]
}

Properties

A series of steps a user can take to reach a destination.

RouteStep

A singe step in a route.

{
  "total_time": 0,
  "step_type": "transit",
  "start_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "end_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  }
}

Properties

A singe step in a route.

Enumerated Values

WalkStep

A step where the user walks from one location to another.

{
  "total_time": 0,
  "step_type": "walk",
  "start_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "end_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "walk_distance": 0
}

Properties

allOf - discriminator: RouteStep.step_type

and

Enumerated Values

TransitStep

A step in which the user takes a form of public transit, like a bus or train. Because of this start_point and end_point are guranteed to be of type Station.

{
  "total_time": 0,
  "step_type": "transit",
  "start_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "end_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "wait_time": 0,
  "travel_time": 0,
  "agency": "string",
  "route": "string",
  "stops": 0,
  "transit_type": "bus"
}

Properties

allOf - discriminator: RouteStep.step_type

and

Enumerated Values

PitstopStep

This step represents the user not moving from a location for an amount of time. This step is used in routes generated by algorithms like LunchBreak, where the route contains a non-Station location in the middle of the steps. start_point and end_point represent the location the user will be stopping at, and total_time is how long the user remains at that location. For example, if the user wants to go to a restaurant, eat, and then go to class, the route will contain a PitstopStep where start_point and end_point are both the restaurant and total_time is the time spent eating.

{
  "total_time": 0,
  "step_type": "stop",
  "start_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  },
  "end_point": {
    "latitude": -90,
    "longitude": -180,
    "location_type": "input"
  }
}

Properties

allOf - discriminator: RouteStep.step_type

and

Enumerated Values

Location

A location of any possible type. While all locations contain these fields, some may contain more; this is dependent on the type of location this is, stored in the location_type field.

{
  "latitude": -90,
  "longitude": -180,
  "location_type": "input"
}

Properties

*A location of any possible type. While all locations contain these fields, some may contain more; this is dependent on the type of location this is, stored in the location_type field. *

Enumerated Values

InputLocation

The location the caller passed in to the method. This has no extra information, and has a location_type value of input.

{
  "latitude": -90,
  "longitude": -180,
  "location_type": "input"
}

Properties

allOf - discriminator: Location.location_type

and

Enumerated Values

Station

A public transit station. In addition to standard fields, it also has a name field. It has a location_type value of station.

{
  "latitude": -90,
  "longitude": -180,
  "location_type": "station",
  "name": "string"
}

Properties

allOf - discriminator: Location.location_type

and

Enumerated Values

ReturnedLocation

A location found by the method to meet the given requirements. It has a name and a series of tags in addition to the standard location field.

{
  "latitude": -90,
  "longitude": -180,
  "location_type": "returned",
  "name": "string",
  "tags": [
    "string"
  ]
}

Properties

allOf - discriminator: Location.location_type

and

Enumerated Values