Skip to content

REST APIs

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

Overview

The backend provides three REST APIs for:

  • Planning journeys from A to B
  • Searching nodes by their name
  • Searching nearest nodes given a location

All APIs accept and handle POST and OPTIONS requests.

The corresponding code can be found in packages

src/de/tischner/cobweb/routing/server/
src/de/tischner/cobweb/searching/name/server/
src/de/tischner/cobweb/searching/nearest/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 (must be combined with at least one other mode)
    • 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

Name Search API

The name 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

Nearest Search API

The nearest search API finds nodes nearest to a given location. The answer contains the nearest node.

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 /nearestsearch. An example would be

POST /nearestsearch 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:

  • latitude - Latitude to search the nearest node for
  • longitude - Longitude to search the nearest node for

It might look like:

{
  "latitude": 48.011157,
  "longitude": 7.837142
}

The server parses requests directly into the class

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

Response

A response consists of:

  • time - Duration the computation of the query took, in milliseconds
  • id - Inique ID of the OSM node which is nearest to the requested location or -1 to indicate that there is no nearest node
  • latitude - Latitude coordinate of the matched OSM node, to be ignored if id was -1
  • longitude - Longitude coordinate of the matched OSM node, to be ignored if id was -1

It might look like:

{
   "time": 1,
   "id": 456416,
   "latitude": 48.011157,
   "longitude": 7.837142
}

The server constructs the response directly out of the class

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