YOURS

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
English 한국어 русский
Quick links
Live demonstration
Routing engine
Indexing service
Route altitude profiles
Routing Benchmarks

This is the main wiki project page for YOURS, Yet another OpenStreetMap Route Service.

 ! Call for sponsoring !
For this project a sponsor is needed to host the Gosmore routing backend. Please contact user Lambertus if you can help. Thanks!
Minimal requirements: dual core, 16 GB ram, 100 GB disk, 200 MB traffic/month

Introduction

YOURS goal is to use OpenStreetMap data to make a routing website utilizing as much other (opensource) applications as possible. Currently integrated applications are:

Hosting for the YOURS demo website yournavigation.org is sponsored by Oxilion. Routing servers are sponsored by OpenStreetMap and an anonymous donor.

Name

As there are already a number of route services using OSM data it becomes more difficult to find a suitable application/project name. Each ones name contains relevant words like 'open', 'service', 'route', etc. So I thought of 'Yet Another Openstreetmap Routing Service' short YAORS which sounds like 'yours' hence: YOURS. As in 'your route service'...oh well :-)

Features

  • Generate fastest or shortest routes in different modes:
    • using all available roads for Car, Bicycle and Pedestrians .
    • using only national, regional or local cycle routes/networks for Bicycle.
  • Unlimited via points (waypoints) to make complex routes.
  • Drag and drop waypoints moving.
  • Drag and drop waypoint ordering.
  • Geolocation: Lookup street- and placenames to determine their coordinates.
  • Reverse geolocation: Lookup coordinates to determing their street- and placenames.
  • Generate route altitude profiles.
  • Download routes as GPX file so the route can be put onto a GPS device for trackback.
  • Provides a routing calculation API that returns KML or geoJSON.
  • Allow quick editing of the current mapview using a link to the online 'Potlatch' map editor.
  • Single click map/route data testing.
  • Show the date of the planet-latest file on which the routing database is based.
  • Client-side (session based) route caching.
  • Automatic zoom to location of the user based on geoIP.

Compare YOURS against other online OpenStreetMap navigation websites.

Resource requirements

The resources required to run a server for worldwide routing are listed below. The 'minimal' hardware requirements are probably enough for responsive regional routing. Building a new route database requires a fair amount of disk space. A copy of the OpenStreetMap planet dump requires approx. 20 GB while the resulting route database is about 15 GB and including intermediate files and including the existing routing database the required disk space adds up quickly to 80 GB. Off-site routing database generation will reduce this to about 30 GB at the expense of more scripting and traffic.

Software

  • Linux (32-bit for local routing, 64-bit for regional/worldwide routing)
  • Remote shell access (ssh)
  • Webserver (Apache2)
  • PHP5
  • Java 1.6

Hardware

Minimal: one concurrent route request, possibly slow

  • 8 GB ram
  • 80 GB disk space
  • 1 GB traffic/month

Optimal: two+ concurrent route requests

  • 24 GB ram
  • 160 GB disk space
  • 10 GB traffic/month

Development

