Overview
The different Route APIs calculates routes for different vehicle types and can return up to a total of 3 different routes which can vary in length and drive time.
Each of the routes in the response is a GeoJSON feature collection which can be easily displayed in third party GIS software.
The GeoJSON features consists of individual route parts, which holds the geometry for that route part, the driving instructions, road features etc.
The complete geometry for the entire route is the sum of the geometry of all the features in the feature collection.
The APIs also support a OutputSRS parameter where you can specify the output coordinate system. This helps avoiding doing client-side reprojection
of the LineString coordinates. Supported coordinate systems are UTM33N (EPSG 25833) and WGS84 (EPSG 4326).
The underlying road network geometry is stored in UTM33N and that will be most accurate, but WGS84 can be used for visualization purposes.
Migrating from Ruteplan API v2 to Ruteplan API v3
The main difference between v2 and v3 is the repsonse model. In v3 the route is a GeoJSON Feature Collection and all the data about that route is in that array.
In v2 each route was split in different arrays, one containing route-part information and a separate array for the geometry.
When migrating from v2 to v3 the response model parsing will need to be rewritten. The goal of changing the response model was simplicity, so when using the v3 response model,
each route can be used directly with third party GIS software without any special client-side logic.
The recommended approach for parsing the response model is using a OpenAPI Code Generation Tool.
The various parameters are roughly the same between v2 and v3. The main difference is the vehicle type parameters which has been split up in seperate APIs in v3.
So instead of using a parameter bruksklassespesialtransport=bk_10_50 you would use the endpoint /api/Routes/bruksklasseSpesialTransport and
set parameter Bruksklasse=Bk_10_50
as in this example:
https://www.vegvesen.no/ws/no/vegvesen/ruteplan/routingservice_v3_0/open/routingservice/api/Route/bruksklasseSpesialTransport?Bruksklasse=Bk_10_50&Stops=236397.85827911127%2C6662445.118563663%3B237667.8608191164%2C6675145.143963715&ReturnFields=Geometry
Code generation
The APIs implement the OpenAPI specification which means you can use code generation tools create contracts for your target language.
For typescript for instance, we have found that tools that support the "options pattern" are most favorable because of the large parameter space of the specific APIs.
For our test clients we have chosen to use openapi-typescript-codegen
Here is a sample package.json file for using that tool to create typescript files for the APIs
{
"devDependencies": {
"openapi-typescript-codegen": "^0.25.0"
},
"scripts": {
"generate": "openapi --input https://www.vegvesen.no/ws/no/vegvesen/ruteplan/routingservice_v3_0/open/routingService/swagger/v1/swagger.json --output ./generatedTypeScriptFiles --useOptions"
}
}
then after a npm/yarn install you can simply run npm/yarn run generate to do the work!
404 Not Found Errors
In case of 404 not found error, the http response will contain a message with status code and error message in json format:
{
"Code":9200,
"Message":"Start posisjonen er for langt unna gyldig vegnett."
}
Complete list of current error messages with their corresponding error code:
- 9005 - Ingen rute funnet.
- 920X - X Posisjon er for langt unna gyldig vegnett. X Indicates which stop point is to far away from valid road network and corresponds to the index of the point in the "Stops" input parameter.
- 9008 - Rutemotoren er overbelastet. For mange forespørsler.
- 9009 - Tidsavbrudd fra rutemotoren.
- 9999 - Intern feil i rutemotoren.
9200 to 9299 provides a set with error messages based on missing points or link with location.
Numbers over 9200 represent which point in input request that cannot be mapped.
- Startposisjon er for langt unna gyldig vegnett.
- Sluttposisjon er for langt unna gyldig vegnett.
- Viapunktet er for langt unna et gyldig vegnett.
- Kunne ikke finne start på nærmeste lenke.
- Kunne ikke finne slutt på nærmeste lenke.
- Kunne ikke finne nærmeste lenke for viapunkt.