Skip to content

REST APIs

Jump to bottom
Daniel Tischner edited this page Jun 9, 2018 · 8 revisions
Table of Contents

Overview

The backend provides two REST APIs for:

  • Planning journeys from A to B
  • Searching nodes by their name

Both APIs accept and handle POST and OPTIONS requests.

The corresponding code can be found in the package

src/de/tischner/cobweb/routing/server/

Routing API

The routing API answers journey planning requests from a given source to a destination. The answer contains multiple viable journeys.

A valid request must be send via POST, encoded in UTF-8 and formatted in JSON. The response is encoded in UTF-8 and formatted in JSON too. The requested HTTP resource must be /route. An example would be

POST /route HTTP/1.0
Content-Length: 63
Content-Type: application/json; charset=utf-8
Connection: keep-alive

with a response of

HTTP/1.0 200 OK
Content-Length: 19308
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Connection: close

Request

A request consists of:

  • depTime - Departure time to start journeys at, in milliseconds since epoch
  • modes - Allowed transportation modes, an array consisting of at least one number of
    • 0 - Car
    • 1 - Tram
    • 2 - Foot
    • 3 - Bike
  • from - Source node, as OSM ID
  • to - Destination node, as OSM ID

It might look like:

{
  "depTime": 1524406380000,
  "modes": [0, 2],
  "from": 452722,
  "to": 456416
}

The server parses requests directly into the class

src/de/tischner/cobweb/routing/server/model/RoutingRequest.java

Response

A response consists of:

  • time - Duration the computation of the query took, in milliseconds
  • compTime - Duration computation of the answer to the query took, in milliseconds
  • from - Source node, as OSM ID (as contained in the request)
  • to - Destination node, as OSM ID (as contained in the request)
  • journeys - Computed viable journeys from the given source to destination, an array consisting of multiple journeys in the format described in the following. If the array is empty the destination is not reachable from the source.
    • depTime - Departure time to start the journey at, in milliseconds since epoch
    • arrTime - Arrival time at the destination node, in milliseconds since epoch
    • route - Route of the journey, as array consisting of nodes and paths in the following format. The first entry is always a node representing the given source, analogously for the last entry and the destination. Node and path elements always alternately. The first coordinate in a path always corresponds to the coordinate of the previous node element, analogously for the last coordinate and the next node element.
      • type - Type of this route element, a number of
        • 0 - The element represents a node which contain a position and meta-data
        • 1 - The element represents a path which contain several positions and meta-data
      • mode - If the type is a path this represents the transportation mode to use, one number out of the following. To be ignored if the type is a node.
        • 0 - Car
        • 1 - Tram
        • 2 - Foot
        • 3 - Bike
      • name - Name of the element, as a string or empty if not present. Might represent the name of a street.
      • geom - List of coordinates belonging to this element, as array containing sub-arrays in the format described in the following. A path may contain multiple coordinates, a node only one.
        • [x, y] - Coordinate as array consisting of two floating number entries, x is the latitude and y the longitude

An example of a response with two journeys might look like:

{
  "time": 2023,
  "compTime": 104,
  "from": 5843453,
  "to": 3445345,
  "journeys": [
    {
      "depTime": 1524258300000,
      "arrTime": 1524261782839,
      "route": [
        {
          "type": 0,
          "name": "Berliner Allee 7-5",
          "geom": [[48.007877, 7.828493]]
        },
        {
          "type": 1,
          "mode": 0,
          "name": "Berliner Allee",
          "geom": [
            [48.007877, 7.828493],
            [48.009139, 7.830648],
            [48.010454, 7.832698],
            [48.011682, 7.834658]
          ]
        },
        {
          "type": 0,
          "name": "Madisonallee 2",
          "geom": [[48.011682, 7.834658]]
        },
        {
          "type": 1,
          "mode": 0,
          "name": "Madisonallee",
          "geom": [
            [48.011682, 7.834658],
            [48.012436, 7.835941]
          ]
        },
        {
          "type": 0,
          "name": "Madisonallee 10",
          "geom": [[48.012436, 7.835941]]
        },
        {
          "type": 1,
          "mode": 3,
          "name": "Emmy-Noether-Straße",
          "geom": [
            [48.012436, 7.835941],
            [48.011273, 7.838019]
          ]
        },
        {
          "type": 0,
          "name": "Emmy-Noether-Straße 10",
          "geom": [[48.011273, 7.838019]]
        },
        {
          "type": 1,
          "mode": 2,
          "name": "Hirtenweg",
          "geom": [
            [48.011273, 7.838019],
            [48.011273, 7.838019],
            [48.0112, 7.837792],
            [48.011157, 7.837446],
            [48.011157, 7.837142]
          ]
        },
        {
          "type": 0,
          "name": "Hirtenweg 9",
          "geom": [[48.011157, 7.837142]]
        }
      ]
    },
    {
      "depTime": 1524258300000,
      "arrTime": 1524261782839,
      "route": [
        {
          "type": 0,
          "name": "Berliner Allee 7-5",
          "geom": [[48.007877, 7.828493]]
        },
        {
          "type": 1,
          "mode": 0,
          "name": "Elefantenweg",
          "geom": [
            [48.007877, 7.828493],
            [48.011157, 7.837142]
          ]
        },
        {
          "type": 0,
          "name": "Hirtenweg 9",
          "geom": [[48.011157, 7.837142]]
        }
      ]
    }
  ]
}

The server constructs the response directly out of the class

src/de/tischner/cobweb/routing/server/model/RoutingResponse.java

Search API

The search API finds nodes by their name. The answer contains viable matches.

A valid request must be send via POST, encoded in UTF-8 and formatted in JSON. The response is encoded in UTF-8 and formatted in JSON too. The requested HTTP resource must be /namesearch. An example would be

POST /namesearch HTTP/1.0
Content-Length: 24
Content-Type: application/json; charset=utf-8
Connection: keep-alive

with a response of

HTTP/1.0 200 OK
Content-Length: 218
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Connection: close

Request

A request consists of:

  • amount - Maximal amount of matches interested in, the response will not contain more matches
  • name - Name to search nodes for, can be a prefix and fuzzy

It might look like:

{
  "amount": 10,
  "name": "Freirb"
}

The server parses requests directly into the class

src/de/tischner/cobweb/searching/server/model/NameSearchRequest.java

Response

A response consists of:

  • time - Duration the computation of the query took, in milliseconds
  • matches - List of viable matches, sorted by relevance (most relevant first). As array, not containing more matches than specified in the request. If the list is empty no matches were found. A match has the following format
    • id - Unique OSM ID of the matched node
    • name - Full name of the matched node

It might look like:

{
   "time": 1,
   "matches": [
      {
         "id": 456416,
         "name": "Freiburg-Süd"
      },
      {
         "id": 2104200,
         "name": "Freiburg im Breisgau"
      },
      {
         "id": 29717746,
         "name": "Freiburg"
      }
   ]
}

The server constructs the response directly out of the class

src/de/tischner/cobweb/searching/server/model/NameSearchResponse.java
Clone this wiki locally