YOURS code is available under the BSD license. You can download the code for version 1 (as shown on http://www.yournavigation.org) from the OpenStreetMap SVN server:

 svn co http://svn.openstreetmap.org/applications/routing/yours/branches/version-1.0-via

The developer version which will support route via's and driving directions will be committed to the trunk of the repository in a few weeks. Contributors please check out the branch 'version-1.0' only. SVN trunk is not yet up to date!

 svn co http://svn.openstreetmap.org/applications/routing/yours/trunk (Do not use this link)

Contact, bug reports and feature requests

Bug reports and feature requests should preferably be done as Trac tickets assigned to the YOURS project. You can also add your comment to the discussion page or forum topic. For other stuff you can email me: osm at na1400 dot info but I'm also often present on the irc channels #osm and #osm-dev between 09:00 and 23:00 CET.

Contribution

Any help in making YOURS better is welcome! Please refer to a ticket when committing your changes like:

 Added new feature blah (refs #1234)

Where 1234 is the ticket number requesting the new feature or bugreport

Known issues

There is a list of active Trac tickets. A list of sub-optimal or weird routes is listed here.

  • Very long routes can't be exported in GPX format. This needs a different implementation approach (YOURS).
  • The route altitude profiler only works for routes with less then 400 nodes (YOURS).
  • Gosmore is not designed for generating very long routes (> 200km).
  • No routing in the Northeastern part of the American continent (Server/hosting).
  • Due to server limitations the American continent is devided into three sections: Northeast-, Northwest- and South America. Route calculations can't be performed when the route goes from one section to another (Server/hosting/YOURS).
  • Non-standard ASCII characters are currently not supported by the YOURS Namefinder interface. I assume this affects a lot of non-western countries, but so far I've only received feedback on this from Germany and Denmark...(YOURS).
  • Oneway restrictions on roads tagged using oneway=true are disregarded (Gosmore).
  • Some routes cannot be calculated (Gosmore).
  • Internet Explorer fails to show the route altitude graph (YOURS). Fixed thanks to Tobias Lindh.

Altitude profile

The altitude profile is based upon SRTM data which comprises multiple terabytes of data when covering the world but sponsored servers usually don't have that amount of storage available. A possible solution for this is to spread the data over a number of servers. Below is a list of currently supported servers by YOURS. Please send me a message if you have configured a server yourself and want YOURS to support it too. If you decide to configure a profile server please make sure to overlap the neighboring areas by e.g. 1 degree as that will make generating profiles easier.

Host Base URL Area description Area bbox
Metacarta http://labs.metacarta.com/altitude/profile/ North and South America N60 W-179 S-56 E-44
Komяpa http://altitude.komzpa.net/profile/ Belarus N57 W23 S50 E33

The website

Setup instructions

Prerequisites

  • I assume that a webserver with PHP is already available. If not, there are many manuals on the internet on how to get this running.
  • You will also need php5-curl for Curl integration (used by the cross-domain proxy transport.php)
  • SVN tools are needed to get a copy from the repository. Contact me for a zip file if you don't have (or want) SVN tools installed.
  • Use the Firefox browser with the Firebug plugin to debug your application. You'll learn about errors and it's causes quickly that way.

Installing Gosmore routing engine

  • Get a copy of Gosmore following the instructions from: Gosmore
  • Download a precompiled map as described in the link above, name it gosmore.pak and put it in the same directory where Gosmore resides.
  • Alternatively you can download a planet dump or planet extract from: Planet and convert it into a gosmore.pak following the instruction on the Gosmore wiki page.
  • Compile Gosmore for a server without graphical desktop environment with CFLAGS=-DHEADLESS -DONLY_ROUTING.

Concurrent access control

Gosmore sometimes requires large amounts of ram so it is wise to enable load control if you expect to serve multiple requests concurrently. With this option Gosmore uses shared ram features and spreads available resources over the concurrent processes. It will also kill the most resource hungry process if there are not enough resources available, leading to incomplete routes (routes that start with 'Jump'), therefore the server should have a lot of ram to lower the chance of this behavior occurring. So, if your server has 16+ GB RAM and you require concurrent then you can add the compile option -DLD_CTRL. Gosmore will create a file named 'ld_ctrl' that it needs for inter process communication. If you call Gosmore from a webpage (which YOURS obviously does) then you'll need to give the webserver read/write access to this file. With Linux this action is performed by the command 'chmod 0666 ld_ctrl'.

Installing RoutingInstructions

  • Follow the instructions on this page. It's straightforward.

For Ubuntu the packages cmake, libqt4-dev, qt4-dev-tools, libqt4-core, qt4-linguist-tools and libicu48 are needed. For Debian 7 "Wheezy" the packages libqt4-dev, qt4-dev-tools, qt4-linguist-tools are needed.

Installing YOURS website

  • Go to the public html directory and get a copy of YOURS using the SVN command:
    svn co http://svn.openstreetmap.org/applications/routing/yours/trunk/www yours

You should now have a directory named 'yours' in the public html directory.

  • Open gosmore.php in the API directory, e.g.: yours/api/dev/gosmore.php and put the correct path the the yours www directory ($www_dir), the path to the gosmore routing engine ($yours_dir) and an email address for the administrator (only used to notify API abusers) so you may leave it blank.

Finally

Start your browser and go to: http://www.my-server.com/yours and enjoy!

Embedding YOURS into 3rd party web application

It's fairly easy to get routing in your own web application. Determine the TO and FROM coordinates and ask www.yournavigation.org to calculate a route for you. Have a look at the API documentation for more information on the parameters and it's usage.

Cross-site AJAX calls

Browsers don't allow cross-site AJAX calls (it's a security restriction). There are two possible solutions for this:

  1. Relay the request to www.yournavigation.org via a proxy on your own server.
  2. Use a 3rd party JavaScript library that uses tricks to perform cross-site AJAX requests. E.g. by using a Flash or Java applet.

Option 1 is probably easiest to understand and implement. There are many proxy's available on the internet, but the YOURS repository already contains a proxy for cross-site calls: Transport.php

Once you have the proxy in place on your server then you can request a route using an AJAX call like this (untested!):

var url = 'http://www.my-server.com/yours/transport.php?url=http://www.yournavigation.org/api/1.0/gosmore.php?format=kml&flat=52.215676&flon=5.963946&tlat=52.2573&tlon=6.1799&v=motorcar&fast=1&layer=mapnik';

Notice the replacement of 'gosmore.php?' with 'gosmore.php&' compared to regular URL constructions when using the proxy script in the example above.

Note: This proxy script needs the CURL plugin for PHP.

Websites that run their own instance of YOURS

Please add your website here

API documentation

If you would like to embed some of the functions of the YOURS website in your own site or application then you can incorporate the API. The API is described below.

Usage

Use of the API is on a Fair Use Policy basis: everyone can use the API as long as it won't overload the server systematically. If you do overload but provide an X-Yours-client header (as described below) then I'll try to contact you to find a solution. If you don't provide this information (or I can't contact you) then you might become blocked (this has happened only once so far, so don't worry too much about it).

Speed/Reliability

The sponsored server that runs www.yournavigation.org only has 2 GB ram but the routing database is about 12 GB. This forces the server to move blocks of data in and out of ram when there are multiple concurrent users that request routes all over the world. Despite the speed with which Gosmore is able to calculate routes in optimal conditions, the harddisk seeks will slow the server down almost completely in case of such situation and new requests might be rejected if there are already too many concurrent requests running (this happens quite often unfortunately, multiple times per day). There is not much that can be done about it unless the server is upgraded with more ram and/or an SSD harddisk (Hint!).

Fair Use Policy

The routing API is open and freely available for everyone under the condition that you don't overload the server. Overloading the server in this context means: more then 1 request per second for sustained periods of time. Bursting multiple requests for short time-periods is not a problem though. Please contact me (Lambertus) in advance if your application is expected to perform a lot of requests. Commercial, public or other applications that are expected to perform lots of requests must identify themselves by providing an application name/contact information in the request headers (see API 1.0 documentation).

API users (IP addresses or applications) that violate this FUP will be blocked. I reserve the right of deciding when an API user is overloading the server.

API revisions

The API can have multiple revisions. In each version the interface is kept unchanged to prevent 3rd party applications from becoming broken. Each API version is kept in it's own directory which allows multiple API versions to operate simultaneously without interfering with each other. 3rd party developers can then gradually move from one version to another without being forced to do so on short notice. Note: The API interface can change without notice as long as it's called 'dev'.

The current API revision is '1.0'. The 2.0 API is being developed as 'dev'. The base URL for each API is: http://www.yournavigation.org/api/, so the 1.0 API is located at: http://www.yournavigation.org/api/1.0/ and the dev API is located at: http://www.yournavigation.org/api/dev/.

Version 1.0

Clients of this API version are kindly requested to identify themselves using an extra HTTP header: X-Yours-client. This way the (amount of) users can be tracked and appropriate action taken if a 3rd party application is overloading the service or otherwise misbehaving. E.g. the yournavigation website is identified by X-Yours-client: www.yournavigation.org.

Routing API

The routing API provides routing information based upon a given start/end location and some route parameters like the vehicle type, etc. The resulting route is returned as a KML file containing all the nodes from start to finish. If Gosmore is unable to successfully calculate a route then the most complete route so far will be returned.

Base URL

http://www.yournavigation.org/api/1.0/gosmore.php

Parameters

Available parameters are described below. Only the location parameters are required. All other parameters are optional, they will use the default value when omitted.

  • flat = latitude of the starting location.
  • flon = longitude of the starting location.
  • tlat = latitude of the end location.
  • tlon = longitude of the end location.
  • v = the type of transport, possible options are: motorcar, bicycle or foot. Default is: motorcar.
  • fast = 1 selects the fastest route, 0 the shortest route. Default is: 1.
  • layer = determines which Gosmore instance is used to calculate the route. Provide mapnik for normal routing using car, bicycle or foot. Provide cn for using bicycle routing using cycle route networks only. Default is: mapnik.
  • format = specifies the format (KML or geoJSON) in which the route result is being sent back to the client. This can either be kml or geojson. Default is: kml.
  • geometry = enables/disables adding the route geometry in the output. Options are 1 to include the route geometry in the output or 0 to exclude it. Default is: 1.
  • distance = specifies which algorithm is used to calculate the route distance. This returned value is always in metric units (km), independent of the chosen language. Options are v for Vicenty, gc for simplified Great Circle, h for Haversine Law, cs for Cosine Law. Default is: v. Implemented using the geography class from Simon Holywell.
  • instructions = enbles/disables adding driving instructions in the output. Options are 1 to include driving directions, 0 to disable driving directions. Default is 0.
  • lang = specifies the language code in which the routing directions are returned. Distances in the instructions are given in metric or imperial units depending on the chosen language. Default is en_US (English). Options are:
Languages
Code Language Translation quality
bs Bosnian 34 of 34
ca Catalan; Valencian 34 of 34
cs Czech 5 of 34
da Danish 34 of 34
de German 34 of 34
el Modern Greek 34 of 34
en_GB Brittish English 24 of 34
es Spanish 34 of 34
et Estonian 34 of 34
fi Finnish 34 of 34
fr French 34 of 34
gl Galician 34 of 34
hu Hungarian 7 of 34
it Italian 34 of 34
kk Japanese 34 of 34
km Central Khmer 34 of 34
lt Lithuanian 24 of 34
lv Latvian 34 of 34
nb Norwegian Bokmål 34 of 34
nds Low German 24 of 34
nl Dutch; Flemish 34 of 34
pa Panjabi; Punjabi 19 of 34
pl Polish 34 of 34
pt Portuguese 34 of 34
pt_BR Brazilian Portugese 34 of 34
ru Russian 34 of 34
sk Slovak 34 of 34
sl Slovenian 34 of 34
sv Swedish 34 of 34
tr Turkish 1 of 34
uk Ukrainian 34 of 34
zh_CN Chinese 4 of 34
zh_TW Taiwanese Chinese 34 of 34



Note: Support for route instructions and it's translations is provided by RoutingInstructions. Helping this project with translations and keeping this table up-to-date is welcome!.

Example URL

http://www.yournavigation.org/api/1.0/gosmore.php?format=kml&flat=52.215676&flon=5.963946&tlat=52.2573&tlon=6.1799&v=motorcar&fast=1&layer=mapnik

Export API

YOURS can export a route in different formats, like Waypoints or GPX track. Provide the route and it will return the route in the requested format.

Base URL

http://www.yournavigation.org/api/1.0/saveas.php

Parameters

  • type = the type of output format, possible options are: gpx (GPX track), wpt (Waypoints).
  • data = the source route in lat/lon pairs. Each pair is separated by a comma character while the lat/lon values are separated by a space character.

Example URL

http://www.yournavigation.org/api/1.0/saveas.php?type=gpx&data=5.62373%2053.01,5.62359%2053.01014,5.62336%2053.01024,5.62314%2053.010303

API users

Below is a list of known API users. The list of API users is incomplete because there are possibly many unknown clients (not everyone provides identification information).
Please add your service here as well

  • The YOURS demonstration site.
  • Mapi simple Javascript mapping and routing API.
  • Woophoo mobile GPS tracking system.
  • Tracks4Bikers Mountaibike tracks site.
  • Aosm routing application running on J2ME and BlackBerry devices.
  • MGMaps Lib Mobile Mapping SDK from Nutiteq, as sample directions service (J2ME, BlackBerry, Android devices).
  • Maemo mapper Maemo mapper OSM routing script. (Note: Does not seem to be using YOURS anymore)
  • OpenMaps is an iPhone maps application.
  • OpenSatNav is an Android navigation application.
  • OpenVoiceNav is an navigation application for the visually impaired.
  • gvSIG mini is a map viewer for mobile phones, that displays existing free maps tiles services, such as OpenStreetMap, Yahoo Maps, Microsoft Bing and more.
  • MySpeed is an Android navigation application with speed logging and speed camera alerts.
  • Parkenapp is a routing application for the iPhone specifically targetting parking needs (in German)
  • OpenMobileMaps is a map viewer application for Windows Mobile phones as an alternative to Google Maps.
  • AndRoad is an OpenStreetMap-based navigation app for Android.
  • PocketNavigator enables you to navigate in a foreign city without forcing you to repetetive look on your device as a usual navigation system would do.
  • TangoGPS is an easy to use, fast and lightweight mapping application for use with or without GPS. It runs on any Linux platform from the desktop over eeePC down to phones like the Openmoko Neo.
  • tub2go is a web application for students at the Technische Universität Berlin.
  • Fahrtenbuch is a navigation app for Windows Phone 7.
  • ViewRanger is an outdoor GPS app for your mobile phone or tablet.
  • UBC CPSC 210 is a Computer Science curriculum course covering complex software systems construction provided by the University of British Columbia.
  • Locus is an Android app aimed at tourist, hiking an geocaching navigation.
  • 700_City_Maps is an navigation app for the iPhone/iPad.
  • PickaCab is an app for iPhone or Android to 'Book the nearest available taxi to you at the touch of a button'.
  • Klinikkarte.de is a german website for searching hospitals.
  • Chester Zoo Mobile app for routing inside the zoo (among other things).
  • Manutec
  • Sat Eye GPS tracking
  • Norgeskart Mobile app displaying topographical and sea maps for Norway.
  • Reloado.com is a search engine and a map service.
  • ProOnGo is a mileage tracking service.
  • University of Osnabrueck iPhone app.
  • Anagog.com provides location based services.
  • Cyclemaps Lite is an iPhone app for cyclists.

Todo list