From 57fdf92b1e7d73c9be56dd189a29d1ac401af26c Mon Sep 17 00:00:00 2001 From: Rinigus Date: Wed, 11 Jul 2018 12:46:28 +0300 Subject: [PATCH] update README --- README.md | 111 +++++++++++++++----------------------------- README.older_api.md | 67 ++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 73 deletions(-) create mode 100644 README.older_api.md diff --git a/README.md b/README.md index 7f542026..b71bc15f 100644 --- a/README.md +++ b/README.md @@ -240,7 +240,7 @@ where Results are returned in JSON format. Example query: `http://localhost:8553/v1/search?limit=10&search=tartu mnt 1, tallinn` -``` +```json [ { "admin_region": "Tallinn, Kesklinna linnaosa, Tallinna linn, Harju maakond, Eesti", @@ -273,7 +273,7 @@ one. However, the result includes parsing feedback when geocoder-nlp is used. For example, `http://localhost:8553/v2/search?limit=3&search=tartu mnt 1, tallinn`: -``` +```json { "parsed": { "city": "tallinn", @@ -373,83 +373,47 @@ coordinates are preferred. The result is given in JSON format. It returns a JSON object with two keys: `"origin"` (coordinates of the reference point used in the search) -and `"results"` (array with the POIs). See Poor Maps implementation on -how to process the results. +and `"results"` (array with the POIs). Example response to `http://localhost:8553/v1/guide?limit=2&poitype=restaurant&radius=1000&search=pühavaimu,%20tallinn`: + +```json +{ + "origin": { + "lat": 59.43834699271878, + "lng": 24.746281838016813 + }, + "query_name": "", + "query_type": "restaurant", + "results": [ + { + "admin_region": "Golden Dragon, 7, Pühavaimu, Tallinna vanalinn, Kesklinna linnaosa, Tallinn, Harju maakond, Eesti", + "distance": 48.305660772979806, + "lat": 59.4385562050235, + "lng": 24.74703017433754, + "object_id": 41060, + "title": "Golden Dragon, 7, Pühavaimu", + "type": "Food" + }, + { + "admin_region": "Restoran Trofé, 29, Pikk, Tallinna vanalinn, Kesklinna linnaosa, Tallinn, Harju maakond, Eesti", + "distance": 57.47079082155229, + "lat": 59.43886465906252, + "lng": 24.746263062553567, + "object_id": 41038, + "title": "Restoran Trofé, 29, Pikk", + "type": "Food" + } + ] +} +``` ## Routing There are two versions of routing protocol that have to be used in -accordance with the used backend. Version 1 (`v1/route`) is used by -libosmscout and is described below. Version 2 (`v2/route`) is used by +accordance with the used backend. Version 2 (`v2/route`) is used by Valhalla and uses Valhalla's API. Version 2 is supported, in part, by -libosmscout as well. - -### Version 1: libosmscout - -The routing component allows to calculate routes between given -points. Server can be accessed via `/v1/route` path: - -`http://localhost:8553/v1/route?radius={radius}&type={type}&gpx={gpx}&p[0][search]={search}&p[0][lng]={lng}&p[0][lat]={lat}& ... &p[n-1][search]={search}&p[n-1][lng]={lng}&p[n-1][lat]={lat}` - -where each point along the route can be given either by `{search}` or -longitude and latitude with precise coordinates preferred if the both -approaches are used. The number of points `n` should be at least two, -with the counting starting from 0. The server looks for points in the -query by starting from index 0 and incrementing it by one until the -points with consecutive indexes are all found. Note that if you skip -an index in the list (like having indexes 0, 1, 3, and 4), the points -after the increment larger than one will be ignored (in the example, -points 3 and 4). - -The query parameters are: - -`{type}` - type of the vehicle with `car`, `bicycle`, and `foot` -supported (`car` is default); - -`{radius}` - distance from the points in meters where closest routing -point is searched for (1000 meters by default); - -`{gpx}` - when 1 or larger integer, GPX trace of the route will be -given in the response of the server instead of JSON reply; - -`{search}` - a query that is run to find a reference point, the first -result is used; - -`{lng}`, `{lat}` - longitude and latidude, respectively. - - -For example, the following request finds the route between two cities -given by names: - -`http://localhost:8553/v1/route?p[0][search]=Tallinn&p[1][search]=Tartu` - - -The result is given in JSON format. It returns a JSON object with -several keys: - -`locations` - coordinates of the reference points used in the calculations; - -`language` - language of the maneuvers instructions; - -`lat` - array of latitudes with the calculated route; - -`lng` - array of longitudes with the calculated route; - -`maneuvers` - array of objects describing maneuvers; - -`summary` - object specifying length and duration of the route; - -`units_distance` - units of distances used in route description (kilometers for now); - -`units_time` - units of time used in route description (seconds for now). - - -See included example under Examples and Poor Maps implementation on -how to process the results. - -At present, the car speeds on different roads are inserted in the -code. This will improve in future. +libosmscout as well. Older Version 1 (`v1/route`) is used by +libosmscout and is described in [OLD_API](README.older_api.md). ### Version 2: Valhalla @@ -478,6 +442,7 @@ this flag, the client application can determine whether version 1 protocol response has been used. + ## Translations The translations were contributed by diff --git a/README.older_api.md b/README.older_api.md new file mode 100644 index 00000000..21ab6812 --- /dev/null +++ b/README.older_api.md @@ -0,0 +1,67 @@ +## Description of older APIs + +While APIs described here are supported, the developers are encouraged +to use APIs described in the main [README](README.md). + +### Routing, Version 1: libosmscout + +The routing component allows to calculate routes between given +points. Server can be accessed via `/v1/route` path: + +`http://localhost:8553/v1/route?radius={radius}&type={type}&gpx={gpx}&p[0][search]={search}&p[0][lng]={lng}&p[0][lat]={lat}& ... &p[n-1][search]={search}&p[n-1][lng]={lng}&p[n-1][lat]={lat}` + +where each point along the route can be given either by `{search}` or +longitude and latitude with precise coordinates preferred if the both +approaches are used. The number of points `n` should be at least two, +with the counting starting from 0. The server looks for points in the +query by starting from index 0 and incrementing it by one until the +points with consecutive indexes are all found. Note that if you skip +an index in the list (like having indexes 0, 1, 3, and 4), the points +after the increment larger than one will be ignored (in the example, +points 3 and 4). + +The query parameters are: + +`{type}` - type of the vehicle with `car`, `bicycle`, and `foot` +supported (`car` is default); + +`{radius}` - distance from the points in meters where closest routing +point is searched for (1000 meters by default); + +`{gpx}` - when 1 or larger integer, GPX trace of the route will be +given in the response of the server instead of JSON reply; + +`{search}` - a query that is run to find a reference point, the first +result is used; + +`{lng}`, `{lat}` - longitude and latidude, respectively. + + +For example, the following request finds the route between two cities +given by names: + +`http://localhost:8553/v1/route?p[0][search]=Tallinn&p[1][search]=Tartu` + + +The result is given in JSON format. It returns a JSON object with +several keys: + +`locations` - coordinates of the reference points used in the calculations; + +`language` - language of the maneuvers instructions; + +`lat` - array of latitudes with the calculated route; + +`lng` - array of longitudes with the calculated route; + +`maneuvers` - array of objects describing maneuvers; + +`summary` - object specifying length and duration of the route; + +`units_distance` - units of distances used in route description (kilometers for now); + +`units_time` - units of time used in route description (seconds for now). + + +See included example under Examples and Poor Maps implementation on +how to process the results.