Skip to content

Web service interface

The web interface is still REST and a modified json-rpc but it has been much simplified. I will try to build the complete API in this part.

new version

Todo

The rest of this chapter is a pruned older version. I will only cut parts if an equivalent has been implemented in the new version.

old version

The format of messages adheres to json-rpc standard 2.0 jsonrpc-ref-label

There is generally a choice to pass or retrieve values in a terse or a verbose manner. Usually this is done by passing values either as nameless arrays (terse), or as name objects(verbose):

changetitle
1
[ [ 7.23,52,33 ], [ 7.3134,55.533 ] ]

vs :

changetitle
1
[ { 'y': 7.23,'x':52.33 }, { 'x': 55.533,'y':7.3134} ]

This shows that positional/terse/array passing must be in a predetermined [lon,lat] or [x,y] order, where named/verbose/objects passing can be switched.

coordinates

Coordinates will mostly be in x,y[,z] order. So that means longitude,latitude,height. The height however is not (yet ?) used and coordinates are expected to be ground level x,y pairs. Klopt uses various (open)sources and though they do agree about the format ws94 (what we generally call latitude/longitude), they do not on the order in which they are used:

  • google maps generally puts the latitude (y or northing) first en the longitude (x or easting) second
  • osrm also use lat.long
  • mongodb geo spatial data tends to use x,y,z (longitude/latitude/height)

Because of it's similarity with mathematics coordinate systems, we chose the last format for all places where the members are not specifically named.

services

The basic service from ws.klopt.org are divided in three main groups:

  • maintenance : ping, status
  • geocoding : nearest, geocode, reverse geocode
  • routing : point to point routing, matrix routing
  • planning : tsp, lp, vrp

Most services can handle different kinds of input. Since it will always be a trade of between clarity and space, both positional and named parameters can be used. In the result this can be steered with the option parameter : "named". The default is unnamed so named:false or an absent named option will return nameless arrays.

maintenance

Some methods of getting this result :

rest client

Get a rest client for your browser, set it to POST and paste the top json into the RAW data field. Push 'send'

python script

This short python script will do the trick :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
#!/usr/bin/python

# this need request for python , you could use pip :
# sudo apt-get install python-pip
# pip install requests

import httplib, urllib
import random
import requests

def restit(postdata):
    params = {'jsonrpc':postdata}
    print postdata

    r = requests.post("http://ws.klopt.org:1901/ws", data=postdata);
    response = r.text
    print response

for x in range(1,10):
    postdata = '{"jsonrpc":"2.0","id":666,"method":"ping"}';
    restit(postdata)

geocoding

These service are all about find location and matching points on the earth with addresses and vice-versa.

  • a point on a digital network, so you can make a route to or from it.
  • an address, so you could send something to it.

Usually, different datasets are better suited for different purposes, and so these datasets tend to be different from eachother. Typically the routing network is from openstreetmap, teleatlas etc. And the address database is from google, or country specific databases like 'kadaster' in Holland. Nearest is the service to use when matching between coordinates.

Nearest

Given a location or x,y pair on the surface of the earth, get the closest point on a digitized network. The main method in the json-rpc calls is 'nearest', and the parameters are described next :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "jsonrpc":"2.0",
    "method":"nearest",
    "id":533,
    "params":{
        "options": {
            "algorithm":"osrm",
            "timings":false,
            "meters":false,
            "matchname":false,
            "membernames":false
        },
        "coordinates":[[53.2207962646,6.2751811345],[53.3942779081,7.39675197775],[53.0580683872,6.22649210735]]
    }
}

The params object contains an optional options section, if omitted all options are set to default. The options and their defaults are : * algorithm: could be 'osrm', 'google' or 'bag'. The default will be osrm because that matches the best coordinate for what is mostly the next step : routing. Actually at this moment the only supported algorithm is osrm. * timings: true or false. This causes the response object to contain the time measurements on the server. The default is False. * meters: return the bird flight distance in meters between the input and the found point. * matchname: return the name of the object matched if any. mostly a streetname, default is false * membernames: return the results as named objects, default is false (positional) [x,y,meters,name].

Optional you can send the coordinates as :

"coordinates":[{'y':52.18708326214931,'x':5.347380638122559}]

Both objects and array members can be intermixed, but the object version will be slower.

The coordinates member is an array to be matched coordinates on the peer network, if the default algorithm 'osrm' is used it will be an exact location on the openstreetmap network. A quick match can be made with these precise coordinates in routing operations. When using 'google' or 'bag' the exact coordinates on those networks will be returned. The 'coordinates' object is an array of objects with two members, which can be either named of positional. If named they should be called 'x' and 'y'. If no names are specified, it is assumed 'x' or longitude position is the first, and 'y', also latitude is second.

In the result, the corresponding array index in the coordinates array will hold the result.

