Road2 is a route and isochrone calculation server written in Javascript and designed to work with NodeJS. This server offers the calculation of routes and isochrones via existing engines like OSRM or PGRouting. Road2 is therefore an interface for calculation engines. These are not done in Road2's code but via calls to its engines. This can mean calling a library, or a database, or another web service.
Road2 was designed with the idea of being able to easily add new engines and new APIs, and this, in a completely transparent way for each other. In other words, adding an engine has no impact on existing APIs. The goal is to facilitate the addition of new features while maintaining access to the service. For a longer discussion on the software concepts introduced in Road2, please refer to the following documentation.
Currently, Road2 offers three engines, OSRM, PGRouting and Valhalla, through one REST API. Other API are coming.
Road2 offers several sets of features :
- Calculate routes
- Calculate isochrones and isodistances
- Manage the service
- etc...
These sets include all the functionalities and are detailed here.
Road2 is released under the GPL v3 license.
IGN offers a demonstrator for the route and the isochrone. These demonstrators allow you to build queries via a map and visualize the results.
Otherwise, for a first grip of the service locally, it is possible to use the alpine image of Road2. This will make it possible to have a local instance of the service and a web page allowing it to be tested. Setup instructions are given here.
IGN offers a visualization of the user API for the itinerary and the isochrone.
IGN also offers pages for testing an instance of the service throughout France, with map visualization. There is a page for the itinerary and a page for the isochrone.
Otherwise, all available APIs are documented in this folder. At the moment there is only one user API which is documented via a file JSON using openapi 3.0.0, and one documented admin API via another file JSON following the same formating.
It is possible to view these API documentations locally by following the instructions that are here.
To use this project, it is necessary to have NodeJS installed on the machine used. The NodeJS version used during development is 12.14.0.
The installation of the modules is carried out via NPM. Going to the root of the project:
npm install
NB: There are optional dependencies to manage those of each engine. For more information, see this document.
Whatever the data source, it is necessary to provide it in one of the formats used by Road2. Since Road2 can use several calculation engines, it accepts several data formats:
- OSRM 5.26.0 makes it possible to use OSRM data generated with this version.
- PGRouting 3.1.3 makes it possible to use a database using this version. It will be necessary to add the project procedures pgrouting-procedures so that Road2 can communicate with the database.
This data can therefore be generated from any database, or from OSM files. The route-graph-generator project offers tools to generate graphs from any database or OSM files. (If the database does not correspond to the format of the database expected by route-graph-generator, it will suffice to derive it.)#TODO
For a detailed discussion of the expected data, refer to this documentation.
In order for the server to work, it is necessary to configure. This involves creating a tree structure of a few JSON files allowing instantiation of the server with resources.
Once configured, it is possible to launch an instance of Road2 with the command:
node ${road2}/src/js/road2.js --ROAD2_CONF_FILE=${configuration}/administration.json
In the docker/distributions folder, you will find different Dockerfiles that allow you to see the installation and test the service on different platforms. At the moment, Debian 10 is available.
Contributing to this project is welcome (see our code of conduct on this subject). We have set up a guide of contributions to help you in this process.
Developer documentation can be found here. It indicates the useful concepts to carry out developments on Road2.
To learn more about our roadmap, you can look at the IGNF/Road2 Roadmap project.
Finally, it is possible to use this docker-compose to have a development environment including building binaries, modules and generating data.
In order to use Road2 in production, several informations are given in this document. These are mainly the needs already observed for a production launch of the service covering the whole of French territory.