The response objects is structured like this :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "jsonrpc":"2.0",
    "method":"nearest",
    "id":533,
    "result": {
        "coordinates":[
            {"lat":53.3004,"lon":7.08334,"meters":11,"matchname":""},
            {"lat":52.5005,"lon":6.50071,"meters":0,"matchname":"Nieuwe Hammerweg"},
            {"lat":52.9083,"lon":7.12618,"meters":0,"matchname":""} 
        ]
        "timings": {
            "nearest":30444
        }
    }
}

Of course, result is the most interesting member, it returns the matched coordinates , very likely different from the input coordinates but of course they could be identical. Meters is the distance from the original coordinates measured in a 'straight' line, but regarding the earths curvature. The name is filled if the matched point (or point of a road) has a name attached to it. Timings returns a measure in microseconds of the operation time on the server, so without communication overhead.

Technical note: the osrm algorithm uses internal function FindPhantomNodeForCoordinate() from the osrm suite. The maximum distance for this function has been stretched quite a lot to always get a result, but it could theoretically fail.

visit.

geocode (coordinates)

Geocoding is the process of finding coordinates from other geographical data like addresses, zipcodes etc. Reverse geocoding is the opposite and since the terms are getting mixed up a lot, this web service can be called both by 'geocode' and 'coordinates'. So with this function you end up with a location. There are a number of fields that can be used to find a location, any combination of which can be used to attempt geocoding. If you however specify postal code and street, the latter is mostly ignored in favor of the zipcode.

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "jsonrpc":"2.0",
    "method":"coordinates",
    "id":533,"params":
    {
        "options":{
            "algorithm":"bag",
            "timings":false,
            "membernames":false
        },
        "addresses":
        [
            {
                "country":"nl",
                "city":"",
                "street":"",
                "house":"248",
                "zipcode":"3151aw"
            },
            [ "nl","Leiden","kerkstraat","20","" ]
        ]
    }
}

As before, addresses can be positional arrays , or named objects. The order shown here is the fixed order : country,city,street,number,zipcode. Options are :

  • algorithm : which can be bag or google
  • timings: true or false
  • membernames: true or false

The result object will look something like this:

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "jsonrpc":"2.0",
    "method":"coordinates",
    "id":533,
    "result": 
    { 
        "coordinates":
        [
            {
                "lat":51.9769,
                "lon":4.13086
            }
        ],
        "timings" : { 
            "coordinates":2272
        } 
    }
}

reverse geocode (addresses)

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "jsonrpc":"2.0",
    "method":"addresses",
    "id":533,"params": {
        "options": {
            "algorithm":"osrm",
            "timings":true,
            "maxmeters":100
        },
        "coordinates": [
            [4.730987548828125,52.138361130011326]
        ]
    }
}

Options include :

  • algorithm. for instance google, bag or osrm
  • timings: whether to return timings or not

The result for the message above would be :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "jsonrpc":"2.0",
    "method":"addresses",
    "id":533,result : 
    {
        "addresses" : 
        [
            {
                "street":"Pieter Pasmahof",
                "city":"Aarlanderveen",
                "country":"NL",
                "zipcode":"2445BH",
                "number":"2"
            }
        ], 
        "timings" : { 
            "locate":1422856,
            "address":41692,
            "street":75044,
            "total":1539592
        } 
    }
}

The timings are divided in 3 steps, first the x,y location is resolved to a house address. The address is then retrieved for it's number, streetname and and postal code. The last step finds the city and country for the address. Total is simply the sum of these 3.

Live demo for this functionality : visit.

routing

Individual routes

We call these 'individual' rather than single to distinguish them form time tables (next chapter). Single is an 'off' name because the command we use can return multiple 'individual routes at once. The major form of the command is :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "jonrpc":"2.0",
    "method":"route",
    "id":33,"params": 
    {
        "options":
        {
            "algorithm":"osrm",
            "timings":true,
            "paths":true
        },
        "coordinates":
        [
            { 52.5,6.69705188498 }, 
            { 52.5,7.08420342009 } 
        ]
    }
}

options :

  • algorithm is mostly osrm
  • paths specifies if you want detailed information about the path on the map driven (true) or just the distance and time (false)
  • timings, specifies if you want the timings returned in the result

An example of a return message with paths enabled :

changetitle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "jsonrpc":"2.0",
    "method":"route",
    "id":33,
    "result":
    {
        "routes":
        [
            {"mtr":-1,"sec":-1,"path":""},
            {"mtr":-1,"sec":-1,"path":""},
            {"mtr":19648,"sec":1058,"path":"snzccBizm ... }eCf~@}wC"} 
        ]
    }
}

Live demo for this functionality : visit.

time tables

We also often call this matrices. because it is the mathematical form for it.

Live demo for this functionality : visit.