diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index d961ab0d33..70ab74e11f 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -5,7 +5,8 @@ name: Deploy Backend Documentation to Pages on: # Runs on pushes targeting the `main` branch. push: - branches: ["main"] + tags: + - latest # Allows you to run this workflow manually from the Actions tab workflow_dispatch: diff --git a/docs/.vitepress/components/VersionSwitcher.vue b/docs/.vitepress/components/VersionSwitcher.vue new file mode 100644 index 0000000000..ce41d46fa8 --- /dev/null +++ b/docs/.vitepress/components/VersionSwitcher.vue @@ -0,0 +1,185 @@ + + + + + + + \ No newline at end of file diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 4d6040d72e..0c1552993d 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -1,7 +1,8 @@ import {withMermaid} from "vitepress-plugin-mermaid"; +import defineVersionedConfig from 'vitepress-versioning-plugin' // https://vitepress.dev/reference/site-config -export default withMermaid({ +export default withMermaid(defineVersionedConfig({ mermaid: { // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options }, @@ -22,6 +23,7 @@ export default withMermaid({ } }, themeConfig: { + versionSwitcher: false, // https://vitepress.dev/reference/default-theme-config siteTitle: false, logo: { @@ -30,7 +32,15 @@ export default withMermaid({ alt: 'openrouteservice logo' }, search: { - provider: 'local' + provider: 'local', + options: { + _render(src, env, md) { + const html = md.render(src, env) + if (env.frontmatter?.search === false) return '' + if (env.relativePath.startsWith('versions')) return '' + return html + } + } }, outline: { level: [2, 4] @@ -50,16 +60,19 @@ export default withMermaid({ {text: 'Homepage', link: 'https://openrouteservice.org'}, {text: 'API Playground', link: 'https://openrouteservice.org/dev/#/api-docs'}, {text: 'Forum', link: 'https://ask.openrouteservice.org'}, + {component: 'VersionSwitcher'} ], // undocumented options for NotFound-Page notFound: { - title: 'MAYBE YOU CLICKED AN OLD LINK?', + title: 'PAGE NOT FOUND', quote: 'We recently reworked most of our documentation. You probably ended up here by clicking an old link somewhere, e.g. in the forum. Let us know how you got here and we\'ll fix it. Click the link below and check "Getting Started" - this will help you figure out where to find what you came for.', - linkText: 'Documentation Home', + quote: 'We recently introduced versioning for our documentation. You probably ended up here by changing the version - and this page doesn\'t exist in this version. Click the link below and check "Getting Started" - you will need to change the version again, though.', + linkText: 'Documentation Home - latest Version', }, - sidebar: [ + sidebar: { + '/': [ { - text: 'Home', link: '/', + text: 'Home - v9.0.0', link: '/', items: [ {text: 'Getting Started', link: '/getting-started'}, { @@ -221,5 +234,23 @@ export default withMermaid({ footer: { message: 'openrouteservice is part of HeiGIT gGmbH and Universität Heidelberg GIScience research group. | Imprint' } + } + }, + + locales: { + root: { + label: 'English', + lang: 'en' } -}) + }, + + versioning: { + latestVersion: "v9.0.0 (latest)", + sidebars: { + processSidebarURLs: true, + sidebarPathResolver: (version) => `.vitepress/sidebars/versioned/${version}.json`, + sidebarUrlProcessor: (url, version) => url.startsWith("http") ? url : `/${version}${url}` + }, + }, + +}, __dirname )) diff --git a/docs/.vitepress/sidebars/versioned/v7.1.1.json b/docs/.vitepress/sidebars/versioned/v7.1.1.json new file mode 100644 index 0000000000..a6d0f2daea --- /dev/null +++ b/docs/.vitepress/sidebars/versioned/v7.1.1.json @@ -0,0 +1,167 @@ +[ + { + "text": "Home - v7", + "link": "/", + "items": [ + { + "text": "Getting Started", + "link": "/getting-started" + }, + { + "text": "Installation and Usage", + "collapsed": true, + "link": "/installation/Installation-and-Usage", + "items": [ + { + "text": "Running with Docker", + "link": "/installation/Running-with-Docker" + }, + { + "text": "Building from Source", + "link": "/installation/Building-from-Source" + }, + { + "text": "System Requirements", + "link": "/installation/System-Requirements" + }, + { + "text": "Configuration", + "link": "/installation/Configuration" + }, + { + "text": "Advanced Docker Setup", + "link": "/installation/Advanced-Docker-Setup" + }, + { + "text": "Backend Documentation", + "link": "/installation/Backend-Documentation" + } + ] + }, + { + "text": "Data", + "link": "/Data" + }, + { + "text": "Contributing", + "collapsed": true, + "link": "/contributing/Contributing", + "items": [ + { + "text": "Contributing Translations", + "link": "/contributing/Contributing-Translations" + } + ] + }, + { + "text": "Documentation", + "collapsed": true, + "link": "/documentation/Documentation", + "items": [ + { + "text": "Tag Filtering", + "link": "/documentation/Tag-Filtering" + }, + { + "text": "Travel Speeds", + "collapsed": true, + "link": "/documentation/travel-speeds/Travel-Speeds", + "items": [ + { + "text": "Waytype Speeds", + "link": "/documentation/travel-speeds/Waytype-Speeds" + }, + { + "text": "Surface Speeds", + "link": "/documentation/travel-speeds/Surface-Speeds" + }, + { + "text": "Tracktype Speeds", + "link": "/documentation/travel-speeds/Tracktype-Speeds" + }, + { + "text": "Country Speeds", + "link": "/documentation/travel-speeds/Country-Speeds" + } + ] + }, + { + "text": "Route Attributes", + "link": "/documentation/Route-Attributes" + }, + { + "text": "Routing Options", + "collapsed": true, + "link": "/documentation/routing-options/Routing-Options", + "items": [ + { + "text": "Examples", + "link": "/documentation/routing-options/Examples" + }, + { + "text": "Country List", + "link": "/documentation/routing-options/Country-List" + } + ] + }, + { + "text": "Instruction Types", + "link": "/documentation/Instruction-Types" + }, + { + "text": "Extra Info", + "collapsed": true, + "link": "/documentation/extra-info/Extra-Info", + "items": [ + { + "text": "Steepness", + "link": "/documentation/extra-info/Steepness" + }, + { + "text": "Surface", + "link": "/documentation/extra-info/Surface" + }, + { + "text": "Waycategory", + "link": "/documentation/extra-info/Waycategory" + }, + { + "text": "Waytype", + "link": "/documentation/extra-info/Waytype" + }, + { + "text": "Trail Difficulty", + "link": "/documentation/extra-info/Trail-Difficulty" + }, + { + "text": "Road Access Restrictions", + "link": "/documentation/extra-info/Road-Access-Restrictions" + } + ] + }, + { + "text": "Geometry Decoding", + "link": "/documentation/Geometry-Decoding" + }, + { + "text": "Structured Geocoding Query", + "link": "/documentation/Structured-Geocoding-Query" + }, + { + "text": "Matrix Response", + "link": "/documentation/Matrix-Response" + }, + { + "text": "Places Request and Response", + "link": "/documentation/Places-Request-and-Response"}, + {"text": "Geocoding Response", + "link": "/documentation/Geocoding-Response"}, + {"text": "Error Codes", + "link": "/documentation/Error-Codes"} + ] + }, + {"text": "FAQ", + "link": "/Frequently-Asked-Questions"} + ] + } +] diff --git a/docs/.vitepress/sidebars/versioned/v8.2.0.json b/docs/.vitepress/sidebars/versioned/v8.2.0.json new file mode 100644 index 0000000000..9966d29dbe --- /dev/null +++ b/docs/.vitepress/sidebars/versioned/v8.2.0.json @@ -0,0 +1,306 @@ +[ + { + "process": true, + "text": "Home - v8", + "link": "/", + "items": [ + { + "text": "Getting Started", + "link": "/getting-started" + }, + { + "text": "API Reference", + "collapsed": true, + "link": "/api-reference/", + "items": [ + { + "text": "Endpoints", + "collapsed": true, + "link": "/api-reference/endpoints/", + "items": [ + { + "text": "Directions", + "collapsed": true, + "link": "/api-reference/endpoints/directions/", + "items": [ + { + "text": "Requests and Return Types", + "link": "/api-reference/endpoints/directions/requests-and-return-types" + }, + { + "text": "Routing Options", + "link": "/api-reference/endpoints/directions/routing-options" + }, + { + "text": "Extra info", + "collapsed": true, + "link": "/api-reference/endpoints/directions/extra-info/", + "items": [ + { + "text": "Steepness IDs", + "link": "/api-reference/endpoints/directions/extra-info/steepness" + }, + { + "text": "Surface IDs", + "link": "/api-reference/endpoints/directions/extra-info/surface" + }, + { + "text": "Category IDs", + "link": "/api-reference/endpoints/directions/extra-info/waycategory" + }, + { + "text": "Type IDs", + "link": "/api-reference/endpoints/directions/extra-info/waytype" + }, + { + "text": "Difficulty IDs", + "link": "/api-reference/endpoints/directions/extra-info/trail-difficulty" + }, + { + "text": "Restriction IDs", + "link": "/api-reference/endpoints/directions/extra-info/road-access-restrictions" + }, + { + "text": "Country IDs", + "link": "/technical-details/country-list" + } + ] + }, + { + "text": "Route Attributes", + "link": "/api-reference/endpoints/directions/route-attributes" + }, + { + "text": "Geometry Decoding", + "link": "/api-reference/endpoints/directions/geometry-decoding" + }, + { + "text": "Instruction Types", + "link": "/api-reference/endpoints/directions/instruction-types" + } + ] + }, + { + "text": "Isochrones", + "link": "/api-reference/endpoints/isochrones/" + }, + { + "text": "Matrix", + "link": "/api-reference/endpoints/matrix/" + }, + { + "text": "Snapping (not live)", + "link": "/api-reference/endpoints/snapping/" + }, + { + "text": "Export (not live)", + "link": "/api-reference/endpoints/export/" + }, + { + "text": "Health (not live)", + "link": "/api-reference/endpoints/health/" + }, + { + "text": "Status (not live)", + "link": "/api-reference/endpoints/status/" + }, + { + "text": "POI", + "link": "/api-reference/endpoints/poi/" + }, + { + "text": "Elevation", + "link": "/api-reference/endpoints/elevation/" + }, + { + "text": "Geocoder", + "link": "/api-reference/endpoints/geocoder/" + }, + { + "text": "Optimization", + "link": "/api-reference/endpoints/optimization/" + } + ] + }, + { + "text": "Error Codes", + "link": "/api-reference/error-codes" + } + ] + }, + { + "text": "Run ORS instance", + "collapsed": true, + "link": "/run-instance/", + "items": [ + { + "text": "System Requirements", + "link": "/run-instance/system-requirements" + }, + { + "text": "Data", + "link": "/run-instance/data" + }, + { + "text": "Running with Docker", + "link": "/run-instance/running-with-docker" + }, + { + "text": "Running JAR", + "link": "/run-instance/running-jar" + }, + { + "text": "Running WAR", + "link": "/run-instance/running-war" + }, + { + "text": "Building from Source", + "link": "/run-instance/building-from-source" + }, + { + "text": "Configuration", + "collapsed": true, + "link": "/run-instance/configuration/", + "items": [ + { + "text": "Spring Properties", + "link": "/run-instance/configuration/spring/", + "collapsed": true, + "items": [ + { + "text": "server", + "link": "/run-instance/configuration/spring/server.md" + }, + { + "text": "logging", + "link": "/run-instance/configuration/spring/logging.md" + } + ] + }, + { + "text": "ORS Properties", + "collapsed": true, + "items": [ + { + "text": "endpoints", + "link": "/run-instance/configuration/ors/endpoints/", + "collapsed": true, + "items": [ + { + "text": "defaults", + "link": "/run-instance/configuration/ors/endpoints/defaults.md" + }, + { + "text": "routing", + "link": "/run-instance/configuration/ors/endpoints/routing.md" + }, + { + "text": "matrix", + "link": "/run-instance/configuration/ors/endpoints/matrix.md" + }, + { + "text": "isochrones", + "link": "/run-instance/configuration/ors/endpoints/isochrones.md" + }, + { + "text": "snap", + "link": "/run-instance/configuration/ors/endpoints/snap.md" + } + ] + }, + { + "text": "engine", + "link": "/run-instance/configuration/ors/engine/", + "collapsed": true, + "items": [ + { + "text": "profiles", + "link": "/run-instance/configuration/ors/engine/profiles.md" + }, + { + "text": "elevation", + "link": "/run-instance/configuration/ors/engine/elevation.md" + } + ] + }, + { + "text": "cors", + "link": "/run-instance/configuration/ors/cors/" + }, + { + "text": "messages", + "link": "/run-instance/configuration/ors/messages/" + } + ] + }, + { + "text": "JSON config (deprecated)", + "link": "/run-instance/configuration/json.md" + } + ] + } + ] + }, + { + "text": "Contributing", + "collapsed": true, + "link": "/contributing/", + "items": [ + { + "text": "Backend documentation", + "link": "/contributing/backend-documentation" + }, + { + "text": "Contribution guidelines", + "link": "https://github.com/GIScience/openrouteservice/blob/main/CONTRIBUTE.md" + }, + { + "text": "Contributing translations", + "link": "/contributing/contributing-translations" + } + ] + }, + { + "text": "Technical details", + "collapsed": true, + "link": "/technical-details/", + "items": [ + { + "text": "Country List", + "link": "/technical-details/country-list" + }, + { + "text": "Travel Speeds", + "link": "/technical-details/travel-speeds/", + "items": [ + { + "text": "Country Speeds", + "link": "/technical-details/travel-speeds/country-speeds.md" + }, + { + "text": "Tracktype Speeds", + "link": "/technical-details/travel-speeds/tracktype-speeds.md" + }, + { + "text": "Waytype Speeds", + "link": "/technical-details/travel-speeds/waytype-speeds.md" + }, + { + "text": "Surface Speeds", + "link": "/technical-details/travel-speeds/surface-speeds.md" + } + ] + }, + { + "text": "Tag Filtering", + "link": "/technical-details/tag-filtering" + } + ] + }, + { + "text": "FAQ", + "link": "/frequently-asked-questions" + } + ] + } +] diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js deleted file mode 100644 index b306d289df..0000000000 --- a/docs/.vitepress/theme/index.js +++ /dev/null @@ -1,5 +0,0 @@ -// .vitepress/theme/index.js -import DefaultTheme from 'vitepress/theme-without-fonts' -import './custom.css' - -export default DefaultTheme diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000000..5941a46dcf --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,11 @@ +import DefaultTheme from 'vitepress/theme-without-fonts' +import './custom.css' +import { Theme } from 'vitepress'; +import VersionSwitcher from "../components/VersionSwitcher.vue"; + +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + app.component('VersionSwitcher', VersionSwitcher) + } +} satisfies Theme; \ No newline at end of file diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index 9a46fdcbdd..97afa3de21 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -18,13 +18,11 @@ If you are developing ORS or running your own instance, you might benefit from t The [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service) is a complete, interactive and concise technical documentation of our live API. It can also be used to send sample requests to either our live API or an instance of openrouteservice running on your local machine. Use the form "API Server" on the top left to select and edit "Development Server" if you want to send requests to your local instance: -![Development server usage](/public/playground-select-server.png "Development server usage"){ style="display: block; -margin: 0 auto"} +![Development server usage](/public/playground-select-server.png "Development server usage"){ style="display: block; margin: 0 auto"} The responses of your sample requests are visualized on a small map on the bottom right, but can also be shown as json, table or downloaded as file: -![Example request visualization](/public/playground-map.png "Example request visualization"){ style="display: block; -margin: 0 auto"} +![Example request visualization](/public/playground-map.png "Example request visualization"){ style="display: block; margin: 0 auto"} ::: warning Hint If you prefer the swagger-ui you can also use the [swagger editor](https://editor-next.swagger.io/) and load diff --git a/docs/versions/v7.1.1/Data.md b/docs/versions/v7.1.1/Data.md new file mode 100644 index 0000000000..6b13c44451 --- /dev/null +++ b/docs/versions/v7.1.1/Data.md @@ -0,0 +1,22 @@ +# Data +openrouteservice makes use of public opensource data. To generate the best routes, a number of different datasets are used. + +## Base Data +The base data used for the road network and related information (road type, access restrictions etc.) is [OpenStreetMap](https://openstreetmap.org). This dataset is a free and open dataset that can be edited by anyone. + +## Elevation +The data used for elevation are [SRTM](http://srtm.csi.cgiar.org/) and GMTED. + +## Population +When requesting isochrones, you can also request to get population data for the isochrone areas. The data used for this is the [Global Human Settlement Layer (GHSL)](https://data.jrc.ec.europa.eu/dataset/jrc-ghsl-ghs_pop_gpw4_globe_r2015a) from the European Commission. openrouteservice uses the 2015 data at a resolution of 250m. + +## Borders +Data relating to the avoid borders features is derived from administrative boundaries features in OpenStreetMap. Information about open borders is obtained from [Wikipedia](https://en.wikipedia.org/wiki/Open_border). + +## Green & Quiet +The data used to identify green and quite routes were derived from research +projects in the GIScience research group at Heidelberg University. More +information about these can be found on the GIScience news blog +[here](http://k1z.blog.uni-heidelberg.de/2017/07/03/healthy-routing-prefering-green-areas-added-to-openrouteserviceorg/) +and +[here](http://k1z.blog.uni-heidelberg.de/2017/07/10/reducing-stress-by-avoiding-noise-with-quiet-routing-in-openrouteservice/) diff --git a/docs/versions/v7.1.1/Frequently-Asked-Questions.md b/docs/versions/v7.1.1/Frequently-Asked-Questions.md new file mode 100644 index 0000000000..1081f71834 --- /dev/null +++ b/docs/versions/v7.1.1/Frequently-Asked-Questions.md @@ -0,0 +1,70 @@ +--- +title: FAQ +--- + +# Frequently Asked Questions + +## Why is my ors reporting `Could not find point`? + +This is a frequently encountered error message: +``` +Could not find point 0: 25.3531986 51.5214311 within a radius of 350.0 meters.; +Could not find point 1: 25.3524229 51.4627229 within a radius of 350.0 meters. +``` + +There are three main reasons for this problem, listed in order of most to least common. + +1. If both points are not found you probably just mixed up Lat and Long. Our + API expects coordinates in [lon,lat] order as described in our documentation + (check help button for parameter info). Output is also [lon,lat] as by the + GeoJSON Specification. + +2. The given start and endpoint are further than 350m away from any routable + road. The maximum distance for snapping to road segments in our API is 350m. + This can be customized for local installations via the + `maximum_snapping_radius` and `location_index_resolution` config-parameter. See + [configuration](installation/Configuration) for details. + +3. The start and enpoint are passed with correct lon,lat-order and are within + 350m of a routable road. This should only happen with a local installation. + Usually, this means that ors is trying to route in an area that graphs have not + been built for. + If routes in Heidelberg(Germany) can be found, the ors is still running on the + default dataset. + +--- + +## When does the OSM data update in the openrouteservice? + +The openrouteservice builds its data from the `planet.osm.pbf`-files. According +to [the osm-wiki](https://wiki.openstreetmap.org/wiki/Planet.osm), these files +take two days to build and are updated weekly. + +Since the `planet`-files are rather large (currently over 60GB), there is a bit +of work involved to make sure the download went right and the file is not +corrupted in any way and in fact new. Parts of this process are in the hands of +the OSM, parts are done by the openrouteservice. + +Once the newest `planet`-file is on the openrouteservice-servers, it needs to +be preprocessed before the openrouteservice can start building the graphs used +for routing. + +The build process in itself is [rather +resource-intensive](installation/System-Requirements). It takes roughly two +days for any one of the nine profiles. For the mentioned resource requirements, +this means that it will take roughly a week for all profiles to be re-built. + +Once the graphs are built, the production instances have to load them. Since +this should happen in a low-traffic timeslot, it is also scheduled to happen +once per week. + +To sum up: if you change anything in the OSM, it will therefore take roughly a +week until it's included in the `planet`-file. This gets read once a week, the +build takes a week and reloading graphs happens once a week. + +If everything aligns as it should, changes should be reflected in the +openrouteservice within two to three weeks. + +If, however, anything goes wrong anywhere, this will usually mean a delay of at +least a week, assuming it gets noticed and fixed immediately. It is no sign of +concern, if changes are not reflected within a month. diff --git a/docs/versions/v7.1.1/contributing/Contributing-Translations.md b/docs/versions/v7.1.1/contributing/Contributing-Translations.md new file mode 100644 index 0000000000..5a7c0a2d21 --- /dev/null +++ b/docs/versions/v7.1.1/contributing/Contributing-Translations.md @@ -0,0 +1,50 @@ +# Translations +If you notice any thing wrong with translations, or you want to add a new language to the openrouteservice instructions, please add/edit files in the [`src/main/resources/resources/locales`](https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/locales) folder. You can use the [`ors_en.resources`](https://github.com/GIScience/openrouteservice/openrouteservice/src/main/resources/resources/locales/ors_en-US.resources) file as a template as to what information needs to be present. +As a guide, for each instruction there are two formats - one where there is a named place (i.e. 47 Berlinerstraße) and one without. It is important to keep the `{way_name}` tag in the text, but it should be moved to the correct location. +To show openrouteservice what language is being used, you should alter the name of the file to include the ISO identifier (i.e. for Austrian German the filename would be `ors_de_AT.resources`). + +Since the update to the v2 API, we make use of the Spring framework. Because of that, you also need to make a slight modification to a java file that declares what parameters can be passed through to the API. This file is located in [`openrouteservice/src/main/java/heigit/ors/api/requests/common/APIEnums.java`](https://github.com/GIScience/openrouteservice/blob/master/ors-engine/src/main/java/org/heigit/ors/api/requests/common/APIEnums.java) and the section that needs updating is the `public enum Languages` enum. If (for example) you want to add Polish to the languages, you would also need to add here something like `PL("pl")` to the list where the part in the `("...")` is what would be passed in to the API to select that language. So ultimately you would end up with: +```java +public enum Languages { + public enum Languages { + CS("cs"), + CS_CZ("cs-cz"), + DE("de"), + DE_DE("de-de"), + EN("en"), + EN_US("en-us"), + EO("eo"), + EO_EO("eo-eo"), + ES("es"), + ES_ES("es-es"), + FR("fr"), + FR_FR("fr-fr"), + GR("gr"), + GR_GR("gr-gr"), + HE("he"), + HE_IL("he-il"), + HU("hu"), + HU_HU("hu-hu"), + ID("id"), + ID_ID("id-id"), + IT("it"), + IT_IT("it-it"), + JA("ja"), + JA_JP("ja-jp"), + NE("ne"), + NE_NP("ne-np"), + NL("nl"), + NL_NL("nl-nl"), + PL("pl"), + PL_PL("pl-pl"), + PT("pt"), + PT_PT("pt-pt"), + RO("ro"), + RO_RO("ro-ro"), + RU("ru"), + RU_RU("ru-ru"), + TR("tr"), + TR_TR("tr-tr"), + ZH("zh"), + ZH_CN("zh-cn"); +``` diff --git a/docs/versions/v7.1.1/contributing/Contributing.md b/docs/versions/v7.1.1/contributing/Contributing.md new file mode 100644 index 0000000000..3e16fa19b1 --- /dev/null +++ b/docs/versions/v7.1.1/contributing/Contributing.md @@ -0,0 +1,25 @@ +# Contributing +* [Contributing Code](https://github.com/GIScience/openrouteservice/blob/master/CONTRIBUTE.md) +* [Contributing Translations](Contributing-Translations) +* [Updating OpenStreetMap](https://wiki.openstreetmap.org/wiki/Beginners%27_guide) + +When people contribute to openrouteservice, it makes [the whole +team](https://heigit.org/heigit-team/) do a little happy dance! There are many +ways that you can contribute to make openrouteservice a better routing service. +Whether you are a Java developer who is interested in fixing some bugs or +adding some new functionality, someone who knows an area well and can update +information in OSM so that openrouteservice can take it into account, or even +someone who speaks different languages and is will to provide some translations +for routing instructions, there will be something that you can help with. + +Feel free to create an [issue](https://github.com/GIScience/openrouteservice/issues) +and label it accordingly. If your issue regards the openrouteservice web-app +please use the [corresponding repository](https://github.com/GIScience/ors-maps-client/issues). + +## Guidelines + +We put together a [few +guidelines](https://github.com/GIScience/openrouteservice/blob/master/CONTRIBUTE.md) +to help you in the process and keep the repository clean and tidy. + + diff --git a/docs/versions/v7.1.1/documentation/Documentation.md b/docs/versions/v7.1.1/documentation/Documentation.md new file mode 100644 index 0000000000..a90214d004 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Documentation.md @@ -0,0 +1,4 @@ +# Documentation +For an easy and interactive way to test the api, visit our documentation at [openrouteservice.org](https://openrouteservice.org). +After obtaining your key you can try out the different endpoints instantly and start firing requests. + diff --git a/docs/versions/v7.1.1/documentation/Error-Codes.md b/docs/versions/v7.1.1/documentation/Error-Codes.md new file mode 100644 index 0000000000..cf56266ff5 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Error-Codes.md @@ -0,0 +1,110 @@ +# Error Codes + +## HTTP Status Codes + +The following table describes the supported HTTP status codes. + +| HTTP Status Code | Description | +|:----------------:|--------------------------------------------------------------------------------------------------------------------------------------------| +| 200 | Standard response for successfully processed requests. | +| 400 | The request is incorrect and therefore can not be processed. | +| 404 | The end point is not available, or a given request completed successfully but found no results. | +| 405 | The specified HTTP method is not supported. For more details, refer to the EndPoint documentation. | +| 413 | The request is larger than the server is able to process, the data provided in the request exceeds the capacity limit. | +| 500 | An unexpected error was encountered and more detailed internal error code is provided (see [Internal Error Codes](#internal-error-codes)). | +| 501 | Indicates that the server does not support the functionality needed to fulfill the request. | +| 503 | The server is currently unavailable due to overload or maintenance. | + + + +## Internal Error Codes + +The following sections describes the list of possible internal error codes that might be provided by different ORS +EndPoints. + +### Geocoding API + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 1000 | Unable to parse JSON request. | +| 1001 | Required parameter is missing. | +| 1002 | Invalid parameter format. | +| 1003 | Invalid parameter value. | +| 1004 | Parameter value exceeds the maximum allowed limit. | +| 1006 | Unable to parse the request to the export handler. | +| 1007 | Unsupported export format. | +| 1008 | Empty Element. | +| 1009 | Address not found for location. | +| 1099 | Unknown internal error. | + +### Routing API + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 2000 | Unable to parse JSON request. | +| 2001 | Required parameter is missing. | +| 2002 | Invalid parameter format. | +| 2003 | Invalid parameter value. | +| 2004 | Parameter value exceeds the maximum allowed limit. | +| 2006 | Unable to parse the request to the export handler. | +| 2007 | Unsupported export format. | +| 2008 | Empty Element. | +| 2009 | Route could not be found between locations. | +| 2099 | Unknown internal error. | + +### Isochrones API + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 3000 | Unable to parse JSON request. | +| 3001 | Required parameter is missing. | +| 3002 | Invalid parameter format. | +| 3003 | Invalid parameter value. | +| 3004 | Parameter value exceeds the maximum allowed limit. | +| 3005 | Requested feature is not supported. | +| 3006 | Unable to parse the request to the export handler. | +| 3007 | Unsupported export format. | +| 3008 | Empty Element. | +| 3099 | Unknown internal error. | + +### POIs API + +| Error Code | Description | +|:----------:|-----------------------------------------------------| +| 4000 | Invalid JSON object in request. | +| 4001 | Category or category group ids missing. | +| 4002 | Geometry is missing. | +| 4003 | Bounding box and or geojson not present in request. | +| 4004 | Buffer is missing. | +| 4005 | Geometry length does not meet the restrictions. | +| 4006 | Unsupported HTTP method. | +| 4007 | GeoJSON parsing error. | +| 4008 | Geometry size does not meet the restrictions. | +| 4099 | Unknown internal error. | + +### Matrix API + +| Error Code | Description | +|:----------:|-----------------------------------------------------| +| 6000 | Unable to parse JSON request. | +| 6001 | Required parameter is missing. | +| 6002 | Invalid parameter format. | +| 6003 | Invalid parameter value. | +| 6004 | Parameter value exceeds the maximum allowed limit. | +| 6006 | Unable to parse the request to the export handler. | +| 6007 | Unsupported export format. | +| 6008 | Empty Element. | +| 6099 | Unknown internal error. | + +### Centrality API + +| Error Code | Description | +|:----------:|--------------------------------| +| 7000 | Unable to parse JSON request. | +| 7001 | Required parameter is missing. | +| 7002 | Invalid parameter format. | +| 7003 | Invalid parameter value. | +| 7004 | Unknown parameter. | +| 7005 | Mismatched input. | +| 7006 | Unsupported export format. | +| 7099 | Unknown internal error. | diff --git a/docs/versions/v7.1.1/documentation/Geocoding-Response.md b/docs/versions/v7.1.1/documentation/Geocoding-Response.md new file mode 100644 index 0000000000..8804a69bef --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Geocoding-Response.md @@ -0,0 +1,22 @@ +# Geocoding Response + +Explanation of returned parameters + +## Place type + +Describes the returned location type + + | Value | Description | + |:---------------:|:------------------------------------------------------------------------------------------------| + | `venue` | Points of interest, businesses, things with walls | + | `address` | Places with a street address | + | `street` | Streets, roads, highways | + | `neighbourhood` | Social communities, neighbourhoods | + | `borough` | Local administrative boundary, currently only used for New York City | + | `localadmin` | Local administrative boundaries | + | `locality` | Towns, hamlets, cities | + | `county` | Official governmental area; usually bigger than a locality, almost always smaller than a region | + | `macrocounty` | Related group of counties. Mostly in Europe | + | `region` | States and provinces | + | `macroregion` | Related group of regions. Mostly in Europe | + | `country` | Places that issue passports, nations, nation-states | diff --git a/docs/versions/v7.1.1/documentation/Geometry-Decoding.md b/docs/versions/v7.1.1/documentation/Geometry-Decoding.md new file mode 100644 index 0000000000..bafdb5df8d --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Geometry-Decoding.md @@ -0,0 +1,202 @@ +# Geometry Decoding + +When a response includes a geometry the data might be encoded as single string. This is a so-called [encoded polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). +If no additional elevation data is requested, this can be decoded with a standard polyline decoder, available e.g. from Mapbox or others. + +When you request additional elevation data, this encoded string can not be decoded with a standard polyline decoder. +The reason for that is, that the elevation data is included in the polyline in addition to the latitude and longitude values. +To decode _X,Y_ and _X,Y,Z_ polylines the decoder needs to know whether the geometry has elevation information. +Examples on how to decode _X,Y,Z_ polylines can be found below: + +## Java + +```java +import org.json.JSONArray; + +public class GeometryDecoder { + + private static JSONArray decodeGeometry(String encodedGeometry, boolean inclElevation) { + JSONArray geometry = new JSONArray(); + int len = encodedGeometry.length(); + int index = 0; + int lat = 0; + int lng = 0; + int ele = 0; + + while (index < len) { + int result = 1; + int shift = 0; + int b; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + lat += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + + result = 1; + shift = 0; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + lng += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + + + if(inclElevation){ + result = 1; + shift = 0; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + ele += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + } + + JSONArray location = new JSONArray(); + try { + location.put(lat / 1E5); + location.put(lng / 1E5); + if(inclElevation){ + location.put((float) (ele / 100)); + } + geometry.put(location); + } catch (JSONException e) { + e.printStackTrace(); + } + } + return geometry; + } +} +``` + +## JavaScript + +```js + /** + * Decode an x,y or x,y,z encoded polyline + * @param {*} encodedPolyline + * @param {Boolean} includeElevation - true for x,y,z polyline + * @returns {Array} of coordinates + */ + decodePolyline: (encodedPolyline, includeElevation) => { + // array that holds the points + let points = [] + let index = 0 + const len = encodedPolyline.length + let lat = 0 + let lng = 0 + let ele = 0 + while (index < len) { + let b + let shift = 0 + let result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 // finds ascii + // and subtract it by 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + + lat += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + shift = 0 + result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + lng += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + + if (includeElevation) { + shift = 0 + result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + ele += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + } + try { + let location = [(lat / 1E5), (lng / 1E5)] + if (includeElevation) location.push((ele / 100)) + points.push(location) + } catch (e) { + console.log(e) + } + } + return points + } +``` + +## Python + +```python +def decode_polyline(polyline, is3d=False): + """Decodes a Polyline string into a GeoJSON geometry. + :param polyline: An encoded polyline, only the geometry. + :type polyline: string + :param is3d: Specifies if geometry contains Z component. + :type is3d: boolean + :returns: GeoJSON Linestring geometry + :rtype: dict + """ + points = [] + index = lat = lng = z = 0 + + while index < len(polyline): + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + lat += (~result >> 1) if (result & 1) != 0 else (result >> 1) + + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + lng += ~(result >> 1) if (result & 1) != 0 else (result >> 1) + + if is3d: + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + if (result & 1) != 0: + z += ~(result >> 1) + else: + z += result >> 1 + + points.append( + [ + round(lng * 1e-5, 6), + round(lat * 1e-5, 6), + round(z * 1e-2, 1), + ] + ) + + else: + points.append([round(lng * 1e-5, 6), round(lat * 1e-5, 6)]) + + geojson = {u"type": u"LineString", u"coordinates": points} + + return geojson +``` diff --git a/docs/versions/v7.1.1/documentation/Instruction-Types.md b/docs/versions/v7.1.1/documentation/Instruction-Types.md new file mode 100644 index 0000000000..cc125e7fbb --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Instruction-Types.md @@ -0,0 +1,19 @@ +# Instruction Types +The following table contains the encoding of the instruction types present in the `type`-field in a step of a segment of a route. + +| Value | Encoding | +|:-----:|:----------------:| +| 0 | Left | +| 1 | Right | +| 2 | Sharp left | +| 3 | Sharp right | +| 4 | Slight left | +| 5 | Slight right | +| 6 | Straight | +| 7 | Enter roundabout | +| 8 | Exit roundabout | +| 9 | U-turn | +| 10 | Goal | +| 11 | Depart | +| 12 | Keep left | +| 13 | Keep right | diff --git a/docs/versions/v7.1.1/documentation/Matrix-Response.md b/docs/versions/v7.1.1/documentation/Matrix-Response.md new file mode 100644 index 0000000000..df2c34814e --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Matrix-Response.md @@ -0,0 +1,13 @@ +# Matrix Response + +The Matrix Response contains one matrix for each specified `metrics` value. +In this matrix the items(rows) correspond to the number of `sources` and the entries(columns) of each item correspond to the number of `destinations`. + +Here is a simple example for `sources=2,3` and `destinations=all` with 4 `locations`: + + | Location | L0 | L1 | L2 | L3 | + |:--------:|:--------:|:--------:|:--------:|:--------:| + | L2 | L2 -> L0 | L2 -> L1 | 0 | L2 -> L3 | + | L3 | L3 -> L0 | L3 -> L1 | L3 -> L2 | 0 | + +The result is `null` if a value can't be determined. diff --git a/docs/versions/v7.1.1/documentation/Places-Request-and-Response.md b/docs/versions/v7.1.1/documentation/Places-Request-and-Response.md new file mode 100644 index 0000000000..ba32c23075 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Places-Request-and-Response.md @@ -0,0 +1,265 @@ +# Places Request and Response + +The following tables contain the related names for the ``category_group_ids`` and the subordinate ``category_ids``. + +## category_group_ids + +Category groups + +| Name | Value | +|:------------------------------------------------------------:|:-----:| +| [accommodation](#accommodation--100) | 100 | +| [animals](#animals--120) | 120 | +| [arts_and_culture](#arts_and_culture--130) | 130 | +| [education](#education--150) | 150 | +| [facilities](#facilities--160) | 160 | +| [financial](#financial--190) | 190 | +| [healthcare](#healthcare--200) | 200 | +| [historic](#historic--220) | 220 | +| [leisure_and_entertainment](#leisure_and_entertainment--260) | 260 | +| [natural](#natural--330) | 330 | +| [public_places](#public_places--360) | 360 | +| [service](#service--390) | 390 | +| [shops](#shops--420) | 420 | +| [sustenance](#sustenance--560) | 560 | +| [transport](#transport--580) | 580 | +| [tourism](#tourism--620) | 620 | + +## category_ids + +Categories listed by group + +### accommodation : 100 + +| Name | Value | +|:--------------:|:-----:| +| alpine_hut | 101 | +| apartment | 102 | +| camp_site | 103 | +| caravan_site | 104 | +| chalet | 105 | +| guest_house | 106 | +| hostel | 107 | +| hotel | 108 | +| motel | 109 | +| wilderness_hut | 110 | + +### animals : 120 + +| Name | Value | +|:---------------:|:-----:| +| animal_boarding | 121 | +| animal_shelter | 122 | +| veterinary | 123 | +| pet | 124 | + +### arts_and_culture : 130 + +| Name | Value | +|:----------------:|:-----:| +| arts_centre | 131 | +| gallery | 132 | +| library | 133 | +| museum | 134 | +| place_of_worship | 135 | +| studio | 136 | + +### education : 150 + +| Name | Value | +|:--------------:|:-----:| +| college | 151 | +| driving_school | 152 | +| kindergarten | 153 | +| language_school| 154 | +| music_school | 155 | +| school | 156 | +| university | 157 | + +### facilities : 160 + +| Name | Value | | Name | Value | +|:-----------------:|:-----:|---|-----------------------|-------| +| compressed_air | 161 | | recycling | 172 | +| bench | 162 | | recycling_station | 173 | +| emergency_phone | 163 | | sanitary_dump_station | 174 | +| clock | 164 | | shelter | 175 | +| defibrillator | 165 | | shower | 176 | +| drinking_water | 166 | | table | 177 | +| fire_hydrant | 167 | | telephone | 178 | +| hunting_stand | 168 | | toilets | 179 | +| internet_cafe | 169 | | waste_basket | 180 | +| kneipp_water_cure | 170 | | waste_disposal | 181 | +| post_box | 171 | | water_point | 182 | + +### financial : 190 + +| Name | Value | +|:----------------:|:-----:| +| atm | 191 | +| bank | 192 | +| bureau_de_change | 193 | + +### healthcare : 200 + +| Name | Value | +|:----------------------:|:-----:| +| baby_hatch | 201 | +| clinic | 202 | +| dentist | 203 | +| doctors | 204 | +| emergency_access_point | 205 | +| hospital | 206 | +| nursing_home | 207 | +| pharmacy | 208 | +| retirement_home | 209 | +| social_facility | 210 | +| blood_donation | 211 | + +### historic : 220 + +| Name | Value | | Name | Value | | Name | Value | +|:-------------------:|:-----:|---|----------------|-------|---|-------------------|-------| +| aircraft | 221 | | farm | 231 | | optical_telegraph | 241 | +| aqueduct | 222 | | fort | 232 | | pillory | 242 | +| archaeological_site | 223 | | gallows | 233 | | ruins | 243 | +| castle | 224 | | highwater_mark | 234 | | rune_stone | 244 | +| cannon | 225 | | locomotive | 235 | | ship | 245 | +| city_gate | 226 | | manor | 236 | | tomb | 246 | +| citywalls | 227 | | memorial | 237 | | wayside_cross | 247 | +| battlefield | 228 | | milestone | 238 | | wayside_shrine | 248 | +| boundary_stone | 229 | | monastery | 239 | | wreck | 249 | +| building | 230 | | monument | 240 | | | | + +### leisure_and_entertainment : 260 + +| Name | Value | | Name | Value | | Name | Value | | Name | Value | | Name | Value | +|:-------------------:|:-----:|---|----------------|-------|---|---------------|-------|---|---------------|-------|---|---------------|-------| +| adult_gaming_centre | 261 | | fitness_centre | 271 | | picnic_table | 281 | | swimming_area | 291 | | dojo | 301 | +| amusement_arcade | 262 | | garden | 272 | | pitch | 282 | | swimming_pool | 292 | | gambling | 302 | +| beach_resort | 263 | | golf_course | 273 | | playground | 283 | | track | 293 | | nightclub | 303 | +| bandstand | 264 | | hackerspace | 274 | | raceway | 284 | | turkish_bath | 294 | | planetarium | 304 | +| bird_hide | 265 | | horse_riding | 275 | | public_bath | 285 | | water_park | 295 | | social_centre | 305 | +| common | 266 | | ice_ring | 276 | | sauna | 286 | | wildlife_hide | 296 | | spa | 306 | +| dance | 267 | | marina | 277 | | slipway | 287 | | brothel | 297 | | stripclub | 307 | +| dog_park | 268 | | miniature_golf | 278 | | sports_centre | 288 | | casino | 298 | | aquarium | 308 | +| firepit | 269 | | nature_reserve | 279 | | stadium | 289 | | cinema | 299 | | theme_park | 309 | +| fishing | 270 | | park | 280 | | summer_camp | 290 | | dive_centre | 300 | | zoo | 310 | + +### natural : 330 + +| Name | Value | +|:-------------:|:-----:| +| cave_entrance | 331 | +| beach | 332 | +| geyser | 333 | +| hill | 334 | +| peak | 335 | +| rock | 336 | +| saddle | 337 | +| spring | 338 | +| volcano | 339 | +| water | 340 | + +### public_places : 360 + +| Name | Value | +|:----------------:|:-----:| +| embassy | 361 | +| crematorium | 362 | +| community_centre | 363 | +| courthouse | 364 | +| coworking_space | 365 | +| crypt | 366 | +| fire_station | 367 | +| grave_yard | 368 | +| police | 369 | +| post_office | 370 | +| prison | 371 | +| ranger_station | 372 | +| rescue_station | 373 | +| townhall | 374 | + +### service : 390 + +| Name | Value | +|:------------:|:-----:| +| beauty | 391 | +| estate_agent | 392 | +| dry_cleaning | 393 | +| glaziery | 394 | +| hairdresser | 395 | +| laundry | 396 | +| massage | 397 | +| photo_booth | 398 | +| tailor | 399 | +| tattoo | 400 | + +### shops : 420 + +| Name | Value | Name | Value | Name | Value | Name | Value | Name | Value | Name | Value | +|:-----------------:|:-----:|------------------|-------|---------------------|-------|-----------------------|-------|---------------|-------|-----------------|-------| +| agrarian | 421 | curtain | 441 | e-cigarette | 461 | hifi | 481 | optician | 502 | tiles | 522 | +| alcohol | 422 | cheese | 442 | farm | 462 | houseware | 482 | organic | 503 | tobacco | 523 | +| antiques | 423 | chemist | 443 | fashion | 463 | hunting | 483 | outdoor | 504 | toys | 524 | +| art | 424 | chocolate | 444 | fishing | 464 | jewelry | 485 | paint | 505 | trophy | 525 | +| bag | 425 | clock | 445 | florist | 465 | leather | 486 | pastry | 506 | tyres | 526 | +| bakery | 426 | clocks | 446 | funeral_directors | 466 | locksmith | 487 | perfumery | 507 | variety_store | 527 | +| bed | 427 | clothes | 447 | furniture | 467 | kiosk | 488 | photo | 508 | vending_machine | 528 | +| beverages | 428 | coffee | 448 | games | 468 | kitchen | 489 | pyrotechnics | 509 | video | 529 | +| bicycle | 429 | computer | 449 | garden_centre | 469 | lamps | 490 | radiotechnics | 510 | video_games | 530 | +| books | 430 | confectionery | 450 | garden_furniture | 470 | lottery | 491 | seafood | 511 | watches | 531 | +| boutique | 431 | convenience | 451 | gas | 471 | mall | 492 | second_hand | 512 | weapons | 532 | +| brewing_supplies | 432 | copyshop | 452 | general | 472 | marketplace | 493 | security | 513 | wine | 533 | +| business_machines | 433 | cosmetics | 453 | gift | 473 | medical_supply | 494 | shoes | 514 | | | +| butcher | 434 | dairy | 454 | greengrocer | 474 | mobile_phone | 495 | spices | 515 | | | +| cafe | 435 | deli | 455 | grocery | 475 | model | 496 | sports | 516 | | | +| camera | 436 | department_store | 456 | interior_decoration | 476 | motorcycle | 497 | stationery | 517 | | | +| candles | 437 | doityourself | 457 | hairdresser_supply | 477 | music | 498 | supermarket | 518 | | | +| car | 438 | electrical | 458 | hardware | 478 | musical_instrument | 499 | swimming_pool | 519 | | | +| car_parts | 439 | electronics | 459 | hearing_aids | 479 | nutrition_supplements | 500 | tea | 520 | | | +| carpet | 440 | erotic | 460 | herbalist | 480 | newsagent | 501 | ticket | 521 | | | + +### sustenance : 560 + +| Name | Value | +|:--------------:|:-----:| +| bar | 561 | +| bbq | 562 | +| biergarten | 563 | +| caf? | 564 | +| drinking_water | 565 | +| fast_food | 566 | +| food_court | 567 | +| ice_cream | 568 | +| pub | 569 | +| restaurant | 570 | + +### transport : 580 + +| Name | Value | | Name | Value | | Name | Value | +|:----------------------:|:-----:|---|--------------------|-------|---|------------------|-------| +| aerodrome | 581 | | car_sharing | 591 | | parking | 601 | +| aeroport | 582 | | car_wash | 592 | | parking_entrance | 602 | +| bicycle_parking | 583 | | charging_station | 593 | | parking_space | 603 | +| bicycle_rental | 584 | | ev_charging | 594 | | station | 604 | +| bicycle_repair_station | 585 | | ferry_terminal | 595 | | tram_stop | 605 | +| boat_sharing | 586 | | fuel | 596 | | taxi | 606 | +| bus_station | 587 | | halt | 597 | | platform | 607 | +| bus_stop | 588 | | helipad | 598 | | stop_position | 608 | +| car_rental | 589 | | heliport | 599 | | stop_area | 609 | +| car_repair | 590 | | motorcycle_parking | 600 | | station | 610 | + +Note, that `station` appears once as a railway station (604) and once as a general public transport station (610). + +### tourism : 620 + +| Name | Value | +|:-------------:|:-----:| +| artwork | 621 | +| attraction | 622 | +| fountain | 623 | +| information | 624 | +| picnic_site | 625 | +| travel_agency | 626 | +| viewpoint | 627 | diff --git a/docs/versions/v7.1.1/documentation/Route-Attributes.md b/docs/versions/v7.1.1/documentation/Route-Attributes.md new file mode 100644 index 0000000000..f615a355d0 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Route-Attributes.md @@ -0,0 +1,18 @@ +# Route Attributes + +Route attributes can be used to attribute every segment of a route with possibly three values: + +## AvgSpeed + +This value is in _km/h_ and equals the average speed for this way segment after grading and applying factors. + +## Detourfactor + +This value is a _factor_ and gives the relative length of the segment with +regard to the length of the beeline between the start and end point of the +route segment. + +## Percentage + +This value is in _percent_ and gives the segment length in terms of the route +length. diff --git a/docs/versions/v7.1.1/documentation/Structured-Geocoding-Query.md b/docs/versions/v7.1.1/documentation/Structured-Geocoding-Query.md new file mode 100644 index 0000000000..f7576f803e --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Structured-Geocoding-Query.md @@ -0,0 +1,30 @@ +# Structured Geocoding Query + +A structured geocoding request is more precise than a normal one. It is also very useful for querying locations from tables. +For a structured request insert a JSON Object with at least on of the following parameters into the query parameter of the geocoding request: + + | Parameter | Description | + |:-------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | address | Can contain a full address with house number or only a street name | + | neighbourhood | Vernacular geographic entities that may not necessarily be official administrative divisions but are important nonetheless | + | borough | Mostly known in the context of New York City, even though they may exist in other cities, such as Mexico City | + | locality | Name of a City | + | county | Administrative division between localities and regions | + | region | Normally the first-level administrative divisions within countries, analogous to states and provinces in the United States and Canada, respectively, though most other countries contain regions as well | + | postalcode | A postalcode | + | country | Name of a country. Supports two- and three-letter abbreviations | + +## Example + +```json +{ + "address": "Berliner Straße 45", + "locality": "Heidelberg", + "country": "Germany", + "postalcode": "69120" +} +``` + +## Uglyfied and encoded: + +`%7B"address": "Berliner Straße 45","locality": "Heidelberg","country": "Germany","postalcode": "69120"%7D` diff --git a/docs/versions/v7.1.1/documentation/Switching-from-V1-API-to-V2.md b/docs/versions/v7.1.1/documentation/Switching-from-V1-API-to-V2.md new file mode 100644 index 0000000000..943a6c2591 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Switching-from-V1-API-to-V2.md @@ -0,0 +1,101 @@ +# Moving from V1 API to V2 + +Soon (30th October, 2020), the V1 openrouteservice API will be getting switched off, so before then it is important that you update your queries to reflect this change. The V2 API offers some great benefits over the V1 API including: +* **All request information is sent in the request body rather than needing to be encoded in the URL. This makes writing and debugging of queries far easier!** +* **The URL is structured in a way that makes it easier to request different response data types and see what profile you are querying** + +So how do you switch from V1 to V2 API? The biggest difference is that the main request information needs to go in the body of the request, and the request made as a POST method. The body itself is a nice JSON format, and makes use of true arrays rather than the piped (|) list in the V1 GET method. Also, the URL itself has been modified to be the format of: +`https://api.openrouteservice.org/v2/{endpoint}/{profile}` +where `{endpoint}` is one of `directions`, `isochrones`, or `matrix`, and `{profile}` is the profile you want to get the route for. In addition, the `directions` endpoint can also have the response data format added after the profile, for example `https://api.openrouteservice.org/v2/directions/driving-car/{response-format}` where `{response-format}` is one of `json`, `geojson`, or `gpx`. + +**Please note that it is only the `directions`, `isochrones`, and `matrix` endpoints that use the V2 API. All other endpoints (e.g. geocoding) remain the same as before!** + +So that's the basic changes, so now lets give some examples of how to change the requests. + +## Directions + +Let's start with a basic directions request for the car profile, where you have a start, end, and via point, you want to avoid highways, and you want to avoid France. In the V1 API, your request would be: + +`https://api.openrouteservice.org/directions?api_key=xxx&coordinates=8.684692,49.40025|7.849731,48.046874|7.36084,49.231947&profile=driving-car&options={"avoid_features":"highways","avoid_countries":"70|193"}&geometry_format=geojson` + +or in it's encoded form + +`https://api.openrouteservice.org/directions?api_key=xxx&coordinates=8.684692,49.40025%7C7.849731,48.046874%7C7.36084,49.231947&profile=driving-car&options=%7B%22avoid_features%22:%22highways%22,%22%22avoid_countries%22%3A%2270%7C193%22%7D&geometry_format=geojson` + +Using the V2 API, the same request would be as follows: + +`https://api.openrouteservice.org/v2/directions/driving-car/geojson?api_key=xxx` + +with the POST body being: + +```json +{ + "coordinates": [ + [8.684692,49.40025], + [7.849731,48.046874], + [7.36084,49.231947] + ], + "options": { + "avoid_countries": ["FRA","CHE"], + "avoid_features": ["highways"] + } +} +``` + +As you can see, that is much easier to read! + +## Isochrones + +For the Isochrones endpoint, to request pedestrian isochrones for 2 locations up to 60 minutes duration with equal intervals at 10 minutes, in V1 API you would send the following request: + +`https://api.openrouteservice.org/isochrones?api_key=5b3ce3597851110001cf62480fd03f0ff4c14a33a72cc528290f2823&profile=foot-walking&locations=40.38939,%2056.148562&range=3600&range_type=time&interval=600` + +In V2 API, it would be done as follows (again as a POST): + +`https://api.openrouteservice.org/v2/isochrones/foot-walking?api_key=xxx` + +with the following body: + +```json +{ + "locations": [ + [8.681495,49.41461], + [8.686507,49.41943] + ], + "range": [3600], + "interval": 360, + "range_type": "time" +} +``` + +## Matrix + +Finally, for a HGV Matrix request using 4 locations, where the last 2 in the list are the destinations, returning distance and duration, and the distances being in kilometres, in V1 you would request: + +`https://api.openrouteservice.org/matrix?api_key=xxx&profile=driving-hgv&locations=9.970093,48.477473|9.207916,49.153868|37.573242,55.801281|115.663757,38.106467&destinations=2,3&metrics=distance|duration&units=km` + +or in its encoded form: + +`https://api.openrouteservice.org/matrix?api_key=xxx&profile=driving-hgv&locations=9.970093,48.477473%7C9.207916,49.153868%7C37.573242,55.801281%7C115.663757,38.106467&destinations=2,3&metrics=distance%7Cduration&units=km` + +For the same request in V2, you would use the following POST request: + +`https://api.openrouteservice.org/v2/matrix/driving-hgv?api_key=xxx` + +```json +{ + "locations": [ + [9.70093,48.477473], + [9.207916,49.153868], + [37.573242,55.801281], + [115.663757,38.106467] + ], + "destinations": [2,3], + "metrics": ["distance","duration"], + "units": "km" +} +``` + +So that's basically how to convert your V1 API requests into V2 API requests. As you can see, things are a lot easier to read in the newer API, and there are some additional functionalities which are not available in the V1 API. + +You can get a better understanding of the different requests and how to build them in our [interactive documentation](https://openrouteservice.org/dev/#/api-docs/). diff --git a/docs/versions/v7.1.1/documentation/Tag-Filtering.md b/docs/versions/v7.1.1/documentation/Tag-Filtering.md new file mode 100644 index 0000000000..6517c36398 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/Tag-Filtering.md @@ -0,0 +1,143 @@ +# Tag Filtering +During the graph build process, openrouteservice looks at various tags that are given to OSM ways as a means of identifying whether that way should be included into the routing graph or not. For example, in the foot profile any ways that are marked as `highway=motorway` are rejected and not included in the graph, meaning that they can never be routed over (for that profile). + +The following tables list what tags are taken into account during the initial filtering process. `Reject` means that the tag value indicates that the way is explicitly rejected form the graph building, `Accept` means that the tag indicates that the way should be included, and `Conditional` means that the tag is taken into account during the filtering process, but the acceptance/rejection is based on other tags and logic. + +**All ways are initially rejected from the graph building unless criteria for acceptance has been met!** + +**The order of items is important, as in many cases a more generic "catch" is introduced towards the end of processing if it has not already been explicitly rejected/accepted.** + +Notation: +_italic words_ are variables defined for the respective section and group several tags. +`monospace code` are tags from openstreetmap. +`[square brackets]` denote a range of possible tags. +`*` denotes any tag, `key != *` denotes the absence of `key`. + + +## Driving car :car: + +Definitions: +_restrictedValues_ = `[private, agricultural, forestry, no, restricted, delivery, military, emergency]` +_intendedValues_ = `[yes, permissive, destination]` +_restrictions_ = `[motorcar, motor_vehicle, vehicle, access]` +_firstValue_ = value of the first encountered key from _restrictions_ + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `highway != *` AND `route != [shuttle_train, ferry]` | :heavy_check_mark: | | | +| `highway != *` AND `route = [shuttle_train, ferry]` AND _firstValue_ = _restrictedValues_ | :heavy_check_mark: | | | +| `highway != *` AND `route = [shuttle_train, ferry]` AND ( _firstValue_ = _intendedValues_ OR _firstValue_ != `*` AND `foot != *` AND `bicycle != *` ) | | :heavy_check_mark: | | +| `highway = track` AND `tracktype = *` | | | :heavy_check_mark: | +| `highway != [motorway, motorway_link, motorroad, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, unclassified, residential, living_street, service, road, track]` | :heavy_check_mark: | | | +| `impassable = yes` OR `[status, smoothness] = impassable` | :heavy_check_mark: | | | +| _firstValue_ = _restrictedValues_ | :heavy_check_mark: | | | +| _firstValue_ = _intendedValues_ | | :heavy_check_mark: | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| `maxwidth < 2` | :heavy_check_mark: | | | + +## Driving HGV :truck: :bus: 🚜 + +The profile differs from the above logic for driving car in the definitions of + +_restrictedValues_ = `[private, no, restricted, military]` +_intendedValues_ = `[yes, permissive, designated, destination, hgv, goods, bus, agricultural, forestry, delivery]` + +and the following addition rule: + + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| _restrictions_=_restrictedValues_ AND !(_restrictions_=_intendedValues_) AND !([hgv, goods, bus, agricultural, forestry, delivery]=_intendedValues_) | :heavy_check_mark: | | | + +## cycling-regular :bike: [cycling-electric, cycling-road & cycling-mountain] + +Definitions: +_restrictions_ = `[bicycle, vehicle, access]` +_restrictedValues_ = `[private, no, restricted, military, emergency]` +_intendedValues_ = `[yes, designated, official, permissive]` + +| Tag combination | Reject | Accept | Conditional | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| (`man_made = pier` OR `railway = platform` OR ( `route = [shuttle_train, ferry]` AND (`bicycle = yes` OR ( `bicycle != *` AND `foot != *`)))) AND !(_restrictions_ = _restrictedValues_) | | :heavy_check_mark: | | +| `highway != [cycleway, path, footway, pedestrian, track, service, residential, living_street, steps, unclassified, road, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link]` | :heavy_check_mark: | | | +| `sac_scale = hiking` AND `highway = cycleway` | | :heavy_check_mark: | | +| _cycling-regular, cycling-electric:_
`sac_scale != hiking`

_cycling-road:_
`sac_scale = *`

_cycling-mountain:_
`sac_scale != [hiking, mountain_hiking, demanding_mountain_hiking, alpine_hiking]`
| :heavy_check_mark: | | | +| `bicycle = `_intendedValues_ OR `bicycle = dismount` OR `highway = cycleway` OR `bicycle_road = yes` | | :heavy_check_mark: | | +| `highway = [motorway, motorway_link]` OR `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| _restrictions_ = _restrictedValues_ | :heavy_check_mark: | | | +| ELSE `* = *` | | :heavy_check_mark: | | + + +## Foot + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `sac_scale != hiking` | :heavy_check_mark: | | | +| `foot = [yes, designated, official, permissive]` | | :heavy_check_mark: | | +| `foot = [private, no, restricted, military, emergency]` | | | :heavy_check_mark: | +| `access = [private, no, restricted, military, emergency]` | | | :heavy_check_mark: | +| `sidewalk = [yes, both, left, right]` | | :heavy_check_mark: | | +| `highway != [footway, path, steps, pedestrian, living_street, track, residential, service, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, cycleway, unclassified, road]` | :heavy_check_mark: | | | +| `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | + +The following are applicable only when no highway tag has been provided for the way + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `route = [shuttle_train, ferry]` AND (`foot != *` OR `foot = yes`) | | :heavy_check_mark: | | +| `railway = platform` | | :heavy_check_mark: | | +| `man_made = pier` | | :heavy_check_mark: | | + +## Hiking + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `sac_scale != [hiking, mountain_hiking, demanding_mountain_hiking, alpine_hiking]` | :heavy_check_mark: | | | +| `foot = [yes, designated, official, permissive]` | | :heavy_check_mark: | | +| `foot = [private, no, restricted, military, emergency]` | | | :heavy_check_mark: | +| `access = [private, no, restricted, military, emergency]` | | | :heavy_check_mark: | +| `sidewalk = [yes, both, left, right]` | | :heavy_check_mark: | | +| `highway != [footway, path, steps, pedestrian, living_street, track, residential, service, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, cycleway, unclassified, road]` | :heavy_check_mark: | | | +| `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | + +The following are applicable only when no highway tag has been provided for the way + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `route = [shuttle_train, ferry]` AND (`foot != *` OR `foot = yes`) | | :heavy_check_mark: | | +| `railway = platform` | | :heavy_check_mark: | | +| `man_made = pier` | | :heavy_check_mark: | | + +## Wheelchair + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `motorroad = yes` | :heavy_check_mark: | | | +| `wheelchair = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| `wheelchair = [private, no, restricted]` | :heavy_check_mark: | | | +| `highway = steps` | :heavy_check_mark: | | | +| `foot = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| `foot = [private, no, restricted]` | :heavy_check_mark: | | | +| `sac_scale = *` | :heavy_check_mark: | | | +| `sidewalk = [yes, both, left, right]` | | :heavy_check_mark: | +| `sidewalk = [no, none, separate, detached]` AND `highway = [trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, road]` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| (`bicycle = [designated, official]` OR `horse = [designated, official]`) AND `[foot, access, wheelchair] = [yes, designated, official, permissive, limited]` | :heavy_check_mark: | | | +| `highway = [bridleway, cycleway]` | | | :heavy_check_mark: | +| `highway = [footway, pedestrian, living_street, residential, unclassified, service, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, road path, track]` | | :heavy_check_mark: | | + +The following are applicable only when no highway tag has been provided for the way + +| Tag combination | Reject | Accept | Conditional | +| --------------- |:------:|:------:|:-----------:| +| `route = [shuttle_train, ferry]` AND `wheelchair = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| `route = [shuttle_train, ferry]` AND `wheelchair = [private, no, restricted]` | :heavy_check_mark: | | | +| `route = [shuttle_train, ferry]` AND `foot = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| `route = [shuttle_train, ferry]` AND `foot = [private, no, restricted]` | :heavy_check_mark: | | | +| (`public_transport = platform` OR `railway = platform`) AND `wheelchair = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| (`public_transport = platform` OR `railway = platform`) AND `wheelchair = [private, no, restricted]` | :heavy_check_mark: | | | +| (`public_transport = platform` OR `railway = platform`) AND `foot = [yes, designated, official, permissive, limited]` | | :heavy_check_mark: | | +| (`public_transport = platform` OR `railway = platform`) AND `foot = [private, no, restricted]` | :heavy_check_mark: | | | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Extra-Info.md b/docs/versions/v7.1.1/documentation/extra-info/Extra-Info.md new file mode 100644 index 0000000000..f04caed8a7 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Extra-Info.md @@ -0,0 +1,31 @@ +# Extra Info + +When requesting routes, there are a number of "extra info" items that can be requested to give you more information about the route. This info could be things like the road surface, track type, or OpenStreetMap way ID. The list below details which extra info items are available for each profile **in the routing provided by https://api.openrouteservice.org**. + +| Parameter | Description | Code Information | +|:---------:|:------------|:-----------------| +| steepness | Provides information about how steep parts of the route are | [Steepness IDs](Steepness) +| suitability | How suitable the way is based on characteristics of the route and the profile | 1 (unsuitable) - 10 (very suitable) +| surface | The surface covering along the route | [Surface IDs](Surface) +| waycategory | Specific categories of parts of the route (tollways, highways, fords etc.) | [Category IDs](Waycategory) +| waytype | Types of roads and paths that are used in the route | [Type IDs](Waytype) +| tollways | Any tollways that the route crosses. Whether a way is marked as [tollway](https://wiki.openstreetmap.org/wiki/Key:toll) depends on `profile` | 0 (no tollway) or 1 (tollway) | +| traildifficulty | The difficulty of parts of the way based on sac or mountainbike scales | [Difficulty IDs](Trail-Difficulty) | +| osmid | The OpenStreetMap way IDs of the ways the route uses | | +| roadaccessrestrictions | Information about ways that may have access restrictions (e.g. private roads, destination only) | [Restrictions IDs](Road-Access-Restrictions) | +| countryinfo | Which country parts of the way lies in | [Country IDs](../routing-options/Country-List) +| green | How "green" the parts of the route are (influenced by things like number of trees, parks, rivers etc.) | 0 (minimal greenspace) - 10 (a lot of green space) | +| noise | How noisy the parts of the route are (influenced by things like proximity to highways) | 0 (quiet) - 10 (noisy) | + +# Extra Info Availability + +| | steepness | suitability | surface | waycategory | waytype | tollways | traildifficulty | osmid | roadaccessrestrictions | countryinfo | green | noise | +|:-----------:|:----------------:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| +| driving-car | x | x | x | x | x | x | x | | x | x | | | +| driving-hgv | x | x | x | x | x | x | x | | x | x | | | +| cycling-regular | x | x | x | x | x | | x | | | | | | +| cycling-mountain | x | x | x | x | x | | x | | | | | | +| cycling-road | x | x | x | x | x | | x | | | | | | +| foot-walking | x | x | x | x | x | | x | | | | x | x | +| foot-hiking | x | x | x | x | x | | x | | | | x | x | +| wheelchair | x | x | x | x | x | | x | x | | | | | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Road-Access-Restrictions.md b/docs/versions/v7.1.1/documentation/extra-info/Road-Access-Restrictions.md new file mode 100644 index 0000000000..52088c37aa --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Road-Access-Restrictions.md @@ -0,0 +1,14 @@ +# Road Access Restrictions + +Provides information about possible restrictions on roads. +Explanation of the values can be found in the [list of possible values](https://wiki.openstreetmap.org/wiki/Key:access) + +| Value | Encoding | +|:-----:|:----------:| +| 0 | None (there are no restrictions) | +| 1 | No | +| 2 | Customers | +| 4 | Destination | +| 8 | Delivery | +| 16 | Private | +| 32 | Permissive | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Steepness.md b/docs/versions/v7.1.1/documentation/extra-info/Steepness.md new file mode 100644 index 0000000000..83c2dff4f7 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Steepness.md @@ -0,0 +1,17 @@ +# Steepness + +Negative values indicate decline, positive incline. + +| Value | Encoding | +|:-----:|:--------:| +| -5 | >16% | +| -4 | 12-15% | +| -3 | 7-11% | +| -2 | 4-6% | +| -1 | 1-3% | +| 0 | 0% | +| 1 | 1-3% | +| 2 | 4-6% | +| 3 | 7-11% | +| 4 | 12-15% | +| 5 | >16% | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Surface.md b/docs/versions/v7.1.1/documentation/extra-info/Surface.md new file mode 100644 index 0000000000..a1c87cf9bf --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Surface.md @@ -0,0 +1,25 @@ +# Surface + +This extra provides info about the [surface](https://wiki.openstreetmap.org/wiki/Key:surface) of the corresponding parts of the route. + +| Value | Name | +|:-----:|:----------------:| +| 0 | Unknown | +| 1 | Paved | +| 2 | Unpaved | +| 3 | Asphalt | +| 4 | Concrete | +| 5 | Cobblestone | +| 6 | Metal | +| 7 | Wood | +| 8 | Compacted Gravel | +| 9 | Fine Gravel | +| 10 | Gravel | +| 11 | Dirt | +| 12 | Ground | +| 13 | Ice | +| 14 | Paving Stones | +| 15 | Sand | +| 16 | Woodchips | +| 17 | Grass | +| 18 | Grass Paver | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Trail-Difficulty.md b/docs/versions/v7.1.1/documentation/extra-info/Trail-Difficulty.md new file mode 100644 index 0000000000..19ef380c57 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Trail-Difficulty.md @@ -0,0 +1,14 @@ +# Trail Difficulty + +This extra provides information about a trails difficulty for [hiking](https://wiki.openstreetmap.org/wiki/Key:sac_scale) as well as for [mountain-biking](https://wiki.openstreetmap.org/wiki/Key:mtb:scale). + +| Value | foot-\* | cycling-\* | +|:-----:|-------------------------------------|-------------| +| 0 | no tag | no tag | +| 1 | sac_scale=hiking | mtb:scale=0 | +| 2 | sac_scale=mountain_hiking | mtb:scale=1 | +| 3 | sac_scale=demanding_mountain_hiking | mtb:scale=2 | +| 4 | sac_scale=alpine_hiking | mtb:scale=3 | +| 5 | sac_scale=demanding_alpine_hiking | mtb:scale=4 | +| 6 | sac_scale=difficult_alpine_hiking | mtb:scale=5 | +| 7 | --- | mtb:scale=6 | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Waycategory.md b/docs/versions/v7.1.1/documentation/extra-info/Waycategory.md new file mode 100644 index 0000000000..2d8ead0c8d --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Waycategory.md @@ -0,0 +1,15 @@ +# WayCategory + +The exponential assignment of the values is used for [bit fields](http://eddmann.com/posts/using-bit-flags-and-enumsets-in-java/). One route section may belong to different categories. Hence a value of ``97`` would indicate a belonging to ``Paved road``, ``Tunnel`` and ``Highway`` (``64`` + ``32`` + ``1`` ). + +| Value | Name | +|:-----:|:----------------------------:| +| 0 | No category | +| 1 | Highway | +| 2 | Steps | +| 4 | Unpaved road | +| 8 | Ferry | +| 16 | Track | +| 32 | Tunnel | +| 64 | Paved road | +| 128 | Ford | diff --git a/docs/versions/v7.1.1/documentation/extra-info/Waytype.md b/docs/versions/v7.1.1/documentation/extra-info/Waytype.md new file mode 100644 index 0000000000..f0dccc6d80 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/extra-info/Waytype.md @@ -0,0 +1,17 @@ +# WayType + +This extra provides info about the type of the way of the corresponding parts of the route. + +| Value | Name | +|:-----:|:------------:| +| 0 | Unknown | +| 1 | State Road | +| 2 | Road | +| 3 | Street | +| 4 | Path | +| 5 | Track | +| 6 | Cycleway | +| 7 | Footway | +| 8 | Steps | +| 9 | Ferry | +| 10 | Construction | diff --git a/docs/versions/v7.1.1/documentation/routing-options/Country-List.md b/docs/versions/v7.1.1/documentation/routing-options/Country-List.md new file mode 100644 index 0000000000..ab2c2638c3 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/routing-options/Country-List.md @@ -0,0 +1,54 @@ +# Country List + +This table lists country ids for the `avoid_country`-parameter. For details, see [routing options](Routing-Options). + + | country_id | name | name:en | | country_id | name | name:en | | country_id | name | name:en | | country_id | name | name:en | | country_id | name | name:en | + |:----------:|:--------------------------------------------------:|:------------------------------:|---|:----------:|:-----------------------------------------:|:------------------------------:|---|:----------:|:---------------------------------------:|:---------------------:|---|:----------:|:---------------------------------------------:|:---------------------------------------------:|---|:----------:|:-----------------------------------------:|:------------------------:| + | 1 | افغانستان | Afghanistan | | 49 | Hrvatska | Croatia | | 97 | Italia | Italy | | 145 | Nigeria | Nigeria | | 193 | Schweiz - Suisse - Svizzera - Svizra | Switzerland | + | 2 | Shqipëria | Albania | | 50 | Cuba | Cuba | | 98 | Jamaica | Jamaica | | 146 | Niuē | Niue | | 194 | سوريا | Syria | + | 3 | Algeria | Algeria | | 51 | Κύπρος - Kıbrıs | Cyprus | | 99 | Jangy-ayyl | Jangy-ayyl | | 147 | 조선민주주의인민공화국 | North Korea | | 195 | 臺灣 | Taiwan | + | 4 | Andorra | Andorra | | 52 | Česko | Czech Republic | | 100 | 日本 | Japan | | 148 | Norge | Norway | | 196 | Тоҷикистон | Tajikistan | + | 5 | Angola | Angola | | 53 | Danmark | Denmark | | 101 | Jersey | Jersey | | 149 | عمان | Oman | | 197 | Tanzania | Tanzania | + | 6 | Anguilla | Anguilla | | 54 | Djibouti | Djibouti | | 102 | الأردن | Jordan | | 150 | ‏پاکستان‎ | Pakistan | | 198 | ประเทศไทย | Thailand | + | 7 | Antigua and Barbuda | Antigua and Barbuda | | 55 | Dominica | Dominica | | 103 | Қазақстан | Kazakhstan | | 151 | Belau | Palau | | 199 | The Bahamas | The Bahamas | + | 8 | Argentina | Argentina | | 56 | República Dominicana | Dominican Republic | | 104 | Kenya | Kenya | | 152 | الضفة الغربية وقطاع غزة | Palestinian Territories | | 200 | Nederland | The Netherlands | + | 9 | Հայաստան | Armenia | | 57 | Timór Loro Sa'e | East Timor | | 105 | Kiribati | Kiribati | | 153 | Panamá | Panama | | 201 | Togo | Togo | + | 10 | Australia | Australia | | 58 | Ecuador | Ecuador | | 106 | Kosovë | Kosovo | | 154 | Papua Niugini | Papua New Guinea | | 202 | Tokelau | Tokelau | + | 11 | Österreich | Austria | | 59 | Egypt مصر | Egypt | | 107 | ‏الكويت‎ | Kuwait | | 155 | Paraguay | Paraguay | | 203 | Tonga | Tonga | + | 12 | Azərbaycan | Azerbaijan | | 60 | El Salvador | El Salvador | | 108 | Кыргызстан | Kyrgyzstan | | 156 | Perú | Peru | | 204 | Trinidad and Tobago | Trinidad and Tobago | + | 13 | ‏البحرين‎ | Bahrain | | 61 | Guinea Ecuatorial | Equatorial Guinea | | 109 | ປະເທດລາວ | Laos | | 157 | Philippines | Philippines | | 205 | Tunisie ⵜⵓⵏⵙ تونس | Tunisia | + | 14 | বাংলাদেশ | Bangladesh | | 62 | ኤርትራ | Eritrea | | 110 | Latvija | Latvia | | 158 | Pitcairn Islands | Pitcairn Islands | | 206 | Türkiye | Turkey | + | 15 | Barbados | Barbados | | 63 | Eesti | Estonia | | 111 | لبنان | Lebanon | | 159 | Polska | Poland | | 207 | Türkmenistan | Turkmenistan | + | 16 | Беларусь | Belarus | | 64 | ኢትዮጵያ Ethiopia | Ethiopia | | 112 | Lesotho | Lesotho | | 160 | Portugal | Portugal | | 208 | Turks and Caicos Islands | Turks and Caicos Islands | + | 17 | België - Belgique - Belgien | Belgium | | 65 | Falkland Islands | Falkland Islands | | 113 | Liberia | Liberia | | 161 | ‏قطر‎ | Qatar | | 209 | Tuvalu | Tuvalu | + | 18 | Belize | Belize | | 66 | Føroyar | Faroe Islands | | 114 | Libya ⵍⵉⴱⵢⴰ ليبيا | Libya | | 162 | România | Romania | | 210 | Uganda | Uganda | + | 19 | Bénin | Benin | | 67 | Federated States of Micronesia | Federated States of Micronesia | | 115 | Liechtenstein | Liechtenstein | | 163 | Российская Федерация | Russian Federation | | 211 | Україна | Ukraine | + | 20 | Bermuda | Bermuda | | 68 | Viti | Fiji | | 116 | Lietuva | Lithuania | | 164 | Rwanda | Rwanda | | 212 | الإمارات العربيّة المتّحدة | United Arab Emirates | + | 21 | འབྲུག་ཡུལ་ | Bhutan | | 69 | Suomi | Finland | | 117 | Lëtzebuerg | Luxembourg | | 165 | Sahrawi Arab Democratic Republic | Sahrawi Arab Democratic Republic | | 213 | United Kingdom | United Kingdom | + | 22 | Bolivia | Bolivia | | 70 | France | France | | 118 | Македонија | Macedonia | | 166 | Saint Helena - Ascension and Tristan da Cunha | Saint Helena - Ascension and Tristan da Cunha | | 214 | United States of America | United States of America | + | 23 | Bosna i Hercegovina | Bosnia and Herzegovina | | 71 | Gabon | Gabon | | 119 | Madagasikara | Madagascar | | 167 | Saint Kitts and Nevis | Saint Kitts and Nevis | | 215 | Uruguay | Uruguay | + | 24 | Botswana | Botswana | | 72 | Gambia | Gambia | | 120 | Malawi | Malawi | | 168 | Saint Lucia | Saint Lucia | | 216 | Oʻzbekiston | Uzbekistan | + | 25 | Brasil | Brazil | | 73 | საქართველო | Georgia | | 121 | Malaysia | Malaysia | | 169 | Saint Vincent and the Grenadines | Saint Vincent and the Grenadines | | 217 | Vanuatu | Vanuatu | + | 26 | British Indian Ocean Territory | British Indian Ocean Territory | | 74 | Deutschland | Germany | | 122 | ދިވެހިރާއްޖެ | Maldives | | 170 | Sāmoa | Samoa | | 218 | Città del Vaticano | Vatican City | + | 27 | British Sovereign Base Areas | British Sovereign Base Areas | | 75 | Deutschland - Belgique / België / Belgien | Germany - Belgium | | 123 | Mali | Mali | | 171 | San Marino | San Marino | | 219 | Venezuela | Venezuela | + | 28 | British Virgin Islands | British Virgin Islands | | 76 | Ghana | Ghana | | 124 | Malta | Malta | | 172 | São Tomé e Príncipe | São Tomé and Príncipe | | 220 | Việt Nam | Vietnam | + | 29 | Brunei Darussalam | Brunei | | 77 | Gibraltar | Gibraltar | | 125 | Aelōn̄ in M̧ajeļ | Marshall Islands | | 173 | ‏المملكة العربية السعودية‎ | Saudi Arabia | | 221 | اليمن | Yemen | + | 30 | България | Bulgaria | | 78 | Ελλάδα | Greece | | 126 | Mauritanie موريتانيا | Mauritania | | 174 | Sénégal | Senegal | | 222 | Zambia | Zambia | + | 31 | Burkina Faso | Burkina Faso | | 79 | Kalaallit Nunaat | Greenland | | 127 | Mauritius | Mauritius | | 175 | Србија | Serbia | | 223 | Zimbabwe | Zimbabwe | + | 32 | Burundi | Burundi | | 80 | Grenada | Grenada | | 128 | México | Mexico | | 176 | Sesel | Seychelles | | 224 | Border India - Bangladesh | | + | 33 | ព្រះរាជាណាចក្រ​កម្ពុជា | Cambodia | | 81 | Guatemala | Guatemala | | 129 | Moldova | Moldova | | 177 | Sierra Leone | Sierra Leone | | 225 | Île Verte | | + | 34 | Cameroun | Cameroon | | 82 | Guernsey | Guernsey | | 130 | Monaco | Monaco | | 178 | Singapore | Singapore | | 226 | Border Azerbaijan - Armenia (Enclave AZE) | | + | 35 | Canada | Canada | | 83 | Guinée | Guinea | | 131 | Монгол улс | Mongolia | | 179 | Slovensko | Slovakia | | 227 | Freezland Rock | | + | 36 | Cabo Verde | Cape Verde | | 84 | Guiné-Bissau | Guinea-Bissau | | 132 | Црна Гора / Crna Gora | Montenegro | | 180 | Slovenija | Slovenia | | 228 | Border SI-HR | | + | 37 | Cayman Islands | Cayman Islands | | 85 | Guyana | Guyana | | 133 | Montserrat | Montserrat | | 181 | Solomon Islands | Solomon Islands | | 229 | Willis Island | | + | 38 | Ködörösêse tî Bêafrîka - République Centrafricaine | Central African Republic | | 86 | Ayiti | Haiti | | 134 | Maroc ⵍⵎⵖⵔⵉⴱ المغرب | Morocco | | 182 | Soomaaliya | Somalia | | 230 | Chong-Kara | | + | 39 | Tchad تشاد | Chad | | 87 | Honduras | Honduras | | 135 | Moçambique | Mozambique | | 183 | South Africa | South Africa | | 231 | Ελλάδα - Παγγαίο | | + | 40 | Chile | Chile | | 88 | Magyarország | Hungary | | 136 | မြန်မာ | Myanmar | | 184 | South Georgia and South Sandwich Islands | South Georgia and the South Sandwich Islands | | 232 | Bristol Island | | + | 41 | 中国 | China | | 89 | Ísland | Iceland | | 137 | name | name:en | | 185 | 대한민국 | South Korea | | 233 | Dist. Judges Court | | + | 42 | Colombia | Colombia | | 90 | India | India | | 138 | Namibia | Namibia | | 186 | South Sudan | South Sudan | | 234 | Border Kyrgyzstan - Uzbekistan | | + | 43 | Komori | Comoros | | 91 | Indonesia | Indonesia | | 139 | Naoero | Nauru | | 187 | España | Spain | | 235 | Border Malawi - Mozambique | | + | 44 | République du Congo | Congo-Brazzaville | | 92 | ‏ایران‎ | Iran | | 140 | नेपाल | Nepal | | 188 | ශ්‍රී ලංකාව இலங்கை | Sri Lanka | | 236 | 中華民國 | | + | 45 | République démocratique du Congo | Congo-Kinshasa | | 93 | العراق | Iraq | | 141 | Nederland - Belgique / België / Belgien | Netherlands - Belgium | | 189 | Sudan السودان | Sudan | | | | | + | 46 | Cook Islands | Cook Islands | | 94 | Ireland | Ireland | | 142 | New Zealand/Aotearoa | New Zealand | | 190 | Suriname | Suriname | | | | | + | 47 | Costa Rica | Costa Rica | | 95 | Isle of Man | Isle of Man | | 143 | Nicaragua | Nicaragua | | 191 | Swaziland | Swaziland | | | | | + | 48 | Côte d’Ivoire | Côte d'Ivoire | | 96 | מדינת ישראל | Israel | | 144 | Niger | Niger | | 192 | Sverige | Sweden | | | | | diff --git a/docs/versions/v7.1.1/documentation/routing-options/Examples.md b/docs/versions/v7.1.1/documentation/routing-options/Examples.md new file mode 100644 index 0000000000..8dad6ef6c6 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/routing-options/Examples.md @@ -0,0 +1,145 @@ +# Examples + +**If your request works without the options object, but returns an error with it: try to [%-encode](Routing-Options#url-encoding) the options object!** + +Some options examples in readable and minified JSON form: + +for `profile=driving-car`: + +```json +{ + "avoid_features": ["ferries", "tollways"] +} +``` +`{"avoid_features":["ferries","tollways"]}` + +for `profile=cycling-*`: + +```json +{ + "avoid_features": ["steps"], + "profile_params": { + "weightings": { + "steepness_difficulty": 2 + } + }, + "avoid_polygons": { + "type": "Polygon", + "coordinates": [ + [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] + ]} +} +``` +`{"avoid_features":["steps"],"profile_params":{"weightings":{"steepness_difficulty":2}}}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}` + +for `profile=foot-*`: + +```json +{ + "avoid_features": ["fords","ferries"], + "profile_params": { + "weightings": { + "green": { + "factor": 0.8 + }, + "quiet": { + "factor": 1.0 + } + } + }, + "avoid_polygons": { + "type": "Polygon", + "coordinates": [ + [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] + ]} +} +``` +`{"avoid_features":["fords","ferries"],"profile_params":{"weightings":{"green":{"factor":0.8},"quiet":{"factor":1.0}}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}` + +for `profile=driving-hgv`: + +```json +{ + "avoid_features": ["ferries","tollways"], + "vehcile_type": "hgv", + "profile_params": { + "restrictions": { + "length": 30, + "width": 30, + "height": 3, + "axleload": 4, + "weight": 3, + "hazmat": true + } + }, + "avoid_polygons": { + "type": "Polygon", + "coordinates": [ + [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] + ]} +} +``` +`{"avoid_features":["ferries","tollways"],"vehicle_type":"hgv","profile_params":{"restrictions":{"length":30,"width":30,"height":3,"axleload":4,"weight":3,"hazmat":true}},"avoid_polygons":{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}}` + +for `profile=wheelchair`: + +```json +{ + "avoid_features": ["ferries","steps"], + "profile_params": { + "restrictions": { + "surface_type": "cobblestone:flattened", + "track_type": "grade1", + "smoothness_type": "good", + "maximum_sloped_curb": 0.06, + "maximum_incline": 6 + } + } +} +``` +`{"avoid_features":["ferries","steps"],"profile_params":{"restrictions":{"surface_type":"cobblestone:flattened","track_type":"grade1","smoothness_type":"good","maximum_sloped_curb":0.06,"maximum_incline":6}}}` + +## Border restrictions + +Examples for routing options object with border restrictions: + +*Do not cross country borders at all:* + +```json +{ + "avoid_borders":"all" +} +``` + +`{"avoid_borders":"all"}` + +*Do not cross controlled borders (i.e. USA - Canada) but allow crossing of open borders (i.e. France - Germany):* + +```json +{ + "avoid_borders":"controlled" +} +``` + +`{"avoid_borders":"controlled"}` + +*Do not route through Austria or Switzerland:* + +```json +{ + "avoid_countries": [1,120] +} +``` + +`{"avoid_countries": [1,120]}` + +*Pass open borders but do not cross into Switzerland:* + +```json +{ + "avoid_borders": "controlled", + "avoid_countries": [193] +} +``` + +`{"avoid_borders": "controlled","avoid_countries": [193]}` diff --git a/docs/versions/v7.1.1/documentation/routing-options/Routing-Options.md b/docs/versions/v7.1.1/documentation/routing-options/Routing-Options.md new file mode 100644 index 0000000000..e0a54eddd0 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/routing-options/Routing-Options.md @@ -0,0 +1,81 @@ +# Routing Options + +For advanced options formatted as json object. For structure refer to the [examples](Examples). +The available parameters are: + + +- `avoid_features` : array of features to avoid. + The available features are : + + | Feature | Available for | + |:-------------------:|---------------------------------------------| + | `highways` | driving-\* | + | `tollways` | driving-\* | + | `ferries` | driving-\*, cycling-\*, foot-\*, wheelchair | + | `fords` | driving-\*, cycling-\*, foot-\* | + | `steps` | cycling-\*, foot-\*, wheelchair | + + +- `avoid_borders` : `"all"` for no border crossing. `"controlled"` to cross open borders but avoid controlled ones. Only for `driving-*` profiles. + +- `avoid_countries` : array of country ids to exclude from routing with `driving-*` profiles. Can be used together with `"avoid_borders": "controlled"`. `"[11,193]"` would exclude Austria and Switzerland. List of countries and application examples can be found in the [country list](Country-List). + +- `vehicle_type` (for `profile=driving-hgv` only): `hgv`,`bus`,`agricultural`,`delivery`,`forestry` and `goods`. It is needed for **vehicle restrictions** to work. + +- `profile_params` : Specifies additional routing parameters. + + - `weightings`: Weightings will prioritize specified factors over the shortest path. + + - `steepness_difficulty`: Specifies the fitness level for `cycling-*` profiles. + - `level`: `0` = Novice, `1` = Moderate, `2` = Amateur, `3` = Pro. The prefered gradient increases with level + + - `green`: Specifies the Green factor for `foot-*` profiles. + - `factor`: Values range from `0` to `1`. `0` equals normal routing. `1` will prefer ways through green areas over a shorter route. + + - `quiet`: Specifies the Quiet factor for `foot-*` profiles. + - `factor`: Values range from `0` to `1`. `0` equals normal routing. `1` will prefer quiet ways over a shorter route. + + - `restrictions` : Specifies restrictions for `driving-hgv`, `wheelchair` or `cycling-*` profiles. + + - for `cycling-*`: + + | Parameter | Description | + |:----------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `gradient` | Only for avoided `hills` or specified `steepness_difficulty`. Specifies the maximum route steepness in percent. Values range from `1` to `15`. Routes with a higher gradient are avoided. | + + - for `driving-hgv`: + *(you have to specify the `vehicle_type` in the options for these parameters)* + + | Parameter | Description | + |:----------:|-----------------------------------------------------------------------------------------------------------------------------------| + | `length` | Length restriction in meters. | + | `width` | Width restriction in meters. | + | `height` | Height restriction in meters. | + | `axleload` | Axleload restriction in tons. | + | `weight` | Weight restriction in tons. | + | `hazmat` | Specifies whether to use appropriate routing for delivering hazardous goods and avoiding water protected areas. Default is false. | + + - for `wheelchair`: + + | Parameter | Description | + |:---------------------:|-----------------------------------------------------------------------------------------------------------------------------| + | `surface_type` | Specifies the minimum [surface type](http://wiki.openstreetmap.org/wiki/Key:surface). Default is `"cobblestone:flattened"`. | + | `track_type` | Specifies the minimum [grade](http://wiki.openstreetmap.org/wiki/Key:tracktype) of the route. Default is `"grade1"`. | + | `smoothness_type` | Specifies the minimum [smoothness](http://wiki.openstreetmap.org/wiki/Key:smoothness) of the route. Default is `"good"`. | + | `maximum_sloped_kerb` | Specifies the maximum height of the sloped kerb in meters. Values are `0.03`, `0.06`(default), `0.1` or `any`. | + | `maximum_incline` | Specifies the maximum incline as a percentage. `3`, `6`(default), `10`, `15` or `any`. | + | `minimum_width` | Specifies the minimum width of a road in meters. | + + +- `avoid_polygons` : Comprises areas to be avoided for the route. Formatted as [geojson polygon](http://geojson.org/geojson-spec.html#id4) or [geojson multipolygon](http://geojson.org/geojson-spec.html#id7). + +## URL Encoding + +To use the curl command string you have to encode special characters. +Values you need are shown in this table: + + | Character | { | \| | } | " | [ | ] | + |:---------:|:---:|:---:|:---:|:---:|:---:|:---:| + | Encoding | %7B | %7C | %7D | %22 | %5B | %5D | + +Sometimes needs to be used for the [options object](#examples). diff --git a/docs/versions/v7.1.1/documentation/travel-speeds/Country-Speeds.md b/docs/versions/v7.1.1/documentation/travel-speeds/Country-Speeds.md new file mode 100644 index 0000000000..0948b7958d --- /dev/null +++ b/docs/versions/v7.1.1/documentation/travel-speeds/Country-Speeds.md @@ -0,0 +1,94 @@ +# Country-specific Speeds +As there are various traffic regulations in different countries, if no [maximum +speed](http://wiki.openstreetmap.org/wiki/Key:maxspeed) tag is given in +openstreetmap, we adjust the maximum speed according to the following key +values taken from [country specific speed +limits](http://wiki.openstreetmap.org/wiki/Speed_limits). +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Country | Tags | driving-car | driving-hgv | + |:--------------:|:--------------------:|:-----------:|:-----------:| + | Austria | AT:urban | 50 | 50 | + | | AT:rural | 100 | 80 | + | | AT:trunk | 100 | 80 | + | | AT:motorway | 130 | 80 | + | Switzerland | CH:urban | 50 | 50 | + | | CH:rural | 80 | 80 | + | | CH:trunk | 100 | 80 | + | | CH:motorway | 120 | 80 | + | Czech Republic | CZ:urban | 50 | 50 | + | | CZ:rural | 90 | 90 | + | | CZ:trunk | 80 | 80 | + | | CZ:motorway | 80 | 80 | + | Denmark | DK:urban | 50 | 50 | + | | DK:rural | 80 | 80 | + | | DK:motorway | 130 | 80 | + | Germany | DE:living_street | 7 | 7 | + | | DE:urban | 50 | 50 | + | | DE:rural | 100 | 80 | + | | DE:motorway | 130 | 80 | + | Finland | FI:urban | 50 | 50 | + | | FI:rural | 80 | 80 | + | | FI:trunk | 100 | 80 | + | | FI:motorway | 120 | 80 | + | France | FR:urban | 50 | 50 | + | | FR:rural | 80 | 80 | + | | FR:trunk | 110 | 80 | + | | FR:motorway | 130 | 80 | + | Greece | GR:urban | 50 | 50 | + | | GR:rural | 90 | 80 | + | | GR:trunk | 110 | 80 | + | | GR:motorway | 130 | 80 | + | Hungary | HU:urban | 50 | 50 | + | | HU:rural | 90 | 80 | + | | HU:trunk | 110 | 80 | + | | HU:motorway | 130 | 80 | + | Italy | IT:urban | 50 | 50 | + | | IT:rural | 90 | 80 | + | | IT:trunk | 110 | 80 | + | | IT:motorway | 130 | 80 | + | Japan | JP:national | 60 | 60 | + | | JP:motorway | 100 | 80 | + | Poland | PL:living_street | 20 | 20 | + | | PL:urban | 50 | 50 | + | | PL:rural | 90 | 80 | + | | PL:motorway | 140 | 80 | + | Romania | RO:urban | 50 | 50 | + | | RO:rural | 90 | 80 | + | | RO:trunk | 100 | 80 | + | | RO:motorway | 130 | 80 | + | Russia | RU:living_street | 20 | 20 | + | | RU:rural | 90 | 80 | + | | RU:urban | 60 | 60 | + | | RU:motorway | 110 | 80 | + | Slovakia | SK:urban | 50 | 50 | + | | SK:rural | 90 | 80 | + | | SK:trunk | 90 | 80 | + | | SK:motorway | 90 | 80 | + | Slovenia | SI:urban | 50 | 50 | + | | SI:rural | 90 | 80 | + | | SI:trunk | 110 | 80 | + | | SI:motorway | 130 | 80 | + | Spain | ES:urban | 50 | 50 | + | | ES:rural | 90 | 80 | + | | ES:trunk | 100 | 80 | + | | ES:motorway | 120 | 80 | + | Sweden | SE:urban | 50 | 50 | + | | SE:rural | 70 | 70 | + | | SE:trunk | 90 | 80 | + | | SE:motorway | 110 | 80 | + | United Kingdom | GB:nsl_single | 95 | 90 | + | | GB:nsl_dual | 112 | 90 | + | | GB:motorway | 112 | 90 | + | Ukraine | UA:urban | 60 | 60 | + | | UA:rural | 90 | 80 | + | | UA:trunk | 110 | 80 | + | | UA:motorway | 130 | 80 | + | Uzbekistan | UZ:living_street | 30 | 30 | + | | UZ:urban | 70 | 70 | + | | UZ:rural | 100 | 90 | + | | UZ:motorway | 110 | 90 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v7.1.1/documentation/travel-speeds/Surface-Speeds.md b/docs/versions/v7.1.1/documentation/travel-speeds/Surface-Speeds.md new file mode 100644 index 0000000000..a3706fab70 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/travel-speeds/Surface-Speeds.md @@ -0,0 +1,39 @@ +# Surface Speeds +The surfaces correspond to the OSM [surface](https://wiki.openstreetmap.org/wiki/Key:surface) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Surface \ Profile -> | driving-car | driving-hgv | cycling-regular | + |:--------------------:|:-----------:|:-----------:|:---------------:| + | asphalt | -1 | -1 | 18 | + | concrete | -1 | -1 | 18 | + | concrete:plates | -1 | -1 | 16 | + | concrete:lanes | -1 | -1 | 16 | + | paved | -1 | -1 | 18 | + | cement | 80 | 60 | -1 | + | compacted | 80 | 60 | 18 | + | fine_gravel | 60 | 50 | 16 | + | paving_stones | 40 | 40 | 12 | + | metal | 40 | 40 | 10 | + | bricks | 40 | 40 | -1 | + | grass | 30 | 30 | 8 | + | wood | 30 | 30 | 6 | + | sett | 30 | 30 | 10 | + | grass_paver | 30 | 30 | 8 | + | gravel | 30 | 30 | 12 | + | unpaved | 30 | 30 | 14 | + | ground | 30 | 30 | 12 | + | dirt | 30 | 30 | 10 | + | pebblestone | 30 | 30 | 16 | + | tartan | 30 | 30 | -1 | + | cobblestone | 20 | 20 | 8 | + | clay | 20 | 20 | -1 | + | earth | 15 | 15 | 12 | + | stone | 15 | 15 | -1 | + | rocky | 15 | 15 | -1 | + | sand | 15 | 15 | 6 | + | mud | 10 | 10 | 10 | + | unknown: | 30 | 30 | -1 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v7.1.1/documentation/travel-speeds/Tracktype-Speeds.md b/docs/versions/v7.1.1/documentation/travel-speeds/Tracktype-Speeds.md new file mode 100644 index 0000000000..4ad303507d --- /dev/null +++ b/docs/versions/v7.1.1/documentation/travel-speeds/Tracktype-Speeds.md @@ -0,0 +1,15 @@ +# Tracktype Speeds +The tracktypes corresponds to the OSM [tracktype](https://wiki.openstreetmap.org/wiki/Key:tracktype) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Tracktype \ Profile -> | driving-car | driving-hgv | cycling-regular| + |:----------------------:|:-----------:|:-----------:|:--------------:| + | grade1 | 40 | 40 | 18 | + | grade2 | 30 | 30 | 12 | + | grade3 | 20 | 20 | 8 | + | grade4 | 15 | 15 | 6 | + | grade5 | 10 | 10 | 4 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v7.1.1/documentation/travel-speeds/Travel-Speeds.md b/docs/versions/v7.1.1/documentation/travel-speeds/Travel-Speeds.md new file mode 100644 index 0000000000..227dbfc259 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/travel-speeds/Travel-Speeds.md @@ -0,0 +1,100 @@ +# Travel speeds +A main component that determines things such as fastest routes and the travel +time for isochrones and route instructions is travel speed. This value is +determined differently depending on the profile and can be affected by a number +of aspects. + +## Travel Time Calculation + +The travel time is calculated for each segment by using speed-limits for +different [waytypes](https://wiki.openstreetmap.org/wiki/Key:highway) and +adjusting them for different +[grades](https://wiki.openstreetmap.org/wiki/Key:tracktype) or +[surfaces](https://wiki.openstreetmap.org/wiki/Key:surface) of the road. +If multiple values apply at any point, the lowest value is used. + +The speed limits can be reduced by setting the `maximum_speed` parameter in a [request][apidocs]. +The final [average speed](../Route-Attributes#avgspeed) can be requested by adding `avgspeed` to the `attributes` parameter. + +### Driving profiles (car and HGV) +The base travel speed for any road is based on a cascading assessment: +1. When an tag explicitly stating the speed limit for a road is present on the + way in OSM (`maxspeed` or `maxspeed:forward / maxspeed:backward`), this is + used as the base speed. +2. If the way has a `zone:maxspeed` or `zone:traffic` tag, this is compared to + country-specific values in the `max_speeds` array of the + [speed value files][svf]. + An overview can be found in the [country speed table](Country-Speeds). + This value is then used as the base speed. +3. If neither of the above set a base speed, then the type of way (`highway=` + tag) determines the base speed. Values are defined in the + [speed value files][svf]. + The [waytype speed table](Waytype-Speeds) gives an overview. +4. If it is a track (`highway=track`) then the base speed is set based on the + `tracktype` tag compared to values in the [speed value files][svf]. + The [tracktype speed table](Tracktype-Speeds) gives an overview. + +If the determined base speed is one resulting from a `maxspeed`-tag or from a +[country speed table](Country-Speeds) (i.e. Steps 1 or 2), it is reduced to 90% +of its original value, since it is more common that you would be travelling +below the maximum speed value. The [waytype](Waytype-Speeds) and +[tracktype](Tracktype-Speeds) defaults have already been chosen rather +conservatively, so they are not adjusted. + +Following that, it is further modified based on a number of other factors: +* If a surface is defined (`surface=*`) then the surface value is set to be the + corresponding surface type value defined in the [speed value files][svf]. + An overview can be found in the [surface speed table](Surface-Speeds). +* Attempt to take into account reduced speeds in residential areas using + acceleration modifier or a residential penalty +* cap speed if it is entering a roundabout (based on number of lanes and + roundabout type - mini roundabout = 25km/h, 1 lane = 35km/h, 2 or more lanes += 40km/h) + +### Bike profiles +Bike profiles determine their speeds based on a number of defaults set in the +code based on surface, highway type, and track type. _Though there is currently +a speed_limits file present in the resources for bike profiles, these values +are not used in the calculation_ + +The speeds used can be found in the [CommonBikeFlagEncoder][cbfe] for the +default values and regular bike profile, [MountainBikeFlagEncoder][mbfe] for +the mountain bike profile, [RoadBikeFlagEncoder][rbfe] for the road bike, and +[ElectroBikeFlagEncoder][ebfe] for the electric bike. + +Note that each bike profile has a different value set for the maximum +downhill speed which is calculated when `consider_elevation=true` is set in the +ors-config.json. Currently, this option is turned off for openrouteservice live +servers as it can lead to undesirable routes. + +### Walking profiles +The travel speeds for `foot-*` profiles (walking and hiking) are set to +5 km/h on all allowed waytypes. +For ways with a [`sac_scale`](../extra-info/Trail-Difficulty) higher than +`hiking`, they are reduced to 2 km/h. + +Allowed waytypes consist of ways that are safe for use, ways that are better +avoided (but still allowed) and other allowed ways in between: + + | safe tags | avoid tags | other highway tags | + |:----------------------:|:----------------:|:-------------------:| + | footway | trunk | cycleway | + | path | trunk_link | unclassified | + | steps | primary | road | + | pedestrian | primary_link | | + | living_street | secondary | | + | track | secondary_link | | + | residential | tertiary | | + | service | tertiary_link | | + +### Wheelchair profile +The wheelchair profile has a base speed of 4km/h which is then modified based +on a number of parameters. As such, based on the presence of sidewalks and type +of way, the actual speed can range from 3 to 10km/h + +[svf]: https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/services/routing/speed_limits +[cbfe]: https://github.com/GIScience/openrouteservice/blob/master/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/CommonBikeFlagEncoder.java#L186 +[mbfe]: https://github.com/GIScience/openrouteservice/blob/master/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/MountainBikeFlagEncoder.java#L52 +[rbfe]: https://github.com/GIScience/openrouteservice/blob/master/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/RoadBikeFlagEncoder.java#L85 +[ebfe]: https://github.com/GIScience/openrouteservice/blob/master/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/ElectroBikeFlagEncoder.java#L41 +[apidocs]: https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post diff --git a/docs/versions/v7.1.1/documentation/travel-speeds/Waytype-Speeds.md b/docs/versions/v7.1.1/documentation/travel-speeds/Waytype-Speeds.md new file mode 100644 index 0000000000..468d4b28a4 --- /dev/null +++ b/docs/versions/v7.1.1/documentation/travel-speeds/Waytype-Speeds.md @@ -0,0 +1,31 @@ +# Waytype Speeds +The waytypes correspond to the OSM [highway](https://wiki.openstreetmap.org/wiki/Key:highway) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Waytype \ Profile -> | driving-car | driving-hgv | cycling-regular | + |:--------------------:|:-----------:|:-----------:|:---------------:| + | motorway | 100 | 85 | - | + | motorway_link | 60 | 50 | - | + | motorroad | 90 | 80 | - | + | trunk | 85 | 60 | 18 | + | trunk_link | 60 | 50 | 18 | + | primary | 65 | 60 | 18 | + | primary_link | 50 | 50 | 18 | + | secondary | 60 | 60 | 18 | + | secondary_link | 50 | 50 | 18 | + | tertiary | 50 | 50 | 18 | + | tertiary_link | 40 | 40 | 18 | + | unclassified | 30 | 30 | 16 | + | residential | 30 | 30 | 18 | + | living_street | 10 | 10 | 6 | + | service | 20 | 20 | 14 | + | road | 20 | 20 | 12 | + | track | 15 | 15 | 12 | + | path | - | - | 12 | + | footway | - | - | 6 | + | pedestrian | - | - | 6 | + | cycleway | - | - | 18 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/master/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v7.1.1/getting-started.md b/docs/versions/v7.1.1/getting-started.md new file mode 100644 index 0000000000..94df3cfc15 --- /dev/null +++ b/docs/versions/v7.1.1/getting-started.md @@ -0,0 +1,20 @@ +# Getting started + + +The fastest way to get to the info you are looking for is **the search bar above**. +If that doesn't work, the sidebar has you covered: + +* [Installation and Usage](installation/Installation-and-Usage) contains all + info about setting up the ors locally, whether from + [docker](installation/Running-with-Docker) or from + [source](installation/Building-from-Source). It also contains info about + [configuring openrouteservice](installation/Configuration), + [IDE usage](installation/Opening-Project-in-IntelliJ) and + [more docker stuff](installation/Advanced-Docker-Setup) +* [Data](Data) contains info about the used data sets. +* [Contributing](contributing/Contributing) contains info about contributing to + the openrouteservice, the OpenStreetMap and + [translations](contributing/Contributing-Translations) +* [Documentation](documentation/Documentation) contains all sorts of + explanation about the internal workings of the openrouteservice. +* [FAQ](Frequently-Asked-Questions) contains answers to frequently asked questions. diff --git a/docs/versions/v7.1.1/index.md b/docs/versions/v7.1.1/index.md new file mode 100644 index 0000000000..69e24d9e7f --- /dev/null +++ b/docs/versions/v7.1.1/index.md @@ -0,0 +1,34 @@ +--- +title: Home +layout: home +hero: + name: Openrouteservice Backend Documentation - v7.1.1 + tagline: Smart mobility made easy + actions: + - theme: brand + text: Getting Started + link: ./getting-started + - theme: alt + text: API Playground + link: https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post + - theme: alt + text: Contributing + link: ./contributing/Contributing + - theme: alt + text: Reference + link: ./documentation/Documentation + +features: + - title: Installation + details: Set up your own openrouteservice instance. + linkText: Instructions + link: ./installation/Installation-and-Usage + - title: Data Sources + details: Find all information on the data used by the openrouteservice here. + linkText: Data + link: ./Data + - title: Latest Changes + details: Check out the latest changes to the openrouteservice. + linkText: CHANGELOG.md + link: https://github.com/GIScience/openrouteservice/blob/master/CHANGELOG.md +--- diff --git a/docs/versions/v7.1.1/installation/Advanced-Docker-Setup.md b/docs/versions/v7.1.1/installation/Advanced-Docker-Setup.md new file mode 100644 index 0000000000..b45b4e0a14 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Advanced-Docker-Setup.md @@ -0,0 +1,82 @@ +# Advanced Docker Setup + +Running openrouteservice out of the box via Docker and docker-compose is a great way to quickly get into how to use openrouteservice. For most applications though, you would want to customise some things such as which profiles you want to build and the data that you want to route with. In it's initial Docker container form, openrouteservice uses an older test dataset of Heidelberg (Germany) as the base data, and only builds the car profile. To do more than that, you need to get your hands a little dirty with some configuration settings. This may sound a little daunting, but it is designed in a way that once you overcome the initial understanding of the configuration and Docker, you will be able to use your own datasets and decide which profiles to use in no time. + +Throughout this setup procedure, we will assume that you are running openrouteservice through Docker Compose after cloning from the official openrouteservice repository. You can of course do it using just Docker or even through Maven and Tomcat, but for now we will look at the Docker Compose method as that is generally the best. + +So let's get started! + +## Are you running for the first time or the second? + +One of the biggest deciding factors as to how the configuration is changed is whether you are building your openrouteservice Docker container for the very first time, or if you are restarting an already built container. + +In general, we recommend that you build openrouteservice first using the default settings and then make modifications after this first build as then the folder structure and config files are produced ready. + +### Building for the first time + +If you have just downloaded openrouteservice from the GitHub repo (`git clone https://github.com/GIScience/openrouteservice`) and have yet to run `docker-compose up` then the first place to look into is the `docker-compose.yml` file inside the `docker` folder. Here is where you map tell Docker which files to use. + +The easiest thing to change is the data that you will be using. In the file, you will see a block of code which has been commented out like the following: +```yaml +# build: +# context: ../ +# args: +# ORS_CONFIG: ./ors-api/src/main/resources/ors-config-sample.json +# OSM_FILE: ./ors-api/src/main/files/heidelberg.osm.gz +``` +This block is what tells docker-compose that rather than using the pre-built image on docker hub (or one you have already built) we want to build the image here. So to start off, lets uncomment out this code by removing the `#` characters at the start of each line in this block. The two values in `args` are used to tell the build process which config file to build with (we will talk about that soon) and which osm dataset to use. One thing that can get a little confusing here is where the files should be placed in relation to the docker-compose file. You will see the `context: ../` entry which is telling docker-compose that the "root" folder of where the Docker file and all resulting paths are is one folder above where the `docker-compose.yml` file is. That means that any path you define in the two `args` items are relative to that root folder. +So, lets say you want to use an OSM PBF file for Germany - you could create a folder in the same folder as the Docker file called `data` and put the PBF file in there. Then, inside the docker-compose file, you update the `OSM_FILE` entry to be `OSM_FILE: ./data/germany-latest.osm.pbf`. Now when you run `docker-compose up` this file will be copied into the container and renamed to be `osm_file.pbf` inside the `/ors-core/data` folder, and that is the file that gets used for building the graphs. + +The other line of `ORS_CONFIG: ...` tells the system which config file to copy over to the container to use as the base for creating a configuration file that is compatible with the Docker container. As all filepaths used would need to be in relation to the internal file structure of the container, the first time that the container is built, the provided config file is modified so that the paths for the osm file, elevation data and graphs are all modified to point to the `/ors-core/data/...` folders. Also, it is set so that only the first profile in the list of profiles to build is built (see below). The resultant ors-config.json file is then copied to the `conf` folder that is now in the folder that the docker-compose file is located in. It is recommended that this config file is used as the basis for all modifications that you make once you have built. + +### Running an already built container + +If you have already built the openrouteservice container once, making modifications to the osm data and configuration is somewhat easier. + +The first thing you should do before making changes is to stop the container. **Note that using `docker-compose restart` does not carry across changes made inside the `docker-compose.yml` file, so you should use `docker-compose down` to take down the container, and then `docker-compose up` to restart it again when you have made changes.** + +If you are making changes to anything relating to the OSM data or the settings that change how graphs are built, you need to delete the folders in `graphs` or ensure that the `BUILD_GRAPHS` is set to true in the `docker-compose` file. This makes it so that the graphs are built again with the new data/settings. + +To change the OSM data that is used, you need to uncomment out the following line within the `volumes` section of the `docker-compose.yml` file: +```yaml +#- ./your_osm.pbf:/ors-core/data/osm_file.pbf +``` +and then modify the `./your_osm.pbf` part to point to the osm file that you want to use. This will tell docker to overwrite the current osm file in the container with the one that you are providing. + +One thing to be aware of is the size of the data and how much RAM is given to Java inside the container. We generally [recommend](System-Requirements) at least twice the amount of RAM as the file size, but to tell Java this, you need to update the `JAVA_OPTS` in the `environment` section of the `docker-compose` file. In that line, you will see the `-Xms1g` and `-Xmx2g` items. These tell Java that it should start with 1GB RAM assigned to it, and go no higher than 2 GB of usage. If your pbf file is 1.5 GB in size then you would update the `-Xmx` item to be **AT LEAST** `-Xmx3g`. In general, we would recommend adding a bit more to the RAM value if possible to reduce the chances of hitting an out of memory exception towards the end of the graph building. + +To change any configuration settings, all you need to do is modify the `ors-config.json` file found in the `conf` folder and then restart the container as mentioned above. There are a number of configurations that can be changed, with information available on the [configuration wiki page](Configuration) about what each of these are. As a quick example, by default the openrouteservice docker container only builds the car profile. If you want to add another profile, for example the hiking profile, all you need to do is modify the +```json +"active": [ + "car" + ], +``` +list to include that profile: +```json +"active": [ + "car", + "hiking" + ], +``` +Now when you restart the container, the hiking profile will also be built. As another example, lets say that rather than the default maximum number of locations in a matrix request (100) you want to do some analysis with a lot more, e.g. 10,000 so that you can do a 100 origin x 100 destination matrix calculation. To do that, you would change the `"maximum_routes": 100` within the `matrix` object to be `"maximum_routes": 10000` and then restart the container. + +## Memory mapping in large builds +If you are running a large build (e.g. a planet file) then you may need to increase the number of memory mappings. You only need to do this on the host machine as this value is used by the Docker containers running on it aswell. To do this, go into the system configuration file with `sudo nano /etc/sysctl.conf` and add the following line to the bottom of the file: + +```sh +vm.max_map_count=81920 +``` + +The usual sign that you need to do this change is if you see something similar to the following in your logs: + +```sh +# There is insufficient memory for the Java Runtime Environment to continue. +# Native memory allocation (mmap) failed to map 16384 bytes for committing reserved memory. +# An error report file with more information is saved as: +# /ors-core/hs_err_pid128.log +``` + +## Instance infrastructure +Though having a single container works great for smaller datasets or when the graph data doesn't need updating, in many real world implementations having just the one instance isn't the most suitable solution. If you have one container, then all building and serving of routes happens through that single container, meaning that when you rebuild graphs, you can't make any requests to that instance for things like directions as there are no complete graphs that can be used to generate routes with. If it is important that you have graph updates from new data whilst ensuring that there is a minimal amount of time where users cannot make requests, we would recommend having two instances - one that is permanently active for serving requests, and one that gets fired up to rebuild graphs. + +In that setup, when graphs have been built you can simply stop the container serving requests, replace the graphs used (they are mapped to a folder on the host machine which is defined in the `docker-compose` file), and then restart the container. The new graphs will be reloaded into memory (the amount of time needed for this depends on the size of the graphs and the type of hard drive) and then ready to use for routing. The downtime from reloading already built graphs is normally far less than the time needed to build the graphs. A thing to note though is that you should ensure that the config files and the amount of RAM allocated (as described earlier) is the same on both the builder and the request server else the newly built graphs may not load. **Also, ensure that `BUILD_GRAPHS` parameter in the `docker-compose` file used by the request serving container is set to false else it will try to build the graphs for itself!** diff --git a/docs/versions/v7.1.1/installation/Backend-Documentation.md b/docs/versions/v7.1.1/installation/Backend-Documentation.md new file mode 100644 index 0000000000..44da924d39 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Backend-Documentation.md @@ -0,0 +1,36 @@ +# Setting up the backend documentation + +The backend documentation is built using [vitepress](https://vitepress.dev/guide/getting-started). + +Requirements: +- [node version 20](https://nodejs.org/en/download) + +## Set up locally + +To run a development version with hot reload locally, run + +```bash +npm install +npm run docs:dev +``` + +To build the static files to `docs/.vitepress/dist` and preview the production version locally, use + +```bash +npm run docs:build +npm run docs:preview +``` + +## Configuration and Theme + +Configuration of the site (e.g. sidebar, navigation, …) is in `docs/.vitepress/config.js`. +Follow the [vitepress reference](https://vitepress.dev/reference/site-config) for changes to that. + +The custom theme is in `docs/.vitepress/theme`. +See the [vitepress guide](https://vitepress.dev/guide/extending-default-theme) for details. + +## Deployed version + +The documentation is deployed via a GitHub Action in `.github/workflows/deploy-docs.yml` +using [GitHub Pages](https://pages.github.com/) +on [giscience.github.io/openrouteservice](https://giscience.github.io/openrouteservice/). diff --git a/docs/versions/v7.1.1/installation/Building-from-Source.md b/docs/versions/v7.1.1/installation/Building-from-Source.md new file mode 100644 index 0000000000..4d5ff0b554 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Building-from-Source.md @@ -0,0 +1,211 @@ +# Building from Source + +**We recommend running openrouteservice using a Docker container (see [Running with Docker](Running-with-Docker))** + +## Installation from source + +If you need to install without Docker, on an Ubuntu 20.04 system (also generally works with newer Ubuntu versions) you can use the following steps: + + 1. (Fork and) Clone the openrouteservice repository to your machine. + ```bash + git clone https://github.com/user/openrouteservice.git + cd openrouteservice + ``` + + 2. Make sure that you have java 17 set as the default Java environment. + 3. Make sure that you have Maven installed. + 4. Download/create an OpenStreetMap pbf file on the machine. + 5. Copy the `ors-api/src/main/resources/ors-config-sample.json` file to + the same location but renaming it to `ors-config.json`. + 6. Update the `ors-config.json` file to reflect the various settings, profiles you + want to have running, and the locations of various files, in particular + the source location of the OSM file that will be used and additional files + required for extended storages. You should make sure that these folders/files + are accessible by the service, for example by using the `sudo chmod -R 777 + [path to folder]` command. + An explanation of the file format and parameters can be found [here](Configuration) + 7. From within the `openrouteservice` root directory run the command `mvn package`. This will build + the openrouteservice ready for tomcat deployment. + 8. For running both the unit and api tests, add `-Papitests` as a parameter to `mvn`. + ``` + mvn -Papitests verify + ``` + Note that the test graphs won't be rebuilt + unless the `ors-engine/graphs-apitests`-folder has been deleted. + +After you have packaged openrouteservice, there are two options for running it. +One is to run the `mvn spring-boot:run` command which triggers a spring-boot native +Tomcat instance running on port `8082`. This is more restrictive in terms of +settings for Tomcat. The other is to install and run Tomcat 8 + +## Running from within IDE + +To run the project from within your IDE, you have to: + + 1. Set up your IDE project and import `openrouteservice` + modules as Maven model. + For IntelliJ Idea, have a look at [these instructions](Opening-Project-in-IntelliJ). + + 2. Configure your IDE to run `spring-boot:run` as the maven goal, setting the + environment variable `ORS_CONFIG=ors-config-test.json`. + + 3. You can run all tests via JUnit. + +## Installing and running tomcat8 + + 1. Install Tomcat 8 using `sudo apt-get install tomcat8`. + + Note that it might not be available in the latest repositories of your distribution anymore. + In that case, add the following line(s) to your `/etc/apt/sources.list`: + ``` + debian: deb http://ftp.de.debian.org/debian/ stretch main + deb http://security.debian.org/ stretch/updates main + + ubuntu: deb http://de.archive.ubuntu.com/ubuntu bionic main universe + deb http://de.archive.ubuntu.com/ubuntu bionic-security main universe + ``` + For more details, visit [the debian wiki](https://wiki.debian.org/SourcesList) on the `sources.list`-format. + + 2. If you want to use system settings (i.e. Java heap size) other than the + default, then you need to add these to the + `/usr/share/tomcat8/bin/setenv.sh` file. If the file is not present, then you + can create it. The settings generally used on our servers are similar to: + + ```bash + JAVA_OPTS="-server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:ParallelGCThreads=4 -Xms105g -Xmx105g -XX:MaxMetaspaceSize=50m" + CATALINA_OPTS="(here we set settings for JMX monitoring)" + ``` + + 3. If you add these new settings to the `setenv.sh` file, then you need to + restart Tomcat for these to take effect using `sudo systemctl restart + tomcat8.service`. + 4. To get openrouteservice up and running, copy the `ors.war` file found in + the `ors-api/target` folder to the Tomcat webapps folder. For + example + + ```bash + sudo cp ~/openrouteservice/ors-api/target/ors.war /var/lib/tomcat8/webapps/ + ``` + + 5. Tomcat should now automatically detect the new WAR file and deploy the + service. Depending on profiles and size of the OSM data, this can take + some time until openrouteservice has built graphs and is ready for generating + routes. You can check if it is ready by accessing + `http://localhost:8080/ors/health` (the port and URL may be different if you + have installed Tomcat differently than above). If you get a `status: ready` + message, you are good to go in creating routes. + +There are numerous settings within the `ors-config.json` which are highly dependent +on your individual circumstances, but many of these [are documented](Configuration). As a guide +however you can look at the `ors-config-sample.json` file in the +`ors-api/src/main/resources` folder. If you run into issues relating +to out of memory or similar, then you will need to adjust java/tomcat settings +accordingly. + +## Integrating GraphHopper + +If you need to make adjustments to our forked and edited [GraphHopper +repository](https://github.com/GIScience/graphhopper), follow these steps: + +1. Clone and checkout `ors_4.0`: + + ```bash + git clone https://github.com/GIScience/graphhopper.git + cd graphhopper + git checkout ors_4.0 + ``` + +2. Build the project to create the local snapshot. + +3. Change the `ors-engine/pom.xml`: + + ```xml + + + + com.graphhopper + graphhopper-core + 4.0-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + + + com.graphhopper + graphhopper-web-api + 4.0-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + + + com.graphhopper + graphhopper-reader-gtfs + 4.0-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + ``` + +4. Test your new functionality and run all tests after + rebasing your feature branch with the latest `development` branch. Adjust + tests if necessary + +5. If successful, create a PR for both + [openrouteservice](https://github.com/GIScience/openrouteservice/pulls) and + [GraphHopper](https://github.com/GIScience/graphhopper/pulls) against `master` + and `ors_4.0` branches, respectively. + +**Note that in the above example, the 4.x version of GH is being used - you should +adapt according to your specific version. To know which one to use, check the +[ors-engine module pom file](https://github.com/GIScience/openrouteservice/ors-engine/pom.xml) +and see what version is being used for the `com.github.GIScience.graphhopper` +dependencies** diff --git a/docs/versions/v7.1.1/installation/Configuration.md b/docs/versions/v7.1.1/installation/Configuration.md new file mode 100644 index 0000000000..f5daec4f82 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Configuration.md @@ -0,0 +1,434 @@ +# Configuration + +The configuration of your own **openrouteservice** instance is done in a YAML file called `ors-config.yml`. +**openrouteservice** looks for such files in different locations. If a property is set in multiple files, later +occurances will override previous ones. + +- `/etc/openrouteservice/ors-config.yml` +- `~/.openrouteservice/ors-config.yml` +- `./ors-config.yml` (in the runtime working directory) + +### Available properties + +The properties are organized in a hierarchical structure. Since **openrouteservice** is based +on [spring](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html), all common +spring properties can be set in the ors-config.yml file. The most relevant for normal use are the following: + +| key | type | description | default value | +|--------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| +| server.port | int | Server port | 8082 | +| logging.log4j2.config.override | string | Logging configuration file. **openrouteservice** ships with three presets (`DEFAULT_LOGGING.json`, `DEBUG_LOGGING.json`, `PRODUCTION_LOGGING.json`), but you can also define your own logging configuration. | classpath:logs/DEFAULT_LOGGING.json | + +Additional properties specific to **openrouteservice** are organized under the following top level keys. Detailed +descriptions of each block follows below. + +| key | description | +|---------------|------------------------------------------------------------------------| +| ors.endpoints | Settings required at runtime to process API requests. | +| ors.engine | Settings required at graph-build time during startup. | +| ors.cors | CORS settings for the **openrouteservice** API. | +| ors.messages | System messages can be sent with API responses following simple rules. | + +### Properties in the `endpoints` block + +| key | type | description | default value | +|-------------------------------------------------|--------|----------------------------------------------------------------------------------------|-----------------------------------| +| ors.endpoints.routing.base_url | string | | https://openrouteservice.org/ | +| ors.endpoints.routing.swagger_documentation_url | string | Define the url for the the swagger documentation. Can be different from the `base_url` | https://api.openrouteservice.org/ | +| ors.endpoints.routing.support_mail | string | | support@openrouteservice.org | +| ors.endpoints.routing.author_tag | string | | openrouteservice | +| ors.endpoints.routing.content_licence | string | | LGPL 3.0 || + +### Properties in the `engine` block + +| key | type | description | default value | +|--------------|--------|-------------|---------------| +| ors.engine.x | string | | | + +### Properties in the `cors` block + +| key | type | description | default value | +|------------------------|-------------------------------|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| cors.allowed_origins | string / comma separated list | Configures the Access-Control-Allow-Origins CORS header. `*` for all origins | * | +| cors.allowed_headers | string / comma separated list | Configures the Access-Control-Allow-Headers CORS header. `*` for all headers | Content-Type, X-Requested-With, accept, Origin, Access-Control-Request-Method, Access-Control-Request-Headers, Authorization | +| cors.preflight_max_age | int | Duration in seconds. Specifies how long the OPTIONS response is cached by browsers | 600 | + +### Properties in the `messages` block + +The messages property expects a list of elements where each has the following: + +| key | type | description | example value | +|-----------|---------|-------------------------------------------------------------------|----------------------| +| active | boolean | Enables or disables this message | `true` | +| text | string | The message text | `"The message text"` | +| condition | list | omittable; may contain any of the conditions from the table below | | + +| condition | value | description | +|--------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| time_before | ISO 8601 datetime string | message sent if server local time is before given point in time | +| time_after | ISO 8601 datetime string | message sent if server local time is after given point in time | +| api_version | 1 or 2 | message sent if API version requested through matches value | +| api_format | String with output formats ("json", "geojson", "gpx"), comma separated | message sent if requested output format matches value | +| request_service | String with service names ("routing", "matrix", "isochrones", "snap"), comma separated | message sent if requested service matches one of the given names | +| request_profile | String with profile names, comma separated | message sent if requested profile matches one of the given names | +| request_preference | String with preference (weightings for routing, metrics for matrix, rangetype for isochrones) names, comma separated | message sent if requested preference matches one of the given names | + +##### Example: + +``` +messages: + - active: true + text: This message would be sent with every routing bike fastest request + condition: + - request_service: routing + - request_profile: cycling-regular,cycling-mountain,cycling-road,cycling-electric + - request_preference: fastest + - active: true + text: This message would be sent with every request for geojson response + condition: + - api_format: geojson + - active: true + text: This message would be sent with every request on API v1 from January 2020 until June 2050 + condition: + - api_version: 1 + - time_after: 2020-01-01T00:00:00Z + - time_before: 2050-06-01T00:00:00Z + - active: true + text: This message would be sent with every request +``` + +## Configuration via `ors-config.json` + +The "old" configuration method is supported for a while for convenience. The below description is kept as long as * +*openrouteservice** still supports configuration via JSON file, but we do **not** recommend using this configuration +method. + +### ors + +The top level element. + +| key | type | description | example value | +|----------------|--------|-----------------------------------|---------------------------------------| +| services | object | an object comprising the services | [services](#orsservices) | +| logging | object | the logging properties | [logging](#orslogging) | +| system_message | list | List of system message objects | [system messages](#orssystem_message) | + +--- + +### ors.services + +| key | type | description | example value | +|-------------------------|--------|---------------------------------------|--------------------------------------| +| ors.services.routing | object | settings for routing and its profiles | [routing](#orsservicesrouting) | +| ors.services.isochrones | object | settings for isochrones restrictions | [isochrones](#orsservicesisochrones) | +| ors.services.matrix | object | settings for matrix restrictions | [matrix](#orsservicesmatrix) | +| ors.services.snap | object | settings for snap | [matrix](#orsservicesmatrix) | + +--- + +#### ors.services.routing + +| key | type | description | example value | +|------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point. Default value is true. | `true` | +| mode | string | Can be either "normal" or "preparation". If "preparation" then graphs will be built and the service will be shut down afterwards. | `"normal"` | +| description | string | | `"This is a routing file from openrouteservice"` | +| routing_name | string | Specifies the gpx `name` tag that is returned in a gpx response | `"openrouteservice"` | +| sources | list | the osm file to be used, formats supported are `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` | `["heidelberg.osm.gz"]` | +| init_threads | number | The number of threads used to initialize (build/load) graphs. Higher numbers requires more RAM. | `2` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | +| elevation_preprocessed | boolean | Enables or disables reading ele tags for nodes. Default value is false. If enabled, GH's elevation lookup is prevented and all nodes without ele tag will default to 0. Experimental, for use with the ORS preprocessor | `false` | +| profiles | object | | [profiles](#orsservicesroutingprofiles) | + +--- + +##### **ors.services.routing.profiles** + +| key | type | description | example value | +|----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| active | list | Defines a list of active routing profiles. The element name XXX must correspond to a notation "profile-XXX", which is used in the following sections. Can be one or many of `"car"`, `"hgv"`, `"bike-regular"`, `"bike-mountain"`, `"bike-road"`, `"bike-electric"`, `"walking"`, `"hiking"` or `"wheelchair"` | `["car", "bike-regular"]` | +| default_params | object | Set parameters that is applied to every profile by default | [default_params](#orsservicesroutingprofilesdefault_params) | +| profile-XXX | object | Settings that are applied to the specific profile. You may run multiple profiles at once. | [profile-XXX](#orsservicesroutingprofilesprofile-xxx) | + +--- + +##### **ors.services.routing.profiles.default_params** + +| key | type | description | example value | +|---------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| encoder_flags_size | number | The number of bytes used for FlagEncoders | `8` | +| graphs_root_path | string | The root path to a directory for storing graphs | `"../graphs"` | +| elevation_provider | string | The name of an elevation provider. Possible values are multi, cgiar or srtm | `"multi"` | +| elevation_cache_path | string | The path to a directory in which SRTM tiles will be stored | `"elevation_cache"` | +| elevation_cache_clear | boolean | keep elevation data once it has been downloaded | `false` | +| elevation_smoothing | boolean | smooth out elevation data | `false` | +| instructions | boolean | Specifies whether way names will be stored during the import or not | `true` | +| maximum_distance | number | The maximum allowed total distance of a route | `100000` | +| maximum_segment_distance_
with_dynamic_weights | number | The maximum allowed distance between two way points when dynamic weights are used | `50000` | +| maximum_waypoints | number | The maximum number of way points in a request | `50` | +| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `100` | +| maximum_distance_round_trip_routes | number | The maximum allowed total distance of a route for the round trip algo | `100000` | +| maximum_distance_alternative_routes | number | The maximum allowed total distance of a route for the alternative route algo | `100000` | +| maximum_alternative_routes | number | The maximum number of alternative routes in a request | `3` | +| maximum_avoid_polygon_area | number | The maximum allowed total area of a polygon in square kilometers, optional | `200000000` | +| maximum_avoid_polygon_extent | number | The maximum extent (i.e. envelope side length) of a polygon in kilometers, optional | `20000` | +| location_index_resolution | number | The minimum resolution in meters of tiles in the location index. Lower values yield faster queries at a cost of increased memory requirements. Reducing the resolution reduces the lookup radius which can be compensated by increasing `location_index_search_iterations`. Corresponds to GraphHopper's `index.high_resolution` configuration parameter. | `500` (default) | +| location_index_search_iterations | number | The maximum number of iterations performed in coordinates lookup. Higher values yield a broader search area, but might reduce query performance. It only affects the storage lookup but not its layout so changing this parameter does not require rebuilding the location index. Corresponds to GraphHopper's `index.max_region_search` configuration parameter. | `4` (default) | +| maximum_speed_lower_bound | number | Specifies the threshold for the query parameter `maximum_speed`. | `80` (default) | +| interpolate_bridges_and_tunnels | boolean | Interpolate elevation of bridges and tunnels. | `true` (default) | +| preparation | object | ... | [preparation](#orsservicesroutingprofilesdefault_paramspreparation) | +| execution | object | ... | [execution](#orsservicesroutingprofilesdefault_paramsexecution) | `100` + +--- + +##### **ors.services.routing.profiles.default_params.preparation** + +| key | type | description | example value | +|--------------------------|--------|-------------|------------------------------------------------------------------------| +| min_network_size | number | | `200` | +| min_one_way_network_size | number | | `200` | +| methods | object | | [methods](#orsservicesroutingprofilesdefault_paramspreparationmethods) | + +##### **ors.services.routing.profiles.default_params.preparation.methods** + +| key | type | description | example value | +|------|--------|----------------------------------------------------|-------------------------------------------------------------------------| +| ch | object | Settings for preprocessing contraction hierarchies | [ch](#orsservicesroutingprofilesdefault_paramspreparationmethodsch) | +| lm | object | Settings for preprocessing landmarks | [lm](#orsservicesroutingprofilesdefault_paramspreparationmethodslm) | +| core | object | Settings for preprocessing landmarks | [core](#orsservicesroutingprofilesdefault_paramspreparationmethodscore) | + +##### **ors.services.routing.profiles.default_params.preparation.methods.ch** + +| key | type | description | example value | +|------------|---------|-------------|-----------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended"` | + +##### **ors.services.routing.profiles.default_params.preparation.methods.lm** + +| key | type | description | example value | +|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| landmarks | number | Total number of precomputed landmarks, the subset used during the query is set in [`active_landmarks`](#orsservicesroutingprofilesdefault_paramsexecutionmethodslm) | `16` | + +##### **ors.services.routing.profiles.default_params.preparation.methods.core** + +| key | type | description | example value | +|------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| landmarks | number | Total number of precomputed landmarks, the subset used during the query is set in [`active_landmarks`](#orsservicesroutingprofilesdefault_paramsexecutionmethodscore) | `32` | +| lmsets | string | | `"highways,tollways;highways;tollways;country_193;allow_all"` | + +--- + +##### **ors.services.routing.profiles.default_params.execution** + +| key | type | description | example value | +|---------|--------|-------------|----------------------------------------------------------------------| +| methods | object | | [methods](#orsservicesroutingprofilesdefault_paramsexecutionmethods) | + +##### **ors.services.routing.profiles.default_params.execution.methods** + +| key | type | description | example value | +|------|--------|-------------------------------------------------------|-----------------------------------------------------------------------| +| ch | object | Settings for using contraction hierarchies in routing | [ch](#orsservicesroutingprofilesdefault_paramsexecutionmethodsch) | +| lm | object | Settings for using landmarks in routing | [lm](#orsservicesroutingprofilesdefault_paramsexecutionmethodslm) | +| core | object | Settings for using landmarks in routing | [core](#orsservicesroutingprofilesdefault_paramsexecutionmethodscore) | + +##### **ors.services.routing.profiles.default_params.execution.methods.ch** + +| key | type | description | example value | +|-------------------|---------|-------------|---------------| +| disabling_allowed | boolean | | `true` | + +##### **ors.services.routing.profiles.default_params.execution.methods.lm** + +| key | type | description | example value | +|-------------------|---------|--------------------------------------------------|---------------| +| disabling_allowed | boolean | | `true` | +| active_landmarks | number | Number of landmarks used for computing the route | `8` | + +##### **ors.services.routing.profiles.default_params.execution.methods.core** + +| key | type | description | example value | +|-------------------|---------|--------------------------------------------------|---------------| +| disabling_allowed | boolean | | `true` | +| active_landmarks | number | Number of landmarks used for computing the route | `6` | + +--- + +##### **ors.services.routing.profiles.profile-XXX** + +| key | type | description | example value | +|------------|--------|-----------------------------------------------|----------------------------------------------------------------| +| profiles | string | name of the profile when called via the API | `driving-car` | +| parameters | object | the specific profile parameters of an profile | [parameters](#orsservicesroutingprofilesprofile-xxxparameters) | + +##### **ors.services.routing.profiles.profile-XXX.parameters** + +| key | type | description | example value | +|-------------------------------------|---------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| encoder_options | string | | `"turn_costs=true\ |block_fords=false"` [encoder options](#orsservicesroutingprofilesprofile-xxxparametersencoder_options) | +| elevation | boolean | This will enable the elevation information in the response | `true` | +| maximum_distance | number | Maximum distance a route can have in meters | `100000` | +| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `100` | +| maximum_distance_round_trip_routes | number | The maximum allowed total distance of a route for the round trip route algo | `100000` | +| maximum_distance_alternative_routes | number | The maximum allowed total distance of a route for the alternative route algo | `100000` | +| maximum_alternative_routes | number | The maximum number of alternative routes in a request | `3` | +| maximum_avoid_polygon_area | number | The maximum allowed total area of a polygon in square kilometers, optional | `200000000` | +| maximum_avoid_polygon_extent | number | The maximum extent (i.e. envelope side length) of a polygon in kilometers, optional | `20000` | +| ext_storages | object | Controls which external storages are enabled | [external storages](#orsservicesroutingprofilesprofile-xxxparametersext_storages) | +| gtfs_file | string | Only for pt profile: location of gtfs-file used. Can either be a zip-file or the unzipped folder. | `"src/test/files/vrn_gtfs_cut.zip"` | + +##### **ors.services.routing.profiles.profile-XXX.parameters.encoder_options** + +| key | type | description | example value | +|--------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| +| problematic_speed_factor | number | For wheelchair profile only! Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such ways | `problematic_speed_factor=0.7` | +| preferred_speed_factor | number | For wheelchair profile only! Travel speeds on edges classified as preferrable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such ways | `preferred_speed_factor=1.2` | + +##### **ors.services.routing.profiles.profile-XXX.parameters.ext_storages** + +| key | type | description | example value | +|------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| WayCategory | object | Returns the way category in the route response, Compatible for any profile type | `{}` | +| WaySurfaceType | object | Returns the way surface in the route response, Compatible for any profile type | `{}` | +| HillIndex | object | Returns the ascent/descent in the route response, Compatible for any profile type | `{}` | +| TrailDifficulty | object | Returns the trail difficulty in the route response, Compatible for profile-hiking | `{}` | +| RoadAccessRestrictions | object | RoadAccessRestrictions are where roads are restricted to certain vehicles to certain circumstances, e.g. access=destination. The use_for_warnings parameter tells the ors that this storage can be used for generating warning messages in the route response. For RoadAccessRestrictions, this means that whenever a route goes over a way which has some restrictions, a warning message will be delivered with the response and the roadaccessrestrictions extra info automatically added. | `{ use_for_warnings: true }` | +| Wheelchair | object | Compatible for wheelchair | `{ KerbsOnCrossings: "true" }` | +| OsmId | object | Returns the OsmId of the way, Compatible for wheelchair | `{}` | +| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible for any profile type | [Borders](#orsservicesroutingprofilesprofile-xxxparametersext_storagesborders) | + +##### **ors.services.routing.profiles.profile-XXX.parameters.ext_storages.Borders** + +| key | type | description | example value | +|-------------|--------|-----------------------------------------------------------------------------------------------------|----------------------------| +| boundaries | string | The path to a file containing geojson data representing the borders of countries | `'borders.geojson.tar.gz'` | +| ids | string | Path to a csv file containing a unique id for each country, its local name and its english name | `'ids.csv'` | +| openborders | string | Path to a csv file contianing pairs of countries where the borders are open (i.e. Schengen borders) | `'openborders.csv'` | + +--- + +#### ors.services.isochrones + +| key | type | description | example value | +|------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| maximum_range_distance | list | Possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile | `[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]` | +| maximum_range_time | list | | `[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]` | +| maximum_intervals | number | Maximum number of intervals/isochrones computed for each location | `10` | +| maximum_locations | number | Maximum number of locations in one request | `2` | +| allow_compute_area | number | Speficies whether area computation is allowed | `true` | + +##### **ors.services.isochrones.fastisochrones** + +| key | type | description | example value | +|------------------------|------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| +| maximum_range_distance | list | Possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile | `[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]` | +| maximum_range_time | list | | `[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]` | + +##### **ors.services.isochrones.fastisochrones.profiles.default_params** + +| key | type | description | example value | +|--------------|---------|----------------------------------------------------------|--------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| maxcellnodes | number | Maximum number of nodes allowed in single isochrone cell | `5000` | + +--- + +#### ors.services.matrix + +| key | type | description | example value | +|-------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| maximum_routes | number | Maximum amount of routes the matrix should compute. E.g. `2500` could be a 50x50 matrix or 1x2500 matrix | `2500` | +| maximum_routes_flexible | number | Maximum amount of routes for using custom profiles that do not support contraction hierarchies | `25` | +| maximum_search_radius | number | Maximum allowed distance between the requested coordinate and a point on the nearest road. The value is measured in meters | `5000` | +| maximum_visited_nodes | number | Maximum allowed number of visited nodes in shortest path computation. This threshold is applied only for Dijkstra algorithm | `100000` | +| allow_resolve_locations | number | Specifies whether the name of a nearest street to the location can be resolved or not. Default value is true | `true` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | + +--- +#### ors.services.snap + +| key | type | description | example value | +|-------------------------|---------|----------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | + +--- + +#### ors.logging + +| key | type | description | example value | +|------------|---------|-----------------------------------------------------------------|------------------------| +| enabled | boolean | Enables or disables the end-point (default: true) | `true` | +| level_file | string | Can be either `DEBUG_LOGGING.json` or `PRODUCTION_LOGGING.json` | `"DEBUG_LOGGING.json"` | +| location | string | Location of the logs | `"/var/log/ors"` | +| stdout | boolean | | `true` | + +--- + +#### ors.system_message + +Array of message objects where each has + +| key | type | description | example value | +|-----------|---------|-------------------------------------------------------------------|----------------------| +| active | boolean | Enables or disables this message | `true` | +| text | string | The message text | `"The message text"` | +| condition | object | omittable; may contain any of the conditions from the table below | | + +| condition | value | description | +|--------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| time_before | ISO 8601 datetime string | message sent if server local time is before given point in time | +| time_after | ISO 8601 datetime string | message sent if server local time is after given point in time | +| api_version | 1 or 2 | message sent if API version requested through matches value | +| api_format | String with output formats ("json", "geojson", "gpx"), comma separated | message sent if requested output format matches value | +| request_service | String with service names ("routing", "matrix", "isochrones"), comma separated | message sent if requested service matches one of the given names | +| request_profile | String with profile names, comma separated | message sent if requested profile matches one of the given names | +| request_preference | String with preference (weightings for routing, metrics for matrix, rangetype for isochrones) names, comma separated | message sent if requested preference matches one of the given names | + +##### Example: + +``` +system_message: [ + { + active: true, + text: "This message would be sent with every routing bike fastest request. E.g. 'The fastest weighting for cycling profiles is deprecated, use recommended weighting instead. API will be kept for compatibility until release of version 7.0.0'", + condition: { + "request_service": "routing", + "request_profile": "cycling-regular,cycling-mountain,cycling-road,cycling-electric", + "request_preference": "fastest" + } + }, + { + active: true, + text: "This message would be sent with every request for geojson response.", + condition: { + "api_format": "geojson" + } + }, + { + active: true, + text: "This message would be sent with every request on API v1 from January 2020 until June 2050. E.g. 'The V1 API is deprecated. You should switch to using the V2 API.'", + condition: { + "api_version": "1", + "time_after": "2020-01-01T00:00:00Z", + "time_before": "2050-06-01T00:00:00Z" + } + }, + { + active: true, + text: "This message would be sent with every request. E.g. 'Scheduled downtime due to version upgrade on March 15th 2020, 12:00 AM CET for approx. 3 hours.'" + } +] +``` diff --git a/docs/versions/v7.1.1/installation/Installation-and-Usage.md b/docs/versions/v7.1.1/installation/Installation-and-Usage.md new file mode 100644 index 0000000000..4683fed260 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Installation-and-Usage.md @@ -0,0 +1,30 @@ +# Installation and Usage + +## Installation via Docker + +We suggest using docker to install and launch openrouteservice backend. In short, run the following commands will get everything done. + +```bash +wget https://raw.githubusercontent.com/GIScience/openrouteservice/master/docker-compose.yml +docker compose up +``` + +This will pull the latest release version of openrouteservice from dockerhub and start it up using an example setup and the provided test OSM file. +You can also modify the configuration and source file settings to match your needs. For more details, check the [Running with Docker](Running-with-Docker)-Section. +More explanation about customization can be found in the [Advanced Docker Setup](Advanced-Docker-Setup) + +## Other Resources + +* [Building from Source](Building-from-Source) +* [System requirements](System-Requirements) +* [Configuration](Configuration) + +## Usage +Openrouteservice offers a set of endpoints for different spatial purposes. They are served with the help of [Tomcat in a java servlet container](https://github.com/GIScience/openrouteservice/blob/master/ors-api/WebContent/WEB-INF/web.xml). By default you will be able to query the services with these addresses: + +- `http://localhost:8080/ors/v2/directions` +- `http://localhost:8080/ors/v2/isochrones` +- `http://localhost:8080/ors/v2/matrix` + +Note, that Tomcat running via maven will use port `8082` by default. + diff --git a/docs/versions/v7.1.1/installation/Opening-Project-in-IntelliJ.md b/docs/versions/v7.1.1/installation/Opening-Project-in-IntelliJ.md new file mode 100644 index 0000000000..2a763abc37 --- /dev/null +++ b/docs/versions/v7.1.1/installation/Opening-Project-in-IntelliJ.md @@ -0,0 +1,9 @@ +# Opening openrouteservice code in IntelliJ + +Though IntelliJ provides functionality to directly clone a repository, the steps below are the general procedure for getting openrouteservice up and running in IntelliJ: +1. Clone the repository into a folder +2. Open IntelliJ and Create a project via File -> New -> Project from Existing Sources +3. Select the "pom.xml" file from the cloned "openrouteservice" folder and click "Open" +4. Click through project settings with "Next" until you reach the page for selecting project SDK. +5. Choose "17" as project SDK and click "Next" +6. Finalize the project import by clicking "Finish" in the last window. diff --git a/docs/versions/v7.1.1/installation/Running-with-Docker.md b/docs/versions/v7.1.1/installation/Running-with-Docker.md new file mode 100644 index 0000000000..9804d2854a --- /dev/null +++ b/docs/versions/v7.1.1/installation/Running-with-Docker.md @@ -0,0 +1,158 @@ +# Running with Docker + +## Install and run openrouteservice with docker + +> For a step by step guide check out [this YouTube video](https://www.youtube.com/watch?v=VQXlbqKArFk) (Thanks a lot SyntaxByte <3). + +Installing the openrouteservice backend service with Docker is quite straightforward. All you need is an OSM extract, e.g. from [Geofabrik](http://download.geofabrik.de), and a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker). + +Use [Dockerhub's hosted Openrouteservice image](https://hub.docker.com/r/openrouteservice/openrouteservice) or build your own image +### Docker scenarios + +There are multiple ways with docker to quickly have a running instance. + + +1. Recommended: Run a specific ors version using `docker compose` + +```bash +# For example for the latest release +git clone https://github.com/GIScience/openrouteservice.git +cd openrouteservice +# Checkout latest version +export LATEST_ORS_RELEASE=$(git describe --tags --abbrev=0); +git checkout $LATEST_ORS_RELEASE +# If the docker folder exists cd into it +cd docker || echo "No docker folder found. Continue with next step." +# Now change the version the docker-compose.yml uses +sed -i='' "s/openrouteservice\/openrouteservice:nightly/openrouteservice\/openrouteservice:$LATEST_ORS_RELEASE/g" docker-compose.yml +sed -i='' "s/openrouteservice\/openrouteservice:latest/openrouteservice\/openrouteservice:$LATEST_ORS_RELEASE/g" docker-compose.yml +# Run docker compose with +docker compose up -d +``` + +2. Run nightly using `docker compose` + +```bash +# For nightly builds +wget https://raw.githubusercontent.com/GIScience/openrouteservice/master/docker-compose.yml +docker compose up -d +``` + +3. `docker run` for ors versions >= 6.8.2 + +```bash +# create directories for volumes to mount as local user +mkdir -p docker/conf docker/elevation_cache docker/graphs docker/logs/ors docker/logs/tomcat +docker run -dt -u "${UID}:${GID}" \ + --name ors-app \ + -p 8080:8080 \ + -v $PWD/docker/graphs:/home/ors/ors-core/data/graphs \ + -v $PWD/docker/elevation_cache:/home/ors/ors-core/data/elevation_cache \ + -v $PWD/docker/logs/ors:/home/ors/ors-core/logs/ors \ + -v $PWD/docker/logs/tomcat:/home/ors/tomcat/logs \ + -v $PWD/docker/conf:/home/ors/ors-conf \ + #-v $PWD/your_osm.pbf:/home/ors/ors-core/data/osm_file.pbf \ + #-e "BUILD_GRAPHS=True" \ + -e "JAVA_OPTS=-Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g" \ + -e "CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost" \ + openrouteservice/openrouteservice:latest +``` + +4. `docker run` for ors versions <= 6.8.1 + +```bash +# create directories for volumes to mount as local user +mkdir -p docker/conf docker/elevation_cache docker/graphs docker/logs/ors docker/logs/tomcat +docker run -dt -u "${UID}:${GID}" \ + --name ors-app \ + -p 8080:8080 \ + -v $PWD/docker/graphs:/ors-core/data/graphs \ + -v $PWD/docker/elevation_cache:/ors-core/data/elevation_cache \ + -v $PWD/docker/logs/ors:/home/ors/ors-core/logs/ors \ + -v $PWD/docker/logs/tomcat:/home/ors/tomcat/logs \ + -v $PWD/docker/conf:/ors-conf \ + #-v $PWD/your_osm.pbf:/ors-core/data/osm_file.pbf \ + #-e "BUILD_GRAPHS=True" \ + -e "JAVA_OPTS=-Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g" \ + -e "CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost" \ + openrouteservice/openrouteservice:v6.8.1 +``` + +### Docker configuration + +**What you get** + +All the above scenarios will: + +1. Pull the openrouteservice docker image from dockerhub and start a container named `ors-app` +2. Launch the openrouteservice service on port `8080` within a tomcat running in that container, available at the address `http://localhost:8080/ors`. +3. A local `./docker` folder containing the files used and produced by openrouteservice for easy access. Most relevant is `./docker/conf/ors-config.yml` controlling ORS behaviour, and the test OSM data file `/home/ors/ors-core/data/osm_file.pbf` of Heidelberg and surroundings. + +**Customization** + +Once you have a built image you can decide to start a container with different settings, e.g. changing the active profiles or other settings. To run ORS with a custom configuration, modify the `./docker/conf/ors-config.yml` to your needs, and restart the container. You can obviously also modify the volume mappings in the `docker-compose.yml` to your needs. + +Old ORS configuration files in JSON format are deprecated. If you have a custom `ors-config.json` file from a previous installation we strongly recommend to migrate to the new YAML format. For the transitional period ORS allows the use of old format JSON files placed at `./docker/conf/ors-config.json`. All settings in such a file, if present, will override settings in the proper YAML format. + +If you changed the OSM file after the first container start, don't forget to set the environment variable `BUILD_GRAPHS=True` (see comment in dockerfile or examples above) to force a rebuild of the graph(s) (or delete the contents of the `./docker/graphs` folder, which is the same thing). + +***UID*** + +If you need to change the UID the ors is running with, you can use these variables: +```bash +# set it explicitly to 1001 +ORS_UID=1001 ORS_GID=1001 docker compose up -d + +# or set it to the current user +ORS_UID=${UID} ORS_GID=${GID} docker compose up -d +``` + +***Volumes*** + +There are some important directories one might want to preserve on the host machine, to survive container regeneration. These directories should be mapped as volumes. + +- `/home/ors/ors-core/data/graphs`: Contains the built graphs after ORS intialized. +- `/home/ors/ors-core/data/elevation_cache`: Contains the CGIAR elevation tiles if elevation was specified. +- `/home/ors/ors-core/logs/ors`: Contains the ORS logs. +- `/home/ors/tomcat/logs`: Contains the Tomcat logs. +- `/home/ors/ors-conf`: Contains the `ors-config.json` which is used to control ORS. +- `/home/ors/ors-core/data/osm_file.pbf`: The OSM file being used to generate graphs. + +Look at the [`docker-compose.yml`](https://github.com/GIScience/openrouteservice/blob/master/docker-compose.yml) for examples. + +***Environment variables*** + +- `BUILD_GRAPHS`: Forces ORS to rebuild the routings graph(s) when set to `True`. Useful when another PBF is specified in the Docker volume mapping to `/home/ors/ors-core/data/osm_file.pbf` +- `JAVA_OPTS`: Custom Java runtime options, such as `-Xms` or `-Xmx` +- `CATALINA_OPTS`: Custom Catalina options + +Specify either during container startup or in `docker-compose.yml`. + +***Build arguments*** + +When building the image, the following arguments are customizable: + +- `ORS_CONFIG`: Can be changed to specify the location of a custom `ors-config.json` file. Default `./ors-api/src/main/resources/ors-config.json`. +- `OSM_FILE`: Can be changed to point to a local custom OSM file. Default `./ors-api/src/test/files/heidelberg.osm.gz`. + +**Different OSM file** + +Either you point the build argument `OSM_FILE` to your desired OSM file during building the image. + +Or to change the PBF file when restarting a container: + +1. change the path `/home/ors/ors-core/data/osm_file.pbf` is pointing to your new PBF +2. set the `BUILD_GRAPHS` variable to `True` + +E.g. +`docker run -d -p 8080:8080 -e BUILD_GRAPHS=True -v ./data/andorra-latest.osm.pbf:/home/ors/ors-core/data/osm_file.pbf ors-app` + +It should be mentioned that if your dataset is very large, it may be necessary to adjust the `-Xmx` parameter of `JAVA_OPTS` environment variable. A good rule of thumb is to give Java 2 x file size of the PBF **per profile**. + +Note, `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` file format are supported as OSM files. + +**Checking** + +By default the service status is queriable via the `http://localhost:8080/ors/v2/health` endpoint. When the service is ready, you will be able to request `http://localhost:8080/ors/v2/status` for further information on the running services. + +If you use the default dataset you will be able to request `http://localhost:8080/ors/v2/directions/foot-walking?start=8.676581,49.418204&end=8.692803,49.409465` for test purposes. diff --git a/docs/versions/v7.1.1/installation/System-Requirements.md b/docs/versions/v7.1.1/installation/System-Requirements.md new file mode 100644 index 0000000000..f30cb07211 --- /dev/null +++ b/docs/versions/v7.1.1/installation/System-Requirements.md @@ -0,0 +1,28 @@ +# System Requirements + +When running openrouteservice, by far the biggest consideration that needs to be made is the amount of RAM that is available. Smaller areas such as Baden-Württemberg in Germany can run happily on a mid range system, but for larger areas you need more RAM. For example, in the openrouteservice infrastructure, each profile for the planet is running on a 128GB machine. Anything less than that and you will run out of memory during the build process. + +The main things that affect the amount of RAM needed are: +* The size of the data being loaded (OSM data) +* The profile being built (bike and pedestrian need more space than driving profiles) +* The routing optimisations (having the optimised routing algorithms needs more RAM) +* Elevation (using elevation needs the elevation data to also be loaded into RAM, so the larger the geographic area, the more RAM is needed for elevation) +* Extra info (Each profile can have extra info calculated, each of these requires RAM for storage). + +As a guide, you can look at the size of OSM data extracts as a rough guide as to how much RAM you would need. [Geofabrik](https://download.geofabrik.de) provides a number of these extracts along with the file sizes of the pbf files. The planet file is around 50GB and for bike and pedestrian profiles, this needs around 100-105GB RAM. Germany is around 3GB and can normally be built on a reasonable system with around 8GB RAM, and Baden-Württemberg is 450MB which can be built on a machine with around 2-4GB RAM. In general though, having more RAM also speeds up the build process as less garbage collection actions need to be taken, and you should also be aware of any other services running outside of openrouteservice that consume RAM on the machine. + +## Memory mapping in large builds +If you are running a large build (e.g. a planet file) then you may need to increase the number of memory mappings. You only need to do this on the host machine as this value is used by the Docker containers running on it aswell. To do this, go into the system configuration file with `sudo nano /etc/sysctl.conf` and add the following line to the bottom of the file: + +```sh +vm.max_map_count=81920 +``` + +The usual sign that you need to do this change is if you see something similar to the following in your logs: + +```sh +# There is insufficient memory for the Java Runtime Environment to continue. +# Native memory allocation (mmap) failed to map 16384 bytes for committing reserved memory. +# An error report file with more information is saved as: +# /ors-core/hs_err_pid128.log +``` diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/index.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/index.md new file mode 100644 index 0000000000..802440207b --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/index.md @@ -0,0 +1,147 @@ +# Extra Info + +When requesting routes, there are a number of "extra info" items that can be requested to give you more information about the route. +This info could be things like the road surface, track type, or OpenStreetMap way ID. +The list below details which extra info items are available for each profile in the routing provided by https://api.openrouteservice.org. + +## Specify Extra Info in Request + +The desired extra info can be specified in the request body parameter `extra_info`: + +```json +"extra_info": [ "steepness", "waytype"] +``` + +The following table lists the possible values for the request as well as the keys and possible values in the directions response: + +| Request Value in `extra_info` | Description | Key in Response `$.routes[*].extras` | Response Values | +|:-----------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------|--------------------------------------------------------------| +| steepness | Provides information about how steep parts of the route are | `steepness` | [Steepness IDs](steepness.md) | +| suitability | How suitable the way is based on characteristics of the route and the profile | `suitability` | 1 (unsuitable) - 10 (very suitable) | +| surface | The surface covering along the route | `surface` | [Surface IDs](surface.md) | +| waycategory | Specific categories of parts of the route (tollways, highways, fords etc.) | `waycategory` | [Category IDs](waycategory.md) | +| waytype | Types of roads and paths that are used in the route | `waytypes`¹ | [Type IDs](waytype.md) | +| tollways | Any tollways that the route crosses. Whether a way is marked as [tollway](https://wiki.openstreetmap.org/wiki/Key:toll) depends on `profile` | `tollways` | 0 (no tollway) or 1 (tollway) | +| traildifficulty | The difficulty of parts of the way based on sac or mountain bike scales | `traildifficulty` | [Difficulty IDs](trail-difficulty.md) | +| osmid | The [OpenStreetMap way IDs](https://wiki.openstreetmap.org/wiki/Elements#id) of the ways the route uses | `osmId`¹ | | +| roadaccessrestrictions | Information about ways that may have access restrictions (e.g. private roads, destination only) | `roadaccessrestrictions` | [Restrictions IDs](road-access-restrictions.md) | +| countryinfo | Which country parts of the way lies in | `countryinfo` | [Country IDs](../../../../technical-details/country-list.md) | +| green | How "green" the parts of the route are (influenced by things like number of trees, parks, rivers etc.) | `green` | 0 (minimal green-space) - 10 (a lot of green-space) | +| noise | How noisy the parts of the route are (influenced by things like proximity to highways) | `noise` | 0 (quiet) - 10 (noisy) | +| shadow² | How sunny the parts of the route are are | `shadow` | 0 (completely in the shadow) - 10 (completely in the sun) | +| csv² | Experimental feature: Generic extra information from provided csv file(s) | `csv` | custom values | + +*¹ Note the different keys in request and response!* + +*² No data available in the public openrouteservice hosted by HeiGIT* + + +## Extra Info Availability + +Some values are not available in all routing profiles: + +| | steepness | suitability | surface | waycategory | waytype | tollways | traildifficulty | osmid | roadaccessrestrictions | countryinfo | green | noise | shadow | +|:-----------------|:---------:|:-----------:|:-------:|:-----------:|:-------:|:--------:|:---------------:|:-----:|:----------------------:|:-----------:|:-----:|:-----:|:------:| +| driving-car | x | x | x | x | x | x | x | | x | x | | | | +| driving-hgv | x | x | x | x | x | x | x | | x | x | | | | +| cycling-regular | x | x | x | x | x | | x | | | | | | | +| cycling-mountain | x | x | x | x | x | | x | | | | | | | +| cycling-road | x | x | x | x | x | | x | | | | | | | +| cycling-electric | x | x | x | x | x | | x | | | | | | | +| foot-walking | x | x | x | x | x | | x | | | | x | x | x | +| foot-hiking | x | x | x | x | x | | x | | | | x | x | x | +| wheelchair | x | x | x | x | x | | x | x | | | | | | + + +## Extra Info in Responses + +The requested extra information can be found in the directions response (JSON endpoints) in the node + +```jsonpath +$.routes[*].extras +``` + +of type object. Each requested extra_info is represented as a nested object entry with the requested value as key, e.g. `steepness`. +Note that some keys in the `extras` object are different from the requested values, see the table above! + +Here one example: + +```json +"extras": { + "waytypes": { + "values": [ + [ + 0, + 17, + 3 + ], + [ + 17, + 19, + 1 + ], + [ + 19, + 20, + 3 + ] + ], + "summary": [ + { + "value": 3, + "distance": 1285.2, + "amount": 93.93 + }, + { + "value": 1, + "distance": 83, + "amount": 6.07 + } + ] + }, + "steepness": { + "values": [ + [ + 0, + 20, + 0 + ] + ], + "summary": [ + { + "value": 0, + "distance": 1368.2, + "amount": 100 + } + ] + } +} +``` + +The values of each entry have the same structure: Objects with the entries `values` and `summary`: + +### `values` + +A list of integer arrays with length 3 representing a contiguous section of the calculated route with the same value of the requested information type. +The three values of each list have the following semantics: + +1. Index of the way point starting the section +2. Index of the way point at the end of the section +3. Value of the extra info measure (waytype, steepness etc.) for this section + +In the example above, the calculated route has three sections with different waytypes: + +* waypoints 0-17: waytype=3 +* waypoints 17-19: waytype=1 +* waypoints 19-20: waytype=3 + +and only one section (i.e. the whole route) from waypoint 0-20 with steepness=0. + +### `summary` + +A list of objects with the entries `value`, `distance`, `amount` summarizing the +total length (`distance`) and relative length (`amount`) of all segments with a given `value` +of the extra info unit. + +In the example above, all sections with waytype=3 have a summarized length of 1285.2 m +which is 93.93% of the calculated route and 100% of the route have steepness=0. diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/road-access-restrictions.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/road-access-restrictions.md new file mode 100644 index 0000000000..14d66d9c27 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/road-access-restrictions.md @@ -0,0 +1,22 @@ +# Road Access Restrictions + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.roadaccessrestrictions.values +``` + +Provides information about possible restrictions on roads. +Explanation of the values can be found in the [list of possible values in the OSM Wiki](https://wiki.openstreetmap.org/wiki/Key:access) + +| Value | Encoding | +|:-----:|:---------------------------------:| +| 0 | None (there are no restrictions) | +| 1 | No | +| 2 | Customers | +| 4 | Destination | +| 8 | Delivery | +| 16 | Private | +| 32 | Permissive | + +[//]: # (keep in sync with org.heigit.ors.routing.graphhopper.extensions.AccessRestrictionType.class) \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/steepness.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/steepness.md new file mode 100644 index 0000000000..a95c30aef1 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/steepness.md @@ -0,0 +1,23 @@ +# Steepness + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.steepness.values +``` + +| Value | Encoding | +|:-----:|-------------------:| +| -5 | >=16% decline | +| -4 | 10% - <16% decline | +| -3 | 7% - <10% decline | +| -2 | 4% - <7% decline | +| -1 | 1% - <4% decline | +| 0 | 0% - <1% incline | +| 1 | 1% - <4% incline | +| 2 | 4% - <7% incline | +| 3 | 7% - <10% incline | +| 4 | 10% - <16% incline | +| 5 | >=16% incline | + +[//]: # (keep in sync with org.heigit.ors.routing.util.SteepnessUtil.getCategory ) \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/surface.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/surface.md new file mode 100644 index 0000000000..d5bc0dfefd --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/surface.md @@ -0,0 +1,39 @@ +# Surface + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.surface.values +``` + +This extra provides info about the [surface](https://wiki.openstreetmap.org/wiki/Key:surface) of the corresponding parts of the route. +The strike-through values have been recently removed. + +| Value | Name | Corresponding value* of [`surface`](https://wiki.openstreetmap.org/wiki/Key:surface)-tag(s) | +|:------:|:----------------:|:-----------------------------------------------------------------------------------------------:| +| 0 | Unknown | | +| 1 | Paved | `paved` | +| 2 | Unpaved | `unpaved`, `woodchips`, `rock`, `rocks`, `stone`, `shells`, `salt` | +| 3 | Asphalt | `asphalt`, `chipseal`, `bitmac`, `tarmac` | +| 4 | Concrete | `concrete`, `cement` | +| ~~5~~ | ~~Cobblestone~~ | | +| 6 | Metal | `metal` | +| 7 | Wood | `wood` | +| 8 | Compacted Gravel | `compacted`, `pebblestone` | +| ~~9~~ | ~~Fine Gravel~~ | | +| 10 | Gravel | `gravel`, `fine_gravel` | +| 11 | Dirt | `dirt`, `earth`, `soil` | +| 12 | Ground | `ground`, `mud` | +| 13 | Ice | `ice`, `snow` | +| 14 | Paving Stones | `paving_stones`, `paved_stones`, `sett`, `cobblestone`, `unhewn_cobblestone`, `bricks`, `brick` | +| 15 | Sand | `sand` | +| ~~16~~ | ~~Woodchips~~ | | +| 17 | Grass | `grass` | +| 18 | Grass Paver | `grass_paver` | + +*) For tags listing multiple values separated by a semicolon `;` only the first value is considered, and for a +given `value` all values of the form `value[:*]` are matched, where the part `[:*]` is optional. For example, all the +three ways tagged with `surface=concrete`, `surface=concrete:plates;asphalt` and `surface=cement`, respectively, would +be categorized as "Concrete". + +[//]: # (keep in sync with org.heigit.ors.routing.graphhopper.extensions.SurfaceType) \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/trail-difficulty.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/trail-difficulty.md new file mode 100644 index 0000000000..0da34f9196 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/trail-difficulty.md @@ -0,0 +1,22 @@ +# Trail Difficulty + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.traildifficulty.values +``` + +This extra provides information about a trails difficulty for [hiking](https://wiki.openstreetmap.org/wiki/Key:sac_scale) as well as for [mountain-biking](https://wiki.openstreetmap.org/wiki/Key:mtb:scale). + +| Value | foot-\* | cycling-\* | +|:-----:|-------------------------------------|-------------| +| 0 | no tag | no tag | +| 1 | sac_scale=hiking | mtb:scale=0 | +| 2 | sac_scale=mountain_hiking | mtb:scale=1 | +| 3 | sac_scale=demanding_mountain_hiking | mtb:scale=2 | +| 4 | sac_scale=alpine_hiking | mtb:scale=3 | +| 5 | sac_scale=demanding_alpine_hiking | mtb:scale=4 | +| 6 | sac_scale=difficult_alpine_hiking | mtb:scale=5 | +| 7 | --- | mtb:scale=6 | + +[//]: # (keep in sync with TrailDifficultyScaleGraphStorageBuilder.getSacScale) \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waycategory.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waycategory.md new file mode 100644 index 0000000000..1284506729 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waycategory.md @@ -0,0 +1,20 @@ +# WayCategory + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.waycategory.values +``` + +The exponential assignment of the values is used for [bit fields](http://eddmann.com/posts/using-bit-flags-and-enumsets-in-java/). One route section may belong to different categories. Hence, a value of ``97`` would indicate a belonging to ``Paved road``, ``Tunnel`` and ``Highway`` (``64`` + ``32`` + ``1`` ). + +| Value | Name | Corresponding tag(s) | +|:-----:|:-----------:|:-------------------------------------------:| +| 0 | No category | | +| 1 | Highway | `highway=motorway`, `highway=motorway_link` | +| 2 | Tollways | `toll*=yes` | +| 4 | Steps | `highway=steps` | +| 8 | Ferry | `route=shuttle_train`, `route=ferry` | +| 16 | Ford | `ford=yes` | + +[//]: # (keep in sync with org.heigit.ors.routing.graphhopper.extensions.storages.builders.WayCategoryGraphStorageBuilder) diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waytype.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waytype.md new file mode 100644 index 0000000000..2d17d82685 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/extra-info/waytype.md @@ -0,0 +1,25 @@ +# WayType + +Value list for the directions response values in + +```jsonpath +$.routes[*].extras.waytype.values +``` + +This extra provides info about the type of the way of the corresponding parts of the route. + +| Value | Name | Corresponding [`highway`](https://wiki.openstreetmap.org/wiki/Key:highway)-tag(s) | +|:-----:|:------------:|:----------------------------------------------------------------------------------:| +| 0 | Unknown | | +| 1 | State Road | `primary`, `primary_link`, `motorway`, `motorway_link`, `trunk`, `trunk_link` | +| 2 | Road | `secondary`, `secondary_link`, `tertiary`, `tertiary_link`, `road`, `unclassified` | +| 3 | Street | `residential`, `service`, `living_street` | +| 4 | Path | `path` | +| 5 | Track | `track` | +| 6 | Cycleway | `cycleway` | +| 7 | Footway | `footway`, `pedestrian`, `crossing` | +| 8 | Steps | `steps` | +| 9 | Ferry | `route=shuttle_train`, `route=ferry` | +| 10 | Construction | `construction` | + +[//]: # (keep in sync with org.heigit.ors.routing.graphhopper.extensions.WayType) diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/geometry-decoding.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/geometry-decoding.md new file mode 100644 index 0000000000..bafdb5df8d --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/geometry-decoding.md @@ -0,0 +1,202 @@ +# Geometry Decoding + +When a response includes a geometry the data might be encoded as single string. This is a so-called [encoded polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). +If no additional elevation data is requested, this can be decoded with a standard polyline decoder, available e.g. from Mapbox or others. + +When you request additional elevation data, this encoded string can not be decoded with a standard polyline decoder. +The reason for that is, that the elevation data is included in the polyline in addition to the latitude and longitude values. +To decode _X,Y_ and _X,Y,Z_ polylines the decoder needs to know whether the geometry has elevation information. +Examples on how to decode _X,Y,Z_ polylines can be found below: + +## Java + +```java +import org.json.JSONArray; + +public class GeometryDecoder { + + private static JSONArray decodeGeometry(String encodedGeometry, boolean inclElevation) { + JSONArray geometry = new JSONArray(); + int len = encodedGeometry.length(); + int index = 0; + int lat = 0; + int lng = 0; + int ele = 0; + + while (index < len) { + int result = 1; + int shift = 0; + int b; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + lat += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + + result = 1; + shift = 0; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + lng += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + + + if(inclElevation){ + result = 1; + shift = 0; + do { + b = encodedGeometry.charAt(index++) - 63 - 1; + result += b << shift; + shift += 5; + } while (b >= 0x1f); + ele += (result & 1) != 0 ? ~(result >> 1) : (result >> 1); + } + + JSONArray location = new JSONArray(); + try { + location.put(lat / 1E5); + location.put(lng / 1E5); + if(inclElevation){ + location.put((float) (ele / 100)); + } + geometry.put(location); + } catch (JSONException e) { + e.printStackTrace(); + } + } + return geometry; + } +} +``` + +## JavaScript + +```js + /** + * Decode an x,y or x,y,z encoded polyline + * @param {*} encodedPolyline + * @param {Boolean} includeElevation - true for x,y,z polyline + * @returns {Array} of coordinates + */ + decodePolyline: (encodedPolyline, includeElevation) => { + // array that holds the points + let points = [] + let index = 0 + const len = encodedPolyline.length + let lat = 0 + let lng = 0 + let ele = 0 + while (index < len) { + let b + let shift = 0 + let result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 // finds ascii + // and subtract it by 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + + lat += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + shift = 0 + result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + lng += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + + if (includeElevation) { + shift = 0 + result = 0 + do { + b = encodedPolyline.charAt(index++).charCodeAt(0) - 63 + result |= (b & 0x1f) << shift + shift += 5 + } while (b >= 0x20) + ele += ((result & 1) !== 0 ? ~(result >> 1) : (result >> 1)) + } + try { + let location = [(lat / 1E5), (lng / 1E5)] + if (includeElevation) location.push((ele / 100)) + points.push(location) + } catch (e) { + console.log(e) + } + } + return points + } +``` + +## Python + +```python +def decode_polyline(polyline, is3d=False): + """Decodes a Polyline string into a GeoJSON geometry. + :param polyline: An encoded polyline, only the geometry. + :type polyline: string + :param is3d: Specifies if geometry contains Z component. + :type is3d: boolean + :returns: GeoJSON Linestring geometry + :rtype: dict + """ + points = [] + index = lat = lng = z = 0 + + while index < len(polyline): + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + lat += (~result >> 1) if (result & 1) != 0 else (result >> 1) + + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + lng += ~(result >> 1) if (result & 1) != 0 else (result >> 1) + + if is3d: + result = 1 + shift = 0 + while True: + b = ord(polyline[index]) - 63 - 1 + index += 1 + result += b << shift + shift += 5 + if b < 0x1F: + break + if (result & 1) != 0: + z += ~(result >> 1) + else: + z += result >> 1 + + points.append( + [ + round(lng * 1e-5, 6), + round(lat * 1e-5, 6), + round(z * 1e-2, 1), + ] + ) + + else: + points.append([round(lng * 1e-5, 6), round(lat * 1e-5, 6)]) + + geojson = {u"type": u"LineString", u"coordinates": points} + + return geojson +``` diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/index.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/index.md new file mode 100644 index 0000000000..cc41a1eefd --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/index.md @@ -0,0 +1,12 @@ +# Directions Service + +The Directions Service calculates routes and directions between two or more locations for different modes of transportation. + +A complete and concise overview of all request parameters and return types can be found in the [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service). +Here, however, a few topics are explained in more detail: + +* The different directions aka routing [requests and return types](requests-and-return-types.md) +* How advanced [Routing Options](routing-options.md) can be defined +* How [Extra Info](extra-info/index.md) like road surface, track type, OpenStreetMap way ID or additional [Route Attributes](route-attributes.md) can be requested +* How geometries in directions responses can be [decoded](geometry-decoding.md) +* How [Instruction Types](instruction-types.md) are encoded in the directions response diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/instruction-types.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/instruction-types.md new file mode 100644 index 0000000000..dd7e7eb9df --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/instruction-types.md @@ -0,0 +1,33 @@ +# Instruction Types + +[//]: # (keep in sync with org.heigit.ors.routing.instructions.InstructionType; PT_ENTER, PT_TRANSFER, PT_EXIT are replaced with street names ) + + +The following table contains the encoding of the instruction types present in the `type`-field of a directions response in a step of a segment of a route. + +JSON-Path in json response: +```jsonpath +$.routes[*].segments[*].steps[*].type +``` + +JSON-Path in geojson response: +```jsonpath +$.features[*].properties.segments[*].steps[*].type +``` + +| Value | Encoding | +|-------|------------------| +| 0 | Left | +| 1 | Right | +| 2 | Sharp left | +| 3 | Sharp right | +| 4 | Slight left | +| 5 | Slight right | +| 6 | Straight | +| 7 | Enter roundabout | +| 8 | Exit roundabout | +| 9 | U-turn | +| 10 | Goal | +| 11 | Depart | +| 12 | Keep left | +| 13 | Keep right | diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/requests-and-return-types.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/requests-and-return-types.md new file mode 100644 index 0000000000..fa94d974ed --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/requests-and-return-types.md @@ -0,0 +1,33 @@ +# Requests and Return Types + +## Direction Requests + +There are four POST directions requests that all accept the same request body and differ only in the result types, specified by the last path parameter: + + POST /v2/directions/{profile} <- returns JSON + POST /v2/directions/{profile}/json + POST /v2/directions/{profile}/geojson + POST /v2/directions/{profile}/gpx + +Additionally, there is one simple GET request that does not allow advanced request options. It returns GeoJSON: + + GET /v2/directions/{profile} <- returns GeoJSON + + +## Return Types + +### JSON + +The **JSON** return type is best suited for further processing. + +### GPX + +The **GPX** return type is an XML dialect from openrouteservice based on the [GPS Exchange Format](https://www.topografix.com/gpx.asp) with an own [XML Schema](https://raw.githubusercontent.com/GIScience/openrouteservice-schema/main/gpx/v2/ors-gpx.xsd). +It is a very old standard for lightweight interchange of GPS data and thus being used by hundreds of software programs and Web services. + +### GeoJSON + +**GeoJSON** is a format for encoding a variety of geographic data structures, see [geojson.org](https://datatracker.ietf.org/doc/html/rfc7946). +It is widely used and can therefore be easily processed or displayed in many applications, e.g. in [QGIS](https://qgis.org/) or on [geojson.io](http://geojson.io/) + +More information about the result types can be found in the [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service). diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/route-attributes.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/route-attributes.md new file mode 100644 index 0000000000..b48d4f8072 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/route-attributes.md @@ -0,0 +1,23 @@ +# Route Attributes + +With the request body parameter `attributes`, additional attributes of route segments can be requested in a directions request: + +```json +"attributes":["avgspeed","detourfactor","percentage"] +``` + +The possible values are: + +| Value | Description | +|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| avgspeed | This value is in _km/h_ and equals the average speed for this way segment after grading and applying factors. | +| detourfactor | This value is a _factor_ and gives the relative length of the segment with regard to the length of the beeline between the start and end point of the route segment. | +| percentage | This value is in _percent_ and gives the segment length in terms of the route length. | + +In the response, the additional attributes can be found in + +```jsonpath +$.routes[*].segments[*].avgspeed +$.routes[*].segments[*].detourfactor +$.routes[*].segments[*].percentage +``` diff --git a/docs/versions/v8.2.0/api-reference/endpoints/directions/routing-options.md b/docs/versions/v8.2.0/api-reference/endpoints/directions/routing-options.md new file mode 100644 index 0000000000..578fba3f8c --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/directions/routing-options.md @@ -0,0 +1,267 @@ +# Routing Options + +With the request body parameter `options`, advanced routing options can be specified for a directions request. + +The `options` parameter is a JSON object, multiple of the here mentioned parameters can be set. +For structure refer to the [examples](#examples). + +::: warning +Some of the options below rely on auxiliary data included in the graph, see [External storages](../../../run-instance/configuration/ors/engine/profiles.md#ext_storages) +::: + +## Available parameters + +### `options.avoid_borders` +String value specifying which borders to avoid. Only for **`driving-*`** profiles. + +| Value | Description | +|----------------|----------------------------------------------| +| `"all"` | for no border crossing | +| `"controlled"` | cross open borders but avoid controlled ones | + +### `options.avoid_countries` +An integer array of country ids to exclude from routing with **`driving-*`** profiles. Can be used together with `"avoid_borders": "controlled"`. +The list of countries and application examples can be found in the [country list](../../../technical-details/country-list.md). + +`"[11,193]"` would exclude Austria and Switzerland. + +### `options.avoid_features` +A string array of features to avoid. The available features are : + +| Feature | Available for | +|------------|---------------------------------------------| +| `highways` | driving-\* | +| `tollways` | driving-\* | +| `ferries` | driving-\*, cycling-\*, foot-\*, wheelchair | +| `fords` | driving-\*, cycling-\*, foot-\* | +| `steps` | cycling-\*, foot-\*, wheelchair | + +### `options.avoid_polygons` +Comprises areas to be avoided for the route. Formatted as [geojson polygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.3) or [geojson multipolygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.6). + +### `options.profile_params` +An object of additional routing parameters for all profiles except `driving-car`: + +#### `options.profile_params.weightings` +Weightings will prioritize specified factors over the shortest path. +The value is an object that can have the following properties: + +* `steepness_difficulty`: Integer specifying the fitness level for **`cycling-*`** profiles. The preferred gradient increases with the value. + + | Value | Fitness level | + |-------|---------------| + | `0` | Novice | + | `1` | Moderate | + | `2` | Amateur | + | `3` | Pro | + +* `green`: Integer value specifying the Green factor for **`foot-*`** profiles. + + | Value | Green factor | + |-------|------------------------------------------------------| + | `0` | normal routing | + | `1` | prefer ways through green areas over a shorter route | + + +* `quiet`: Integer value specifying the Quiet factor for **`foot-*`** profiles. + + | Value | Quiet factor | + |-------|----------------------------------------| + | `0` | normal routing | + | `1` | prefer quiet ways over a shorter route | + +#### `options.profile_params.restrictions` + +[//]: # (see RequestProfileParamsRestrictions) + +An object specifying restrictions for `cycling-*`, `driving-hgv` or `wheelchair`profiles. + +* for `driving-hgv`: + + | Parameter | Type | Description | + |------------|---------|-----------------------------------------------------------------------------------------------------------------------------------| + | `length` | Number | Length restriction in meters. | + | `width` | Number | Width restriction in meters. | + | `height` | Number | Height restriction in meters. | + | `axleload` | Number | Axle load restriction in tons. | + | `weight` | Number | Weight restriction in tons. | + | `hazmat` | Boolean | Specifies whether to use appropriate routing for delivering hazardous goods and avoiding water protected areas. Default is false. | + +* for `wheelchair`: + + | Parameter | Type | Description | + |-----------------------|---------|-----------------------------------------------------------------------------------------------------------------------------| + | `surface_type` | String | Specifies the minimum [surface type](http://wiki.openstreetmap.org/wiki/Key:surface). Default is `"cobblestone:flattened"`. | + | `track_type` | String | Specifies the minimum [quality](http://wiki.openstreetmap.org/wiki/Key:tracktype) of the route. Default is `"grade1"`. | + | `smoothness_type` | String | Specifies the minimum [smoothness](http://wiki.openstreetmap.org/wiki/Key:smoothness) of the route. Default is `"good"`. | + | `maximum_sloped_kerb` | Number | Specifies the maximum height of the sloped kerb in meters. Values are `0.03`, `0.06`(default), `0.1` or `any`. | + | `maximum_incline` | Integer | Specifies the maximum incline as a percentage. `3`, `6`(default), `10`, `15` or `any`. | + | `minimum_width` | Number | Specifies the minimum width of a road in meters. | + +### `options.round-trip` + +An object with specifications of a round-trip: + +| Parameter | Type | Description | +|-----------|---------|----------------------------------------------------------------------------------------------------------| +| `length` | Number | The target length of the route in m (note that this is a preferred value, but results may be different). | +| `points` | Integer | The number of points to use on the route. Larger values create more circular routes. | +| `seed` | Integer | A seed to use for adding randomisation to the overall direction of the generated route (optional). | + +### `options.vehicle_type` +For `profile=driving-hgv` only. +It is needed for **vehicle restrictions** to work (see [tag filtering](../../../technical-details/tag-filtering.md#driving-hgv)). +Possible values: + +* `hgv` +* `bus` +* `agricultural` +* `delivery` +* `forestry` +* `goods` + + + +## Examples + +Some `options` examples in readable and minified JSON form: + +### for `profile=driving-car`: + +```json +{"avoid_features":["ferries","tollways"]} +``` + +### for `profile=cycling-*`: + +```json +{ + "avoid_features": ["steps"], + "profile_params": { + "weightings": { + "steepness_difficulty": 2 + } + }, + "avoid_polygons": { + "coordinates": [ + [ + [ + 8.683223, + 49.41971 + ], + [ + 8.68322, + 49.41635 + ], + [ + 8.68697, + 49.41635 + ], + [ + 8.68697, + 49.41971 + ], + [ + 8.683223, + 49.41971 + ] + ] + ], + "type": "Polygon" + } +} +``` +```json +{"avoid_features":["steps"],"profile_params":{"weightings":{"steepness_difficulty":2}},"avoid_polygons":{"coordinates":[[[8.683223,49.41971],[8.68322,49.41635],[8.68697,49.41635],[8.68697,49.41971],[8.683223,49.41971]]],"type":"Polygon"}} +``` + +### for `profile=foot-*`: + +```json +{ + "avoid_features": ["fords","ferries"], + "profile_params": { + "weightings": { + "green": { + "factor": 0.8 + }, + "quiet": { + "factor": 1.0 + } + } + } +} +``` +```json +{"avoid_features":["fords","ferries"],"profile_params":{"weightings":{"green":{"factor":0.8},"quiet":{"factor":1.0}}}} +``` + +### for `profile=driving-hgv`: + +```json +{ + "avoid_features": ["ferries","tollways"], + "profile_params": { + "restrictions": { + "length": 30, + "width": 30, + "height": 3, + "axleload": 4, + "weight": 3, + "hazmat": true + } + } +} +``` +```json +{"avoid_features":["ferries","tollways"],"profile_params":{"restrictions":{"length":30,"width":30,"height":3,"axleload":4,"weight":3,"hazmat":true}}} +``` + +### for `profile=wheelchair`: + +```json +{ + "avoid_features": ["ferries","steps"], + "profile_params": { + "restrictions": { + "surface_type": "cobblestone:flattened", + "track_type": "grade1", + "smoothness_type": "good", + "maximum_sloped_kerb": 0.06, + "maximum_incline": 6 + } + } +} +``` + +```json +{"avoid_features":["ferries","steps"],"profile_params":{"restrictions":{"surface_type":"cobblestone:flattened","track_type":"grade1","smoothness_type":"good","maximum_sloped_kerb":0.06,"maximum_incline":6}}} +``` + +### Border restrictions + +Examples for routing options object with border restrictions: + +#### _Do not cross country borders at all_ + +```json +{"avoid_borders":"all"} +``` + +#### _Do not cross controlled borders (i.e. USA - Canada) but allow crossing of open borders (i.e. France - Germany)_ + +```json +{"avoid_borders":"controlled"} +``` + +#### _Do not route through Austria or Switzerland_ + +```json +{"avoid_countries": [11,193]} +``` + +#### _Pass open borders but do not cross into Switzerland_ + +```json +{"avoid_borders": "controlled","avoid_countries": [193]} +``` diff --git a/docs/versions/v8.2.0/api-reference/endpoints/elevation/index.md b/docs/versions/v8.2.0/api-reference/endpoints/elevation/index.md new file mode 100644 index 0000000000..eac522cfef --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/elevation/index.md @@ -0,0 +1,12 @@ +# Elevation Service + +:::warning NOTE +This endpoint is not part of the openrouteservice, but of our public API. It is not available when running an own instance of openrouteservice. +::: + +The elevation service is a Flask application which extracts elevation from various elevation datasets for Point or LineString 2D geometries and returns 3D geometries in various formats. +Just like the openrouteservice, the elevation service is also accessible via our public API. + +Details on how to use it can be found in our [API Playground](https://openrouteservice.org/dev/#/api-docs/elevation). + +If you need deeper insights or want to run your own instance, please visit our GitHub project [openelevationservice](https://github.com/GIScience/openelevationservice). \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/export/index.md b/docs/versions/v8.2.0/api-reference/endpoints/export/index.md new file mode 100644 index 0000000000..b87f7ce90d --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/export/index.md @@ -0,0 +1,459 @@ +# Export Endpoint + +:::warning NOTE +This endpoint is not available in the public API, +but you can use it when running an own instance of openrouteservice. +You can easily create requests with the [swagger-ui](../../index.md#swagger-ui). +::: + +Export the base graph for different modes of transport. + +In the request, the desired routing profile is specified as the last path parameter, +a bounding box for the area of interest has to be defined in the request body. + +This is an example requests for a base graph for the profile `driving-car`: +```shell +curl -X 'POST' \ + 'http://localhost:8082/ors/v2/export/driving-car' \ + -H 'accept: application/geo+json' \ + -H 'Content-Type: application/json' \ + -d '{ + "bbox": [ + [ + 8.681495, + 49.41461 + ], + [ + 8.686507, + 49.41943 + ] + ], + "id": "export_request" +}' +``` + +The response contains nodes and edges in the bounding box relevant for this routing profile. +The edge entry `weight` contains the fastest car duration in seconds: + +```json +{ + "nodes": [ + { + "nodeId": 11008, + "location": [ + 8.682782, + 49.417388 + ] + }, + { + "nodeId": 11009, + "location": [ + 8.682461, + 49.417389 + ] + }, + { + "nodeId": 11010, + "location": [ + 8.681794, + 49.417637 + ] + }, + { + "nodeId": 1987, + "location": [ + 8.681674, + 49.416601 + ] + }, + { + "nodeId": 1988, + "location": [ + 8.681532, + 49.418291 + ] + }, + { + "nodeId": 1669, + "location": [ + 8.685746, + 49.415712 + ] + }, + { + "nodeId": 1221, + "location": [ + 8.685382, + 49.417368 + ] + }, + { + "nodeId": 15494, + "location": [ + 8.683159, + 49.419081 + ] + }, + { + "nodeId": 1672, + "location": [ + 8.686424, + 49.417375 + ] + }, + { + "nodeId": 3788, + "location": [ + 8.683666, + 49.414963 + ] + }, + { + "nodeId": 3789, + "location": [ + 8.685888, + 49.415001 + ] + }, + { + "nodeId": 3790, + "location": [ + 8.684803, + 49.414908 + ] + }, + { + "nodeId": 16273, + "location": [ + 8.681976, + 49.418537 + ] + }, + { + "nodeId": 16275, + "location": [ + 8.682777, + 49.417663 + ] + }, + { + "nodeId": 16276, + "location": [ + 8.682465, + 49.417623 + ] + }, + { + "nodeId": 16277, + "location": [ + 8.682592, + 49.417719 + ] + }, + { + "nodeId": 2072, + "location": [ + 8.683596, + 49.417386 + ] + }, + { + "nodeId": 216, + "location": [ + 8.686507, + 49.41943 + ] + }, + { + "nodeId": 219, + "location": [ + 8.681882, + 49.417391 + ] + }, + { + "nodeId": 12891, + "location": [ + 8.683295, + 49.418568 + ] + }, + { + "nodeId": 3360, + "location": [ + 8.68504, + 49.419273 + ] + }, + { + "nodeId": 3506, + "location": [ + 8.682577, + 49.415744 + ] + }, + { + "nodeId": 3507, + "location": [ + 8.683801, + 49.415725 + ] + }, + { + "nodeId": 3508, + "location": [ + 8.683767, + 49.416544 + ] + }, + { + "nodeId": 3510, + "location": [ + 8.68269, + 49.417389 + ] + }, + { + "nodeId": 3511, + "location": [ + 8.682661, + 49.416511 + ] + } + ], + "edges": [ + { + "fromId": 1669, + "toId": 1221, + "weight": 44.655840000000005 + }, + { + "fromId": 3506, + "toId": 3507, + "weight": 21.26352 + }, + { + "fromId": 3507, + "toId": 3506, + "weight": 21.26352 + }, + { + "fromId": 3510, + "toId": 3511, + "weight": 23.4336 + }, + { + "fromId": 3788, + "toId": 3790, + "weight": 19.99776 + }, + { + "fromId": 3790, + "toId": 3789, + "weight": 19.008000000000003 + }, + { + "fromId": 3508, + "toId": 3511, + "weight": 19.22184 + }, + { + "fromId": 3511, + "toId": 3506, + "weight": 20.515680000000003 + }, + { + "fromId": 11010, + "toId": 1988, + "weight": 18.03816 + }, + { + "fromId": 1988, + "toId": 11010, + "weight": 18.03816 + }, + { + "fromId": 3507, + "toId": 3508, + "weight": 21.87696 + }, + { + "fromId": 3508, + "toId": 3507, + "weight": 21.87696 + }, + { + "fromId": 3789, + "toId": 1669, + "weight": 19.117440000000002 + }, + { + "fromId": 1672, + "toId": 1221, + "weight": 18.080640000000002 + }, + { + "fromId": 1221, + "toId": 1672, + "weight": 18.080640000000002 + }, + { + "fromId": 11008, + "toId": 16275, + "weight": 7.34184 + }, + { + "fromId": 16275, + "toId": 11008, + "weight": 7.34184 + }, + { + "fromId": 11009, + "toId": 16276, + "weight": 9.339839999999999 + }, + { + "fromId": 16276, + "toId": 11009, + "weight": 9.339839999999999 + }, + { + "fromId": 11010, + "toId": 16277, + "weight": 14.45232 + }, + { + "fromId": 16277, + "toId": 11010, + "weight": 14.45232 + }, + { + "fromId": 1987, + "toId": 219, + "weight": 21.433200000000003 + }, + { + "fromId": 2072, + "toId": 11008, + "weight": 14.133600000000001 + }, + { + "fromId": 219, + "toId": 1987, + "weight": 21.433200000000003 + }, + { + "fromId": 11008, + "toId": 2072, + "weight": 14.133600000000001 + }, + { + "fromId": 219, + "toId": 11010, + "weight": 6.74016 + }, + { + "fromId": 11010, + "toId": 219, + "weight": 6.74016 + }, + { + "fromId": 219, + "toId": 11009, + "weight": 10.039919999999999 + }, + { + "fromId": 11009, + "toId": 219, + "weight": 10.039919999999999 + }, + { + "fromId": 1221, + "toId": 2072, + "weight": 31.017120000000002 + }, + { + "fromId": 2072, + "toId": 1221, + "weight": 31.017120000000002 + }, + { + "fromId": 12891, + "toId": 1988, + "weight": 18.889488 + }, + { + "fromId": 1988, + "toId": 12891, + "weight": 18.889488 + }, + { + "fromId": 1221, + "toId": 3360, + "weight": 51.17568 + }, + { + "fromId": 15494, + "toId": 3360, + "weight": 33.06288 + }, + { + "fromId": 3508, + "toId": 2072, + "weight": 22.6584 + }, + { + "fromId": 2072, + "toId": 3508, + "weight": 22.6584 + }, + { + "fromId": 3511, + "toId": 1987, + "weight": 17.377920000000003 + }, + { + "fromId": 3507, + "toId": 1669, + "weight": 33.76656 + }, + { + "fromId": 3510, + "toId": 11008, + "weight": 1.59384 + }, + { + "fromId": 11008, + "toId": 3510, + "weight": 1.59384 + }, + { + "fromId": 3510, + "toId": 11009, + "weight": 3.9808799999999995 + }, + { + "fromId": 11009, + "toId": 3510, + "weight": 3.9808799999999995 + }, + { + "fromId": 3360, + "toId": 216, + "weight": 25.802400000000002 + }, + { + "fromId": 3788, + "toId": 3507, + "weight": 20.477040000000002 + }, + { + "fromId": 3507, + "toId": 3788, + "weight": 20.477040000000002 + } + ], + "nodes_count": 26, + "edges_count": 46 +} +``` \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/geocoder/index.md b/docs/versions/v8.2.0/api-reference/endpoints/geocoder/index.md new file mode 100644 index 0000000000..0abdb6423f --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/geocoder/index.md @@ -0,0 +1,17 @@ +# Geocoder Endpoint + +:::warning NOTE +This endpoint is not part of the openrouteservice, but of our public API. It is not available when running an own instance of openrouteservice. +::: + +The Geocoder Endpoint of our public API is served by a [Pelias](https://www.pelias.io) instance. +It resolves geographic coordinates to addresses and vice versa. + +Our public API exposes these endpoints: + +* [Forward Geocode Service](https://openrouteservice.org/dev/#/api-docs/geocode/search/get): In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do this, build a query where the text parameter is set to the item you want to find. +* [Geocode Autocomplete Service](https://openrouteservice.org/dev/#/api-docs/geocode/autocomplete/get): This type-ahead functionality helps users find what they are looking for, without requiring them to fully specify their search term. Typically, the user starts typing and a drop-down list appears where they can choose the term from the list below. +* [Structured Forward Geocode Service](https://openrouteservice.org/dev/#/api-docs/geocode/search/structured/get): Structured geocoding can improve how the items in your query are parsed and interpreted in a search by defining search terms for specific fields like `address`, `postalcode` etc. _(:warning: This endpoint is beta.)_ +* [Reverse Geocode Service](https://openrouteservice.org/dev/#/api-docs/geocode/reverse/get): Reverse geocoding is used for finding places or addresses near a latitude, longitude pair — like clicking on a map to see what's there. + +For more insights please refer to the [Pelias Documentation](https://github.com/pelias/documentation). \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/health/index.md b/docs/versions/v8.2.0/api-reference/endpoints/health/index.md new file mode 100644 index 0000000000..1dd8fbf283 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/health/index.md @@ -0,0 +1,11 @@ +# Health Endpoint + +:::warning NOTE +This endpoint is not available in the public API, but you can use it when running an own instance of openrouteservice. +::: + +The GET request http://localhost:8082/ors/v2/health (host and port might be different) returns the current health or readiness status +of the running instance with two possible values: + +* `not ready`: the openrouteservice instance is still busy with building graphs +* `ready`: all required graphs are computed, the openrouteservice instance is ready to process spatial requests \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/index.md b/docs/versions/v8.2.0/api-reference/endpoints/index.md new file mode 100644 index 0000000000..a0c4729e87 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/index.md @@ -0,0 +1,34 @@ +# Endpoints + +:::warning Hint +Not all endpoints are available in our live API. +But you can use them when hosting your own instance of openrouteservice. +::: + +## Spatial Endpoints + +Openrouteservice offers a set of endpoints for different spatial purposes: + +* [Directions Service](directions/index.md): Get directions for different modes of transport +* [Isochrones Service](isochrones/index.md): Obtain areas of reachability from given locations +* [Matrix Service](matrix/index.md): Obtain one-to-many, many-to-one and many-to-many matrices for time and distance +* [Snapping Service](snapping/index.md): Snap coordinates to the road network + +## Technical Endpoints + +Furthermore, there are technical endpoints that are :warning: _not available_ in our live API: + +* [Export Service](export/index.md): Export the base graph for different modes of transport +* [Health Service](health/index.md): Get information on the health of the running openrouteservice instance +* [Status Service](status/index.md): Get information on the status of the openrouteservice instance + +## Included Services + +There are additional other services we are hosting for convenience, which are :warning: _only_ included in our public API. +They are standalone services that are :warning: _not included_ in a local openrouteservice instance and would need +a separate local installation: + +* [POI Service](poi/index.md): Stand-Alone service from HeiGIT that returns points of interest in the area surrounding a geometry +* [Elevation Service](elevation/index.md): Stand-Alone service from HeiGIT that returns the elevation for point or line geometries +* [Geocoding Service](geocoder/index.md): Third Party Service ([Pelias](https://www.pelias.io)) hosted by HeiGIT that resolves geographic coordinates to addresses and vice versa +* [Optimization Service](optimization/index.md): Third Party Service ([VROOM](https://github.com/VROOM-Project/vroom)) hosted by HeiGIT that optimizes routes for vehicle fleets diff --git a/docs/versions/v8.2.0/api-reference/endpoints/isochrones/index.md b/docs/versions/v8.2.0/api-reference/endpoints/isochrones/index.md new file mode 100644 index 0000000000..dfc8086c79 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/isochrones/index.md @@ -0,0 +1,14 @@ +# Isochrones Endpoint + +The Isochrone Service supports time and distance analyses for one single or multiple locations. +It is possible to specify the isochrone interval or provide multiple exact isochrone range values. +This service allows the same range of profile options as the `/directions` endpoint, +which help you to further customize your request to obtain a more detailed reachability area response. + +The result is a GeoJSON where the isochrone polygons are represented as `features`: + +```jsonpath +$.features +``` + +For an overview of all features of the isochrones endpoint please refer to the [API Playground](https://openrouteservice.org/dev/#/api-docs/isochrones_service). diff --git a/docs/versions/v8.2.0/api-reference/endpoints/matrix/index.md b/docs/versions/v8.2.0/api-reference/endpoints/matrix/index.md new file mode 100644 index 0000000000..c0736b9df3 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/matrix/index.md @@ -0,0 +1,60 @@ +# Matrix Endpoint + +The Matrix Endpoint calculates profile specific distance and time matrices between multiple source and destination positions. + +Besides parameters for the routing profile, the desired metrics (distance or time) and some more (see [API Playground](https://openrouteservice.org/dev/#/api-docs/matrix_service)), +the most important and mandatory content of a matrix request is a list of locations (coordinate tuples), e.g.: + +```json +{ + "locations": [ + [8.66044,49.41571], + [8.67842,49.40664], + [8.68370,49.40854], + [8.69014,49.40778] + ] +} +``` + +To specify, from which to which of these locations the metric should be calculated, the parameters `sources` and `destinations` can be specified in the request: + +```json +"sources": ["0", "1"], +"destinations": ["2", "3"] +``` + +The numbers in both parameter value arrays represent the index of the locations array in the same request. +In the example above, the duration from the first (0) and second (1) location to the third (2) and fourth (3) location will be calculated: + + 0 -> 2 + 0 -> 3 + 1 -> 2 + 1 -> 3 + +In the response, the results are contained in the node `durations`. +Here, the first array contains the duration from the first source (0) to both destinations (2 and 3), +and the second array contains the duration from the second source (1) to both destinations (2 and 3): + +```json + "durations": [ + [ // durations from first source to each destination + 448.82, // 0 -> 2 + 553.01 // 0 -> 3 + ], + [ // durations from second source to each destination + 142.68, // 1 -> 2 + 246.88 // 1 -> 3 + ] + ] +``` + +If `sources` or `destinations` is not specified in the request, each of both defaults to "all locations". +If for example the locations array has 5 entries, +the sources array has only one entry `[0]`, +and `destinations` is missing, then duration are calculated from location 0 to all locations in the location list. + +The first entry in the result `durations` list represents the duration from location 0 to itself and is `0`. + +To specify whether distances or duration (or both) are to be calculated, the `metrics` parameter can be set accordingly. + +For details about all request parameters and the response type, see the [API Playground](https://openrouteservice.org/dev/#/api-docs/matrix_service). diff --git a/docs/versions/v8.2.0/api-reference/endpoints/optimization/index.md b/docs/versions/v8.2.0/api-reference/endpoints/optimization/index.md new file mode 100644 index 0000000000..7ed4f60577 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/optimization/index.md @@ -0,0 +1,12 @@ +# Optimization Service + +:::warning NOTE +This endpoint is not part of the openrouteservice, but of our public API. It is not available when running an own instance of openrouteservice. +::: + +Our public API includes an instance of VROOM, an open-source optimization engine written in C++20 that aim at providing +good solutions to various real-life vehicle routing problems (VRP) within a small computing time. + +Details on how to use it can be found in our [API Playground](https://openrouteservice.org/dev/#/api-docs/optimization). + +If you need deeper insights or want to run your own instance, please visit the GitHub project [VROOM](https://github.com/VROOM-Project/vroom). \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/poi/index.md b/docs/versions/v8.2.0/api-reference/endpoints/poi/index.md new file mode 100644 index 0000000000..c4dc05e0c2 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/poi/index.md @@ -0,0 +1,282 @@ +# Points-Of-Interest (POI) Service + +:::warning NOTE +This endpoint is not part of the openrouteservice, but of our public API. It is not available when running an own instance of openrouteservice. +::: + +The [openpoiservice](https://github.com/GIScience/openpoiservice) is a stand-alone service from HeiGIT that returns +points of interest in the area surrounding a geometry. + +It is a separate flask-based python application and lives in a +separate [GitHub repository](https://github.com/GIScience/openpoiservice), where you can also find more detailed +documentation. + +A complete and concise overview of all request parameters and return types can be found in +the [API Playground](https://openrouteservice.org/dev/#/api-docs/pois). + +## POI categories + +The POI stored in the openpoiservice database are organized in category groups and categories. Below you find tables +containing the related names for the ``category_group_ids`` and the subordinate ``category_ids``. + +### category_group_ids + +Category groups + +| Name | Value | +|:------------------------------------------------------------|:-----:| +| [accommodation](#accommodation-100) | 100 | +| [animals](#animals-120) | 120 | +| [arts_and_culture](#arts-and-culture-130) | 130 | +| [education](#education-150) | 150 | +| [facilities](#facilities-160) | 160 | +| [financial](#financial-190) | 190 | +| [healthcare](#healthcare-200) | 200 | +| [historic](#historic-220) | 220 | +| [leisure_and_entertainment](#leisure-and-entertainment-260) | 260 | +| [natural](#natural-330) | 330 | +| [public_places](#public-places-360) | 360 | +| [service](#service-390) | 390 | +| [shops](#shops-420) | 420 | +| [sustenance](#sustenance-560) | 560 | +| [transport](#transport-580) | 580 | +| [tourism](#tourism-620) | 620 | + +### category_ids + +Categories listed by group + +#### accommodation : 100 + +| Name | Value | +|:---------------|:-----:| +| alpine_hut | 101 | +| apartment | 102 | +| camp_site | 103 | +| caravan_site | 104 | +| chalet | 105 | +| guest_house | 106 | +| hostel | 107 | +| hotel | 108 | +| motel | 109 | +| wilderness_hut | 110 | + +#### animals : 120 + +| Name | Value | +|:----------------|:-----:| +| animal_boarding | 121 | +| animal_shelter | 122 | +| veterinary | 123 | +| pet | 124 | + +#### arts_and_culture : 130 + +| Name | Value | +|:-----------------|:-----:| +| arts_centre | 131 | +| gallery | 132 | +| library | 133 | +| museum | 134 | +| place_of_worship | 135 | +| studio | 136 | + +#### education : 150 + +| Name | Value | +|:----------------|:-----:| +| college | 151 | +| driving_school | 152 | +| kindergarten | 153 | +| language_school | 154 | +| music_school | 155 | +| school | 156 | +| university | 157 | + +#### facilities : 160 + +| Name | Value | | Name | Value | +|:------------------|:-----:|---|:----------------------|-------| +| compressed_air | 161 | | recycling | 172 | +| bench | 162 | | recycling_station | 173 | +| emergency_phone | 163 | | sanitary_dump_station | 174 | +| clock | 164 | | shelter | 175 | +| defibrillator | 165 | | shower | 176 | +| drinking_water | 166 | | table | 177 | +| fire_hydrant | 167 | | telephone | 178 | +| hunting_stand | 168 | | toilets | 179 | +| internet_cafe | 169 | | waste_basket | 180 | +| kneipp_water_cure | 170 | | waste_disposal | 181 | +| post_box | 171 | | water_point | 182 | + +#### financial : 190 + +| Name | Value | +|:-----------------|:-----:| +| atm | 191 | +| bank | 192 | +| bureau_de_change | 193 | + +#### healthcare : 200 + +| Name | Value | +|:-----------------------|:-----:| +| baby_hatch | 201 | +| clinic | 202 | +| dentist | 203 | +| doctors | 204 | +| emergency_access_point | 205 | +| hospital | 206 | +| nursing_home | 207 | +| pharmacy | 208 | +| retirement_home | 209 | +| social_facility | 210 | +| blood_donation | 211 | + +#### historic : 220 + +| Name | Value | | Name | Value | | Name | Value | +|:--------------------|:-----:|---|----------------|-------|---|-------------------|-------| +| aircraft | 221 | | farm | 231 | | optical_telegraph | 241 | +| aqueduct | 222 | | fort | 232 | | pillory | 242 | +| archaeological_site | 223 | | gallows | 233 | | ruins | 243 | +| castle | 224 | | highwater_mark | 234 | | rune_stone | 244 | +| cannon | 225 | | locomotive | 235 | | ship | 245 | +| city_gate | 226 | | manor | 236 | | tomb | 246 | +| citywalls | 227 | | memorial | 237 | | wayside_cross | 247 | +| battlefield | 228 | | milestone | 238 | | wayside_shrine | 248 | +| boundary_stone | 229 | | monastery | 239 | | wreck | 249 | +| building | 230 | | monument | 240 | | | | + +#### leisure_and_entertainment : 260 + +| Name | Value | | Name | Value | | Name | Value | | Name | Value | | Name | Value | +|:--------------------|:-----:|---|----------------|-------|---|---------------|-------|---|---------------|-------|---|---------------|-------| +| adult_gaming_centre | 261 | | fitness_centre | 271 | | picnic_table | 281 | | swimming_area | 291 | | dojo | 301 | +| amusement_arcade | 262 | | garden | 272 | | pitch | 282 | | swimming_pool | 292 | | gambling | 302 | +| beach_resort | 263 | | golf_course | 273 | | playground | 283 | | track | 293 | | nightclub | 303 | +| bandstand | 264 | | hackerspace | 274 | | raceway | 284 | | turkish_bath | 294 | | planetarium | 304 | +| bird_hide | 265 | | horse_riding | 275 | | public_bath | 285 | | water_park | 295 | | social_centre | 305 | +| common | 266 | | ice_ring | 276 | | sauna | 286 | | wildlife_hide | 296 | | spa | 306 | +| dance | 267 | | marina | 277 | | slipway | 287 | | brothel | 297 | | stripclub | 307 | +| dog_park | 268 | | miniature_golf | 278 | | sports_centre | 288 | | casino | 298 | | aquarium | 308 | +| firepit | 269 | | nature_reserve | 279 | | stadium | 289 | | cinema | 299 | | theme_park | 309 | +| fishing | 270 | | park | 280 | | summer_camp | 290 | | dive_centre | 300 | | zoo | 310 | + +#### natural : 330 + +| Name | Value | +|:--------------|:-----:| +| cave_entrance | 331 | +| beach | 332 | +| geyser | 333 | +| hill | 334 | +| peak | 335 | +| rock | 336 | +| saddle | 337 | +| spring | 338 | +| volcano | 339 | +| water | 340 | + +#### public_places : 360 + +| Name | Value | +|:-----------------|:-----:| +| embassy | 361 | +| crematorium | 362 | +| community_centre | 363 | +| courthouse | 364 | +| coworking_space | 365 | +| crypt | 366 | +| fire_station | 367 | +| grave_yard | 368 | +| police | 369 | +| post_office | 370 | +| prison | 371 | +| ranger_station | 372 | +| rescue_station | 373 | +| townhall | 374 | + +#### service : 390 + +| Name | Value | +|:-------------|:-----:| +| beauty | 391 | +| estate_agent | 392 | +| dry_cleaning | 393 | +| glaziery | 394 | +| hairdresser | 395 | +| laundry | 396 | +| massage | 397 | +| photo_booth | 398 | +| tailor | 399 | +| tattoo | 400 | + +#### shops : 420 + +| Name | Value | Name | Value | Name | Value | Name | Value | Name | Value | Name | Value | +|:------------------|:-----:|------------------|-------|---------------------|-------|-----------------------|-------|---------------|-------|-----------------|-------| +| agrarian | 421 | curtain | 441 | e-cigarette | 461 | hifi | 481 | optician | 502 | tiles | 522 | +| alcohol | 422 | cheese | 442 | farm | 462 | houseware | 482 | organic | 503 | tobacco | 523 | +| antiques | 423 | chemist | 443 | fashion | 463 | hunting | 483 | outdoor | 504 | toys | 524 | +| art | 424 | chocolate | 444 | fishing | 464 | jewelry | 485 | paint | 505 | trophy | 525 | +| bag | 425 | clock | 445 | florist | 465 | leather | 486 | pastry | 506 | tyres | 526 | +| bakery | 426 | clocks | 446 | funeral_directors | 466 | locksmith | 487 | perfumery | 507 | variety_store | 527 | +| bed | 427 | clothes | 447 | furniture | 467 | kiosk | 488 | photo | 508 | vending_machine | 528 | +| beverages | 428 | coffee | 448 | games | 468 | kitchen | 489 | pyrotechnics | 509 | video | 529 | +| bicycle | 429 | computer | 449 | garden_centre | 469 | lamps | 490 | radiotechnics | 510 | video_games | 530 | +| books | 430 | confectionery | 450 | garden_furniture | 470 | lottery | 491 | seafood | 511 | watches | 531 | +| boutique | 431 | convenience | 451 | gas | 471 | mall | 492 | second_hand | 512 | weapons | 532 | +| brewing_supplies | 432 | copyshop | 452 | general | 472 | marketplace | 493 | security | 513 | wine | 533 | +| business_machines | 433 | cosmetics | 453 | gift | 473 | medical_supply | 494 | shoes | 514 | | | +| butcher | 434 | dairy | 454 | greengrocer | 474 | mobile_phone | 495 | spices | 515 | | | +| cafe | 435 | deli | 455 | grocery | 475 | model | 496 | sports | 516 | | | +| camera | 436 | department_store | 456 | interior_decoration | 476 | motorcycle | 497 | stationery | 517 | | | +| candles | 437 | doityourself | 457 | hairdresser_supply | 477 | music | 498 | supermarket | 518 | | | +| car | 438 | electrical | 458 | hardware | 478 | musical_instrument | 499 | swimming_pool | 519 | | | +| car_parts | 439 | electronics | 459 | hearing_aids | 479 | nutrition_supplements | 500 | tea | 520 | | | +| carpet | 440 | erotic | 460 | herbalist | 480 | newsagent | 501 | ticket | 521 | | | + +#### sustenance : 560 + +| Name | Value | +|:---------------|:-----:| +| bar | 561 | +| bbq | 562 | +| biergarten | 563 | +| café | 564 | +| drinking_water | 565 | +| fast_food | 566 | +| food_court | 567 | +| ice_cream | 568 | +| pub | 569 | +| restaurant | 570 | + +#### transport : 580 + +| Name | Value | | Name | Value | | Name | Value | +|:-----------------------|:-----:|---|--------------------|-------|---|------------------|-------| +| aerodrome | 581 | | car_sharing | 591 | | parking | 601 | +| aeroport | 582 | | car_wash | 592 | | parking_entrance | 602 | +| bicycle_parking | 583 | | charging_station | 593 | | parking_space | 603 | +| bicycle_rental | 584 | | ev_charging | 594 | | station | 604 | +| bicycle_repair_station | 585 | | ferry_terminal | 595 | | tram_stop | 605 | +| boat_sharing | 586 | | fuel | 596 | | taxi | 606 | +| bus_station | 587 | | halt | 597 | | platform | 607 | +| bus_stop | 588 | | helipad | 598 | | stop_position | 608 | +| car_rental | 589 | | heliport | 599 | | stop_area | 609 | +| car_repair | 590 | | motorcycle_parking | 600 | | station | 610 | + +Note, that `station` appears once as a railway station (604) and once as a public transport station (610). + +#### tourism : 620 + +| Name | Value | +|:--------------|:-----:| +| artwork | 621 | +| attraction | 622 | +| fountain | 623 | +| information | 624 | +| picnic_site | 625 | +| travel_agency | 626 | +| viewpoint | 627 | \ No newline at end of file diff --git a/docs/versions/v8.2.0/api-reference/endpoints/snapping/index.md b/docs/versions/v8.2.0/api-reference/endpoints/snapping/index.md new file mode 100644 index 0000000000..18913491ae --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/snapping/index.md @@ -0,0 +1,81 @@ +# Snapping Endpoint + +The snapping endpoint can be used to snap points to the edges of the street network for a specific means of transportation. + +The endpoint returns a list of points snapped to the nearest edge in the graph as JSON or GeoJSON. +In case an appropriate snapping point cannot be found within the specified search radius, `null` is returned. + +The routing profile has to be specified as path parameter. +The list of points to be snapped has to be specified as parameter `locations` in the request body, +a list or longitude/latitude tuples. +Another required request body parameter is the `radius` in meters. + +The result contains the snapped points in the same order as their origin position in the request. + +In the following example request and result, the first point cannot be snapped within the search radius +and therefore the first entry in the result `locations` is `null`. + +Request: +```shell +curl -X 'POST' \ + 'http://localhost:8082/ors/v2/snap/driving-car/json' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "locations": [ + [ + 8.681495, + 49.51461 + ], + [ + 8.686507, + 49.41943 + ] + ], + "id": "my_request", + "radius": 300 +}' +``` + +Response: +```json +{ + "locations": [ + null, + { + "location": [ + 8.686507, + 49.41943 + ], + "name": "Werderplatz", + "snapped_distance": 0.01 + } + ], + "metadata": { + "attribution": "openrouteservice.org, OpenStreetMap contributors", + "service": "snap", + "timestamp": 1702565781290, + "query": { + "locations": [ + [ + 8.681495, + 49.51461 + ], + [ + 8.686507, + 49.41943 + ] + ], + "profile": "driving-car", + "id": "my_request", + "format": "json", + "radius": 300 + }, + "engine": { + "version": "8.0", + "build_date": "2023-12-07T10:16:51Z", + "graph_date": "2023-12-07T15:04:45Z" + } + } +} +``` diff --git a/docs/versions/v8.2.0/api-reference/endpoints/status/index.md b/docs/versions/v8.2.0/api-reference/endpoints/status/index.md new file mode 100644 index 0000000000..19362251f0 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/endpoints/status/index.md @@ -0,0 +1,102 @@ +# Status Endpoint + +:::warning NOTE +This endpoint is not available in the public API, but you can use it when running an own instance of openrouteservice. +::: + +The GET request http://localhost:8082/ors/v2/status (host and port are dependent on the setup) returns basic information about the running instance: + +* `languages`: available languages +* `engine`: the build date and version of the openrouteservice +* `profiles`: available routing profiles, info about storages and configured limits +* `services`: activated services + +[//]: # (TODO: engine git die ORS version aus, nicht die eigentliche engine version, die wir dann auch im graph management verwenden, oder?) + + +:::details This is an example response: +```json +{ + "languages": [ + "cs", + "cs-cz", + "de", + "de-de", + "en", + "en-us", + "eo", + "eo-eo", + "es", + "es-es", + "fr", + "fr-fr", + "gr", + "gr-gr", + "he", + "he-il", + "hu", + "hu-hu", + "id", + "id-id", + "it", + "it-it", + "ja", + "ja-jp", + "ne", + "ne-np", + "nl", + "nl-nl", + "pl", + "pl-pl", + "pt", + "pt-pt", + "ro", + "ro-ro", + "ru", + "ru-ru", + "tr", + "tr-tr", + "zh", + "zh-cn" + ], + "engine": { + "build_date": "2023-12-15T14:31:27Z", + "version": "8.0" + }, + "profiles": { + "profile 1": { + "storages": { + "WayCategory": { + "gh_profile": "car_ors_fastest_with_turn_costs" + }, + "HeavyVehicle": { + "gh_profile": "car_ors_fastest_with_turn_costs" + }, + "WaySurfaceType": { + "gh_profile": "car_ors_fastest_with_turn_costs" + }, + "RoadAccessRestrictions": { + "gh_profile": "car_ors_fastest_with_turn_costs", + "use_for_warnings": "true" + } + }, + "profiles": "driving-car", + "creation_date": "", + "limits": { + "maximum_distance": 100000, + "maximum_waypoints": 50, + "maximum_distance_dynamic_weights": 100000, + "maximum_distance_avoid_areas": 100000 + } + } + }, + "services": [ + "routing", + "isochrones", + "matrix", + "snap" + ] +} +``` +::: + diff --git a/docs/versions/v8.2.0/api-reference/error-codes.md b/docs/versions/v8.2.0/api-reference/error-codes.md new file mode 100644 index 0000000000..f553fd016e --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/error-codes.md @@ -0,0 +1,134 @@ +# Error Codes + +## HTTP Status Codes + +The following table describes the supported HTTP status codes. + +| HTTP Status Code | Description | +|:----------------:|--------------------------------------------------------------------------------------------------------------------------------------------| +| 200 | Standard response for successfully processed requests. | +| 400 | The request is incorrect and therefore can not be processed. | +| 404 | The end point is not available, or a given request completed successfully but found no results. | +| 405 | The specified HTTP method is not supported. For more details, refer to the Endpoint documentation. | +| 413 | The request is larger than the server is able to process, the data provided in the request exceeds the capacity limit. | +| 500 | An unexpected error was encountered and more detailed internal error code is provided (see [Internal Error Codes](#internal-error-codes)). | +| 501 | Indicates that the server does not support the functionality needed to fulfill the request. | +| 503 | The server is currently unavailable due to overload or maintenance. | + + + +## Internal Error Codes + +The following sections describes the list of possible internal error codes that might be provided by different ORS +Endpoints. + +### Routing API + +[//]: # (keep in sync with org.heigit.ors.routing.RoutingErrorCodes) + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 2000 | Unable to parse JSON request. |x +| 2001 | Required parameter is missing. |x +| 2002 | Invalid parameter format. |x +| 2003 | Invalid parameter value. |x +| 2004 | Parameter value exceeds the maximum allowed limit. | +| 2006 | Unable to parse the request to the export handler. | +| 2007 | Unsupported export format. |x +| 2008 | Empty Element. | +| 2009 | Route could not be found between locations. | +| 2010 | Point was not found. | +| 2011 | Incompatible parameters. | +| 2012 | Unknown parameter. |x +| 2013 | Entry not reached. | +| 2014 | Exit not reached. | +| 2015 | Entry not reached. | +| 2016 | No route between entry and exit found. | +| 2017 | Maximum number of nodes exceeded. | +| 2099 | Unknown internal error. | + +### Isochrones API + +[//]: # (keep in sync with org.heigit.ors.isochrones.IsochronesErrorCodes) + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 3000 | Unable to parse JSON request. | +| 3001 | Required parameter is missing. | +| 3002 | Invalid parameter format. | +| 3003 | Invalid parameter value. | +| 3004 | Parameter value exceeds the maximum allowed limit. | +| 3005 | Requested feature is not supported. | +| 3006 | Unable to parse the request to the export handler. | +| 3007 | Unsupported export format. | +| 3008 | Empty Element. | +| 3011 | Unknown parameter. | +| 3012 | Parameter value exceeds the minimum allowed limit. | +| 3099 | Unknown internal error. | + +### POIs API + +[//]: # (keep in sync with openpoiservice https://github.com/GIScience/openpoiservice/blob/master/openpoiservice/server/api/__init__.py) + +| Error Code | Description | +|:----------:|-----------------------------------------------------| +| 4000 | Invalid JSON object in request. | +| 4001 | Category or category group ids missing. | +| 4002 | Geometry is missing. | +| 4003 | Bounding box and or geojson not present in request. | +| 4004 | Buffer is missing. | +| 4005 | Geometry length does not meet the restrictions. | +| 4006 | Unsupported HTTP method. | +| 4007 | GeoJSON parsing error. | +| 4008 | Geometry size does not meet the restrictions. | +| 4099 | Unknown internal error. | + +### Matrix API + +[//]: # (keep in sync with org.heigit.ors.matrix.MatrixErrorCodes) + +| Error Code | Description | +|:----------:|----------------------------------------------------| +| 6000 | Unable to parse JSON request. | +| 6001 | Required parameter is missing. | +| 6002 | Invalid parameter format. | +| 6003 | Invalid parameter value. | +| 6004 | Parameter value exceeds the maximum allowed limit. | +| 6006 | Unable to parse the request to the export handler. | +| 6007 | Unsupported export format. | +| 6008 | Empty Element. | +| 6010 | Point not found. | +| 6011 | Unknown parameter. | +| 6020 | Maximum number of visited nodes exceeded. | +| 6099 | Unknown internal error. | + +### Export API + +[//]: # (keep in sync with org.heigit.ors.export.ExportErrorCodes) + +| Error Code | Description | +|:----------:|--------------------------------| +| 7000 | Unable to parse JSON request. | +| 7001 | Required parameter is missing. | +| 7002 | Invalid parameter format. | +| 7003 | Invalid parameter value. | +| 7004 | Unknown parameter. | +| 7005 | Mismatched input. | +| 7006 | Unsupported export format. | +| 7099 | Unknown internal error. | + +### Snapping API + +[//]: # (keep in sync with org.heigit.ors.snapping.SnappingErrorCodes) + +| Error Code | Description | +|:----------:|-------------------------------------------------------| +| 8000 | Unable to parse JSON request. | +| 8001 | Required parameter is missing. | +| 8002 | Invalid parameter format. | +| 8003 | Invalid parameter value. | +| 8004 | Parameter value exceeds the maximum configured limit. | +| 8007 | Unsupported export format. | +| 8010 | Point not found. | +| 8011 | Unknown parameter. | +| 8099 | Unknown internal error. | diff --git a/docs/versions/v8.2.0/api-reference/index.md b/docs/versions/v8.2.0/api-reference/index.md new file mode 100644 index 0000000000..62d8f71859 --- /dev/null +++ b/docs/versions/v8.2.0/api-reference/index.md @@ -0,0 +1,44 @@ +# API Reference + +There are different ways to get information about the openrouteservice API. + +As a first starting point best try out our [API Playground](#api-playground). + +The following chapter [Endpoints](endpoints/index.md) contains explanation and examples for some selected topics that might not +be explained sufficiently in the API Playground. +Here, the single endpoints are not completely covered with all their request parameters etc. +But on the other hand, there is also information about endpoints that are not available in our live API, +but e.g. on instances you run or host yourself like [Export](endpoints/export/index.md), [Health](endpoints/health/index.md) and [Status](endpoints/status/index.md). + +If you are developing ORS or running your own instance, you might benefit from the included [Swagger-UI](#swagger-ui). + +## API Playground + +The [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service) is a complete, interactive and concise technical documentation of our live API. +It can also be used to send sample requests to either our live API or an instance of openrouteservice running on your local machine. +Use the form "API Server" on the top left to select and edit "Development Server" if you want to send requests to your local instance: +![Development server usage](../public/playground-select-server.png "Development server usage"){ style="display: block; margin: 0 auto"} + +The responses of your sample requests are visualized on a small map on the bottom right, +but can also be shown as json, table or downloaded as file: +![Example request visualization](../public/playground-map.png "Example request visualization"){ style="display: block; margin: 0 auto"} + +::: warning Hint +If you prefer the swagger-ui you can also use the [swagger editor](https://editor-next.swagger.io/) and load +the full OpenAPI spec file for our API from https://openrouteservice.org/wp-json/ors-api/v1/api-doc/source/V2. +However, some of the displayed endpoints or features won't be accessible with our live API. +::: + +## Swagger-UI + +Local instances of openrouteservice also have an accessible swagger-ui. +This is a way to get an interactive API doc for your current or an older version of openrouteservice: +1. Checkout the source code for the desired version or tag and [run the service locally](../run-instance/index.md). +2. You can then navigate to the swagger-ui hosted by your local instance in your browser: [http://localhost:8082/ors/swagger-ui/index.html](http://localhost:8082/ors/swagger-ui/index.html) +(the port may be different on your local environment). + +:::warning Hint +The swagger-ui is not available on the production ORS instances hosted by HeiGIT. +::: + +![Swagger-UI](../public/swagger-ui.png "Swagger UI") diff --git a/docs/versions/v8.2.0/contributing/backend-documentation.md b/docs/versions/v8.2.0/contributing/backend-documentation.md new file mode 100644 index 0000000000..d56e63812b --- /dev/null +++ b/docs/versions/v8.2.0/contributing/backend-documentation.md @@ -0,0 +1,40 @@ +# Setting up the backend documentation + +The backend documentation is built using [vitepress](https://vitepress.dev/guide/getting-started). + +Requirements: +- [node version 20](https://nodejs.org/en/download) + +## Set up locally + +To run a development version with hot reload locally, run + +```bash +npm install +npm run docs:dev +``` + +To build the static files to `docs/.vitepress/dist` and preview the production version locally, use + +```bash +npm run build-preview +``` + +::: info +For Markdown links to resolve properly in your IDE (e.g. Intellij), right-click the `docs` folder and +mark it as 'Sources Root'. +::: + +## Configuration and Theme + +Configuration of the site (e.g. sidebar, navigation, …) is in `docs/.vitepress/config.js`. +Follow the [vitepress reference](https://vitepress.dev/reference/site-config) for changes to that. + +The custom theme is in `docs/.vitepress/theme`. +See the [vitepress guide](https://vitepress.dev/guide/extending-default-theme) for details. + +## Deployed version + +The documentation is deployed via a GitHub Action in `.github/workflows/deploy-docs.yml` +using [GitHub Pages](https://pages.github.com/) +on [giscience.github.io/openrouteservice](https://giscience.github.io/openrouteservice/). diff --git a/docs/versions/v8.2.0/contributing/contributing-translations.md b/docs/versions/v8.2.0/contributing/contributing-translations.md new file mode 100644 index 0000000000..8b579a7894 --- /dev/null +++ b/docs/versions/v8.2.0/contributing/contributing-translations.md @@ -0,0 +1,50 @@ +# Translations +If you notice anything wrong with translations, or you want to add a new language to the openrouteservice instructions, please add/edit files in the [`ors-engine/src/main/resources/resources/locales`](https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/locales) folder. You can use the [`ors_en.resources`](https://github.com/GIScience/openrouteservice/blob/main/ors-engine/src/main/resources/resources/locales/ors_en-US.resources) file as a template as to what information needs to be present. +As a guide, for each instruction there are two formats - one where there is a named place (i.e. 47 Berliner Straße) and one without. It is important to keep the `{way_name}` tag in the text, but it should be moved to the correct location. +To show openrouteservice what language is being used, you should alter the name of the file to include the ISO identifier (i.e. for Austrian German the filename would be `ors_de_AT.resources`). + +Since the update to the v2 API, we make use of the Spring framework. Because of that, you also need to make a slight modification to a java file that declares what parameters can be passed through to the API. This file is located in [`ors-api/src/main/java/org/heigit/ors/api/APIEnums.java`](https://github.com/GIScience/openrouteservice/blob/main/ors-api/src/main/java/org/heigit/ors/api/APIEnums.java) and the section that needs updating is the `public enum Languages` enum. If (for example) you want to add Polish to the languages, you would also need to add here something like `PL("pl")` to the list where the part in the `("...")` is what would be passed in to the API to select that language. So ultimately you would end up with: +```java +public enum Languages { + public enum Languages { + CS("cs"), + CS_CZ("cs-cz"), + DE("de"), + DE_DE("de-de"), + EN("en"), + EN_US("en-us"), + EO("eo"), + EO_EO("eo-eo"), + ES("es"), + ES_ES("es-es"), + FR("fr"), + FR_FR("fr-fr"), + GR("gr"), + GR_GR("gr-gr"), + HE("he"), + HE_IL("he-il"), + HU("hu"), + HU_HU("hu-hu"), + ID("id"), + ID_ID("id-id"), + IT("it"), + IT_IT("it-it"), + JA("ja"), + JA_JP("ja-jp"), + NE("ne"), + NE_NP("ne-np"), + NL("nl"), + NL_NL("nl-nl"), + PL("pl"), + PL_PL("pl-pl"), + PT("pt"), + PT_PT("pt-pt"), + RO("ro"), + RO_RO("ro-ro"), + RU("ru"), + RU_RU("ru-ru"), + TR("tr"), + TR_TR("tr-tr"), + ZH("zh"), + ZH_CN("zh-cn"); +``` diff --git a/docs/versions/v8.2.0/contributing/index.md b/docs/versions/v8.2.0/contributing/index.md new file mode 100644 index 0000000000..84a2e843e3 --- /dev/null +++ b/docs/versions/v8.2.0/contributing/index.md @@ -0,0 +1,27 @@ +# Contributing + +We are glad that you decided to contribute to the openrouteservice. + +There are plenty of ways to help make it an even better routing service. +Whether you are a Java developer who is interested in fixing +some bugs or adding some new functionality, someone who knows an area well and +can update information in OSM so that openrouteservice can take it into +account, or even someone who speaks different languages and is will to provide +some translations for routing instructions, there will be something that you +can help with. + +Feel free to create an [issue](https://github.com/GIScience/openrouteservice/issues) and label it accordingly. +If your issue regards the openrouteservice maps client on [maps.openrouteservice.org](https://maps.openrouteservice.org) +please use the [corresponding repository](https://github.com/GIScience/ors-map-client/issues). + +## Contributing code + +To help you get started, here is a document describing how to [build openrouteservice from code](../run-instance/building-from-source.md). +We also put together a few [guidelines](https://github.com/GIScience/openrouteservice/blob/main/CONTRIBUTE.md) +to help you in the process and keep the repository clean and tidy. + +## Other ways to contribute + +* [Contributing translations](contributing-translations) +* [Contributing to this documentation](backend-documentation) +* [Updating OpenStreetMap](https://wiki.openstreetmap.org/wiki/Beginners%27_guide) diff --git a/docs/versions/v8.2.0/frequently-asked-questions.md b/docs/versions/v8.2.0/frequently-asked-questions.md new file mode 100644 index 0000000000..b7bd6cf0c2 --- /dev/null +++ b/docs/versions/v8.2.0/frequently-asked-questions.md @@ -0,0 +1,133 @@ +--- +title: FAQ +--- + +# Frequently Asked Questions + +## Why is my ors reporting `Could not find point`? + +This is a frequently encountered error message: +``` +Could not find point 0: 25.3531986 51.5214311 within a radius of 350.0 meters.; +Could not find point 1: 25.3524229 51.4627229 within a radius of 350.0 meters. +``` + +There are three main reasons for this problem, listed in order of most to least common. + +1. If both points are not found you probably just mixed up Lat and Long. Our + API expects coordinates in [lon,lat] order as described in our documentation + (check help button for parameter info). Output is also [lon,lat] as by the + GeoJSON Specification. + +2. The given start and endpoint are further than 350m away from any routable + road. The maximum distance for snapping to road segments in our API is 350m. + This can be customized for local installations via the + `maximum_snapping_radius` and `location_index_resolution` config-parameter. See + [configuration](run-instance/configuration/ors/engine/profiles.md) for details. + +3. The start and endpoint are passed with correct lon,lat-order and are within + 350m of a routable road. This should only happen with a local installation. + Usually, this means that ors is trying to route in an area that graphs have not + been built for. + If routes in Heidelberg(Germany) can be found, the ors is still running on the + default dataset. + +## When does the OSM data update in the openrouteservice? + +The openrouteservice builds its data from the `planet.osm.pbf`-files. According +to [the osm-wiki](https://wiki.openstreetmap.org/wiki/Planet.osm), these files +take two days to build and are updated weekly. + +Since the `planet`-files are rather large (currently over 60GB), there is a bit +of work involved to make sure the download went right and the file is not +corrupted in any way and in fact new. Parts of this process are in the hands of +the OSM, parts are done by the openrouteservice. + +Once the newest `planet`-file is on the openrouteservice-servers, it needs to +be preprocessed before the openrouteservice can start building the graphs used +for routing. + +The build process in itself is [rather +resource-intensive](run-instance/system-requirements.md). It takes roughly two +days for any one of the nine profiles. For the mentioned resource requirements, +this means that it will take roughly a week for all profiles to be re-built. + +Once the graphs are built, the production instances have to load them. Since +this should happen in a low-traffic time slot, it is also scheduled to happen +once per week. + +To sum up: if you change anything in the OSM, it will therefore take roughly a +week until it's included in the `planet`-file. This gets read once a week, the +build takes a week and reloading graphs happens once a week. + +If everything aligns as it should, changes should be reflected in the +openrouteservice within two to three weeks. + +If, however, anything goes wrong anywhere, this will usually mean a delay of at +least a week, assuming it gets noticed and fixed immediately. It is no sign of +concern, if changes are not reflected within a month. + +## I get an Error `Native memory allocation (mmap) failed to map 16384 bytes for committing reserved memory` + +See memory mapping section in [system requirements](run-instance/system-requirements.md#memory-mapping-in-large-builds-with-a-containerized-openrouteservice-instance). + +## Why does routing not work when there is clearly a road? + +There are a lot of reasons why routing is seemingly "wrong" since +roads are there that are not being used. In many cases, this is a data issue more than a routing issue. +A very common occurrence has to do with `barrier=*`-nodes in the OSM. + +This issue most commonly manifests itself in two ways: + +1. Ferries are not taken, although they exist and should be faster/shorter +2. Roads in residential areas are not accessible from the outside. + +In both cases, there might be a node with a `barrier=*`-tag on the roads accessing the ferry port or the residential area. +The corresponding barriers are made to disallow unauthorized access. +Thus, if no more information than `barrier=*` is given, the openrouteservice will not route over them. + +This behaviour is often misinterpreted as _wrong_ since in many cases, the barrier is passable by default or a ticket can be purchased. +While often obvious to a human looking at the map, the openrouteservice can not know that. +Routing over such a barrier would be an assumption that the openrouteservice will not make. + +[A lot](https://wiki.openstreetmap.org/wiki/Key:access#List_of_possible_values) +of [options](https://wiki.openstreetmap.org/wiki/Key:locked) exist to +[enable](https://wiki.openstreetmap.org/wiki/Tag:access%3Ddestination) routing, +but they have to be made in the data, not in the routing engine. + +## Why is the response time for matrix requests in my own instance so much higher than in the live API +Depending on the parameters of your request, the openrouteservice will use +different routing algorithms with different preparations to calculate an +answer. + +For matrix calculations, the ors uses the very fast RPHAST algorithm, which is +based on so-called _Contraction Hierarchies_ (CH for short). While the usage +of CH speeds up matrix calculation by a lot, preparing them is rather costly. +Thus, they are not calculated by default, but have to be turned on manually. +Documentation on how to do that can be found [here](https://giscience.github.io/openrouteservice/run-instance/configuration/ors/engine/profiles#methods-ch). + +If CH have not been prepared, matrix calculation will fall back to the Dijkstra +algorithm, which is way slower and responsible for the slow response. + +## When and how does my quota reset? +When you check our [plans](https://openrouteservice.org/plans/), you'll see +that our endpoints have a daily and a minutely request limit. + +All remaining quota is shown in your [developer dashboard](https://openrouteservice.org/dev/#/home). + +The daily limit is reset after 24h, starting from the first time you request +anything. Thus, your 24h-window might shift over the days. + +As an example, let's look at the `directions` endpoint and its default limit of +2000 requests per day. If you request 1000 directions at 3pm today and try to +request 1500 tomorrow at 10am, the last 500 of those will fail, since your +quota only resets at 3pm tomorrow. After 3pm, you can issue up to 2000 requests +again, but if you do so at 6pm, you'll have to wait until 6pm the day after +tomorrow until you can request any more directions. + +The minutely limit is enforced as a sliding window, meaning that any +consecutive period of 60 seconds may only contain 40 directions requests. + +If you run into the daily limit, you will receive a `403 - Forbidden` HTTP error. +If you run into the minutely limit, you will receive a `429 - Too many requests` HTTP error. +The remaining daily quota can also be checked programmatically, compare the `x-ratelimit-remaining` and the `x-ratelimit-reset` header. diff --git a/docs/versions/v8.2.0/getting-started.md b/docs/versions/v8.2.0/getting-started.md new file mode 100644 index 0000000000..d4630a6995 --- /dev/null +++ b/docs/versions/v8.2.0/getting-started.md @@ -0,0 +1,30 @@ +# Getting started + + +The fastest way to get to the info you are looking for is **the search bar above**. If that doesn't work, the sidebar has you covered: + +* The [API Reference](api-reference/index.md) contains info about openrouteservice's API [endpoints](api-reference/endpoints/index.md) and usage, both for using the [public API](https://openrouteservice.org/dev/#/api-docs) and using locally run instances of openrouteservice. + * [Directions](api-reference/endpoints/directions/index.md) endpoint + * [Isochrones](api-reference/endpoints/isochrones/index.md) endpoint + * [Matrix](api-reference/endpoints/matrix/index.md) endpoint + * [Snapping](api-reference/endpoints/snapping/index.md) endpoint + * [Export](api-reference/endpoints/export/index.md) endpoint _(not available in our live API)_ +* [Run ORS instance](run-instance/index.md) contains all info about setting up the ors locally. + * [System requirements](run-instance/system-requirements) + * [Data](run-instance/data) used by openrouteservice + * [Running with Docker](run-instance/running-with-docker.md) artifact + * [Running JAR](run-instance/running-jar.md) artifact + * [Running WAR](run-instance/running-war.md) artifact + * [Building from Source](run-instance/building-from-source.md) + * [Configuration](run-instance/configuration/index.md) of openrouteservice instances +* [Contributing](contributing/index.md) contains info about contributing to the openrouteservice, the OpenStreetMap and [translations](contributing/contributing-translations) +* [Technical details](technical-details/index.md) contains all sorts of explanation about the internal workings of the openrouteservice. +* [FAQ](frequently-asked-questions) contains answers to frequently asked questions. + +For a more general overview, visit our website at [openrouteservice.org](https://openrouteservice.org). + +For an easy and interactive way to test the api, you can try out the different endpoints instantly and start firing requests at the [API Playground](https://openrouteservice.org/dev/#/api-docs) after obtaining an account and an API key. + +If you spot issues with the documentation, click the link below the page to directly open an issue on GitHub. + +If you have questions that aren't answered here, or you want to provide feedback or point out problems, go to our [Forum](https://ask.openrouteservice.org). diff --git a/docs/versions/v8.2.0/index.md b/docs/versions/v8.2.0/index.md new file mode 100644 index 0000000000..206f18922b --- /dev/null +++ b/docs/versions/v8.2.0/index.md @@ -0,0 +1,34 @@ +--- +title: Home +layout: home +hero: + name: Openrouteservice Backend Documentation - v8.2.0 + tagline: Smart mobility made easy + actions: + - theme: brand + text: Getting Started + link: ./getting-started + - theme: alt + text: API Playground + link: https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post + - theme: alt + text: Contributing + link: ./contributing/ + - theme: alt + text: Reference + link: ./api-reference/ + +features: + - title: Installation + details: Set up your own openrouteservice instance. + linkText: Instructions + link: ./run-instance/ + - title: Data Sources + details: Find all information on the data used by the openrouteservice here. + linkText: Data + link: ./run-instance/data + - title: Latest Changes + details: Check out the latest changes to the openrouteservice. + linkText: CHANGELOG.md + link: https://github.com/GIScience/openrouteservice/blob/main/CHANGELOG.md +--- diff --git a/docs/versions/v8.2.0/public/map-client-isochrones.png b/docs/versions/v8.2.0/public/map-client-isochrones.png new file mode 100644 index 0000000000..a750e65f66 Binary files /dev/null and b/docs/versions/v8.2.0/public/map-client-isochrones.png differ diff --git a/docs/versions/v8.2.0/public/openrouteservice.png b/docs/versions/v8.2.0/public/openrouteservice.png new file mode 100644 index 0000000000..af1325c038 Binary files /dev/null and b/docs/versions/v8.2.0/public/openrouteservice.png differ diff --git a/docs/versions/v8.2.0/public/openrouteservice_dark.png b/docs/versions/v8.2.0/public/openrouteservice_dark.png new file mode 100644 index 0000000000..0f0b5aed1d Binary files /dev/null and b/docs/versions/v8.2.0/public/openrouteservice_dark.png differ diff --git a/docs/versions/v8.2.0/public/ors_fav.png b/docs/versions/v8.2.0/public/ors_fav.png new file mode 100644 index 0000000000..3548419e1e Binary files /dev/null and b/docs/versions/v8.2.0/public/ors_fav.png differ diff --git a/docs/versions/v8.2.0/public/playground-map.png b/docs/versions/v8.2.0/public/playground-map.png new file mode 100644 index 0000000000..28bc90076a Binary files /dev/null and b/docs/versions/v8.2.0/public/playground-map.png differ diff --git a/docs/versions/v8.2.0/public/playground-select-server.png b/docs/versions/v8.2.0/public/playground-select-server.png new file mode 100644 index 0000000000..617667e7aa Binary files /dev/null and b/docs/versions/v8.2.0/public/playground-select-server.png differ diff --git a/docs/versions/v8.2.0/public/swagger-ui.png b/docs/versions/v8.2.0/public/swagger-ui.png new file mode 100644 index 0000000000..5584431c5e Binary files /dev/null and b/docs/versions/v8.2.0/public/swagger-ui.png differ diff --git a/docs/versions/v8.2.0/run-instance/building-from-source.md b/docs/versions/v8.2.0/run-instance/building-from-source.md new file mode 100644 index 0000000000..5965bdcf36 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/building-from-source.md @@ -0,0 +1,263 @@ +# Building from Source + +If you need to customize your openrouteservice instance even further than what is possible by [configuration](configuration/index.md), you might need to make changes to the code. +If you implement features that might be useful for others as well, consider [contributing](../contributing/index.md)! The following instructions are useful to get you set up to start modifying the code. + + +## Prerequisites + +The following documentation assumes you are running an Ubuntu 20.04 system (also generally works with newer Ubuntu versions). Depending on your environment, you might need to adjust certain details. You will also need to make sure to have the following installed: +* [java](https://www.java.com/en/) 17 (or higher) should be available, preferably as default Java environment. +* [maven](https://maven.apache.org/) should be installed on your system. +* [git](https://github.com/git-guides/install-git) should be available on your system if you want to download the source code conveniently. + +## Download source code + +If you have git installed, the easiest way to download the source code is to clone the repository with the following command: + +```shell +git clone https://github.com/GIScience/openrouteservice.git +cd openrouteservice +``` + +This creates a directory named `openrouteservice` containing the downloaded source code. All following instructions will assume you are within that directory. + +If you do not have git installed on your system, you can also download the packed (`.zip` and `.tar.gz`) source code file from the "Assets" section of the desired release from our GitHub [releases](https://github.com/GIScience/openrouteservice/releases) page. Unpack the archive and run the following instructions within the directory you unpacked the source code into. + +## Run source code directly + +You should be able to run the application directly with + +```shell +mvn spring-boot:run +``` + +or in your IDE (see below). This will start openrouteservice on port `8082` with the default configuration `ors-config.yml` in the project root directory +and a small OSM data set from Heidelberg. + +In the [Configuration](configuration/index.md) section you find the options how you can use customised configurations. + + +### Running from within IDE + +[//]: # (TODO: review below here) + +To run the project from within your IDE, you have to: + +1. Open IntelliJ and Create a project via File -> New -> Project from Existing Sources +2. Select the "pom.xml" file from the cloned "openrouteservice" folder and click "Open" +3. Click through project settings with "Next" until you reach the page for selecting project SDK. +4. Choose "17" as project SDK and click "Next" +5. Finalize the project import by clicking "Finish" in the last window. +6. Configure your IDE to run `spring-boot:run` as the maven goal. Now you can run your application directly in IntelliJ. +7. To use a different config file than ors-config.yml in the project directory, you can set the environment variable `ORS_CONFIG_LOCATION=` in your run config. +8. You can run all tests via JUnit. + + +### Running Tests + +Running tests is essential if you change the code. Please always make sure that all tests are passing. Failing test sometimes indicate, that code changes break existing code. If the expected behavior of the application changes, it might also be necessary to change existing tests. For new functionality, new tests should be added. + +It is very convenient to run unit tests (all or just one or some) in the IDE. +You can also run tests with maven on the command line. Here are some examples, checkout the maven documentation for more options. + +```shell +mvn clean test # runs unit tests in all modules +mvn clean test -pl :ors-api # runs unit tests in ors-api +mvn clean test -pl :ors-api -Dtest="APIEnumsTest" # run tests in a single test class +mvn clean test -pl :ors-api -Dtest="APIEnumsTest#testLanguagesEnumCreation" # or a single test method only +``` + +The api tests (in `ors-api/src/test/java/org/heigit/ors/apitests`) are excluded by default. +To include them, add the option `-Papitests`, e.g.: + +```shell +mvn clean verify -Papitests +``` + +If you want to run maven tasks without tests, add the option`-DskipTests`, e.g.: + +```shell +mvn clean package -DskipTests +``` + + +### Integrating GraphHopper + +If you need to make adjustments to our forked and edited [GraphHopper repository](https://github.com/GIScience/graphhopper), follow these steps: + +1. Clone and checkout `ors_4.0` branch: + + ```shell + git clone https://github.com/GIScience/graphhopper.git + cd graphhopper + git checkout ors_4.0 + ``` + +2. Build the project to create the local snapshot. + + ```shell + mvn package + ``` + +3. Change the `ors-engine/pom.xml`: + + ```xml + // [!code ++] + + com.github.GIScience.graphhopper + graphhopper-core + 4.9-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + + + com.github.GIScience.graphhopper + graphhopper-reader-gtfs + 4.9-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + + + com.github.GIScience.graphhopper + graphhopper-map-matching + 4.9-SNAPSHOT + + + com.fasterxml.jackson.dataformat + jackson-dataformat-xml + + + + --> // [!code --] + ``` + +4. Test your new functionality and run all tests after rebasing your feature branch with the latest `main` branch. Adjust tests if necessary. + +5. If successful, create a PR for both [openrouteservice](https://github.com/GIScience/openrouteservice/pulls) and [GraphHopper](https://github.com/GIScience/graphhopper/pulls) against `master` and `ors_4.0` branches, respectively. + + +## Build runnable artifacts + +### Build JAR + +When your source code is set up, you can generate a runnable openrouteservice fat JAR: + +```shell +mvn clean package -PbuildFatJar +``` + +Because JAR is the default, you can also run the command without `-PbuildFatJar`: + +```shell +mvn clean package +``` + +You will find the fat JAR file in `ors-api/target/ors.jar` + +The chapter on [JAR](running-jar.md) artifact explains how to configure and run the JAR file. + + +### Build WAR + +When your source code is set up, you can generate a deployable openrouteservice WAR: + +```shell +mvn clean package -PbuildWar +``` + +You will find the WAR file in `ors-api/target/ors.war` + +The chapter on [WAR](running-war.md) artifact explains how to configure and deploy the WAR file. + + +### Build docker image + +::: tip +This chapter only describes how to _build_ a docker container locally. +Before you _run_ your custom docker image the first time, +please read [running prebuilt images](running-with-docker.md#running-prebuilt-images) +to learn the preconditions and how the dockerized openrouteservice is operated. +::: + +To build a local openrouteservice docker image based on the local (modified) code, +it is convenient to use the docker compose file in the project directory. +When you are in the project directory and run the first time + +```shell +docker compose up +``` + +your local docker image `local/openrouteservice:latest` will be built. If it already exists, the existing image will be used. + +To rebuild the image with docker compose, you can execute + +```shell +docker compose build +``` + +or, of course, you can also use docker directly to build your image: + +```shell +docker build . -t local/openrouteservice +``` + +When building the docker image locally, under the hood `mvn clean package` will be executed, +which compiles you local source code to a fat jar that will be placed in your docker image. + +If you don't want to build locally but instead run the nightly image, +modify the `docker-compose.yml`: + +```yaml +image: local/openrouteservice:latest // [!code --] +image: openrouteservice/openrouteservice:nightly // [!code ++] +``` + diff --git a/docs/versions/v8.2.0/run-instance/configuration/index.md b/docs/versions/v8.2.0/run-instance/configuration/index.md new file mode 100644 index 0000000000..5097f8cc71 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/index.md @@ -0,0 +1,127 @@ +# Configuration + +## File location + +There are two (optional) ways for you to provide openrouteservice the location of a configuration file: +1. Program argument + ```shell + java -jar ors.jar /path/to/ors-config.yml + ``` +2. Environment variable `ORS_CONFIG_LOCATION` + ```shell + export ORS_CONFIG_LOCATION=/path/to/ors-config.yml + java -jar ors.jar + ``` +If both are specified, the program argument wins. + +If no config location is specified, openrouteservice will look for a configuration file `ors-config.yml` in the locations below in that order. +The first existing file is used as configuration. + +| Path | Description | +|:--------------------------------------------|:--------------------------------------------| +| `./ors-config.yml` | Current working directory | +| `~/.config/openrouteservice/ors-config.yml` | User configuration directory | +| `/etc/openrouteservice/ors-config.yml` | Global configuration directory | + +::: tip +At program start openrouteservice reports which configuration file was loaded. +::: + +## File Formats + +Depending on the artifact type, the configuration properties can be specified in different formats. +Which format to use in which scenario is documented in the config documentations for +[JAR](../running-jar.md), +[WAR](../running-war.md) and +[Docker](../running-with-docker.md). + +* `.yml` is the default configuration format since version 8. You can find an [example configuration file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.yml) with all available configuration options. Only a minimal set of properties is active, all others are commented out. +* `.env` files for Docker setup. There is also an [example env file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.env) that you can download and customize. +* `.json` config file: In the past openrouteservice was configured [via JSON file](json.md). This configuration method has been **deprecated** and will be eventually removed. Therefore, we strongly discourage you from using it. If you have an old JSON config, please consider to [migrate to the new config](https://github.com/GIScience/ors-config-migration#usage). + +All of the above described config files can contain the same logic application properties. + +For example, the property `ors.engine.profiles.car.enabled` would look like this + +in `*.yml` +```yaml +ors: + engine: + profiles: + car: + enabled: true +``` + +in `*.env` +```shell +ors.engine.profiles.car.enabled=true +``` + +in `*.properties` +```properties +ors.engine.profiles.car.enabled=true +``` + +In [Alternative Configuration](#alternative-configuration) you find the syntax to define the property as environment variable or program argument. + + +## File Content + + +The properties are organized in a hierarchical structure, with the following ones at top level. + +- [Spring Properties](spring/index.md), such as + * [Server Properties](spring/server.md) + * [Logging Properties](spring/logging.md) +- openrouteservice properties with these children: + * [ors.endpoints](ors/endpoints/index.md): Settings required at runtime to process API requests. + * [ors.engine](ors/engine/index.md): Settings required at graph-build time during startup. + * [ors.cors](ors/cors/index.md): Cross-origin resource sharing settings. + * [ors.messages](ors/messages/index.md): System messages that can be sent with API responses following simple rules. + +At the very least, openrouteservice needs the configuration to contain an enabled [profile](ors/engine/profiles.md) and the +reference to an [OSM data file](../data.md#osm-data) to run properly. Therefore, the minimal valid content of such a file +would be, e.g.: + +```yaml +ors: + engine: + source_file: ./osm_file.pbf + profiles: + car: + enabled: true +``` + +## Alternative configuration + +All configuration parameters can be overridden by runtime parameters or by setting environment variables. At program start openrouteservice reports on every environment variable that *might* have an effect on its behavior. You can run openrouteservice entirely without a configuration file by setting all required properties via environment variables. The examples listed below achieve the same example minimal configuration mentioned above. + +The options in order of precedence (higher options win over lower) are: +- Spring runtime parameter + ```shell + java -jar ors.jar --ors.engine.source_file=./osm_file.pbf --ors.engine.profiles.car.enabled=true + ``` +- Java VM runtime parameter + ```shell + java -jar -Dors.engine.source_file=./osm_file.pbf -Dors.engine.profiles.car.enabled=true ors.jar + ``` +- Environment variables + ```shell + export ors.engine.source_file=./osm_file.pbf + export ors.engine.profiles.car.enabled=true + java -jar ors.jar + ``` + +The option to configure using environment variables is especially useful in contexts where you want to run +openrouteservice in containers such as with [docker](../running-with-docker.md). + +Every property also corresponds to an environment variable name in *uppercase letters* and with *underscores* replacing *dots*, so e.g. +- `ORS_ENGINE_SOURCE_FILE` replaces `ors.engine.source_file` +- `ORS_ENGINE_PROFILES_CAR_ENABLED` replaces `ors.engine.profiles.car.enabled` + +Consequently,the following commands are equivalent to the last example above: +```shell + export ORS_ENGINE_SOURCE_FILE=./osm_file.pbf + export ORS_ENGINE_PROFILES_CAR_ENABLED=true + java -jar ors.jar +``` diff --git a/docs/versions/v8.2.0/run-instance/configuration/json.md b/docs/versions/v8.2.0/run-instance/configuration/json.md new file mode 100644 index 0000000000..376d5602ad --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/json.md @@ -0,0 +1,333 @@ +# Configuration via `ors-config.json` + +:::warning +The ors-config.json is deprecated! [Migrate to ors-config.yml](https://github.com/GIScience/ors-config-migration#usage). +::: + +The "old" configuration method is supported for a while for convenience. +The description below is kept as long as openrouteservice still supports configuration via JSON file, +but we do **not** recommend using this configuration method. +Please consider [migrating your JSON configuration](https://github.com/GIScience/ors-config-migration#usage) to the new style. +Note that currently all settings in a provided JSON configuration file will **override** any settings in the YAML file. + +## ors + +The top level element. + +| key | type | description | example value | +|----------------|--------|-----------------------------------|----------------------------------------| +| services | object | an object comprising the services | [services](#ors-services) | +| logging | object | the logging properties | [logging](#ors-logging) | +| system_message | list | List of system message objects | [system messages](#ors-system-message) | + +--- + +### ors.services + +| key | type | description | example value | +|-------------------------|--------|---------------------------------------|----------------------------------------| +| ors.services.routing | object | settings for routing and its profiles | [routing](#ors-services-routing) | +| ors.services.isochrones | object | settings for isochrones restrictions | [isochrones](#ors-services-isochrones) | +| ors.services.matrix | object | settings for matrix restrictions | [matrix](#ors-services-matrix) | +| ors.services.snap | object | settings for snap | [snap](#ors-services-snap) | + +--- + +#### ors.services.routing + +| key | type | description | example value | +|------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point. Default value is true. | `true` | +| mode | string | Can be either "normal" or "preparation". If "preparation" then graphs will be built and the service will be shut down afterwards. | `"normal"` | +| description | string | | `"This is a routing file from openrouteservice"` | +| routing_name | string | Specifies the gpx `name` tag that is returned in a gpx response | `"openrouteservice"` | +| sources | list | the osm file to be used, formats supported are `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` | `["heidelberg.osm.gz"]` | +| init_threads | number | The number of threads used to initialize (build/load) graphs. Higher numbers requires more RAM. | `2` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | +| elevation_preprocessed | boolean | Enables or disables reading ele tags for nodes. Default value is false. If enabled, GH's elevation lookup is prevented and all nodes without ele tag will default to 0. Experimental, for use with the ORS preprocessor | `false` | +| profiles | object | | [profiles](#ors-services-routing-profiles) | + +--- + +##### **ors.services.routing.profiles** + +| key | type | description | example value | +|----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| active | list | Defines a list of active routing profiles. The element name XXX must correspond to a notation "profile-XXX", which is used in the following sections. Can be one or many of `"car"`, `"hgv"`, `"bike-regular"`, `"bike-mountain"`, `"bike-road"`, `"bike-electric"`, `"walking"`, `"hiking"` or `"wheelchair"` | `["car", "bike-regular"]` | +| default_params | object | Set parameters that is applied to every profile by default | [default_params](#ors-services-routing-profiles-default-params) | +| profile-XXX | object | Settings that are applied to the specific profile. You may run multiple profiles at once. | [profile-XXX](#ors-services-routing-profiles-profile-xxx) | + +--- + +##### **ors.services.routing.profiles.default_params** + +| key | type | description | example value | +|---------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| encoder_flags_size | number | The number of bytes used for FlagEncoders | `8` | +| graphs_root_path | string | The root path to a directory for storing graphs | `"../graphs"` | +| elevation_provider | string | The name of an elevation provider. Possible values are multi, cgiar or srtm | `"multi"` | +| elevation_cache_path | string | The path to a directory in which SRTM tiles will be stored | `"elevation_cache"` | +| elevation_cache_clear | boolean | keep elevation data once it has been downloaded | `false` | +| elevation_smoothing | boolean | smooth out elevation data | `false` | +| instructions | boolean | Specifies whether way names will be stored during the import or not | `true` | +| maximum_distance | number | The maximum allowed total distance of a route | `100000` | +| maximum_segment_distance_
with_dynamic_weights | number | The maximum allowed distance between two way points when dynamic weights are used | `50000` | +| maximum_waypoints | number | The maximum number of way points in a request | `50` | +| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `100` | +| maximum_distance_round_trip_routes | number | The maximum allowed total distance of a route for the round trip algo | `100000` | +| maximum_distance_alternative_routes | number | The maximum allowed total distance of a route for the alternative route algo | `100000` | +| maximum_alternative_routes | number | The maximum number of alternative routes in a request | `3` | +| maximum_avoid_polygon_area | number | The maximum allowed total area of a polygon in square kilometers, optional | `200000000` | +| maximum_avoid_polygon_extent | number | The maximum extent (i.e. envelope side length) of a polygon in kilometers, optional | `20000` | +| location_index_resolution | number | The minimum resolution in meters of tiles in the location index. Lower values yield faster queries at a cost of increased memory requirements. Reducing the resolution reduces the lookup radius which can be compensated by increasing `location_index_search_iterations`. Corresponds to GraphHopper's `index.high_resolution` configuration parameter. | `500` (default) | +| location_index_search_iterations | number | The maximum number of iterations performed in coordinates lookup. Higher values yield a broader search area, but might reduce query performance. It only affects the storage lookup but not its layout so changing this parameter does not require rebuilding the location index. Corresponds to GraphHopper's `index.max_region_search` configuration parameter. | `4` (default) | +| maximum_speed_lower_bound | number | Specifies the threshold for the query parameter `maximum_speed`. | `80` (default) | +| interpolate_bridges_and_tunnels | boolean | Interpolate elevation of bridges and tunnels. | `true` (default) | +| preparation | object | ... | [preparation](#ors-services-routing-profiles-default-params-preparation) | +| execution | object | ... | [execution](#ors-services-routing-profiles-default-params-execution) | + +--- + +##### **ors.services.routing.profiles.default_params.preparation** + +| key | type | description | example value | +|------------------|--------|-------------------------------------------------------------------|------------------------------------------------------------------------------| +| min_network_size | number | Minimum size (number of edges) of an independent routing subgraph | `200` | +| methods | object | | [methods](#ors-services-routing-profiles-default-params-preparation-methods) | + +##### **ors.services.routing.profiles.default_params.preparation.methods** + +| key | type | description | example value | +|------|--------|----------------------------------------------------|--------------------------------------------------------------------------------| +| ch | object | Settings for preprocessing contraction hierarchies | [ch](#ors-services-routing-profiles-default-params-preparation-methods-ch) | +| lm | object | Settings for preprocessing landmarks | [lm](#ors-services-routing-profiles-default-params-preparation-methods-lm) | +| core | object | Settings for preprocessing landmarks | [core](#ors-services-routing-profiles-default-params-preparation-methods-core) | + +##### **ors.services.routing.profiles.default_params.preparation.methods.ch** + +| key | type | description | example value | +|------------|---------|-------------|-----------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended"` | + +##### **ors.services.routing.profiles.default_params.preparation.methods.lm** + +| key | type | description | example value | +|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| landmarks | number | Total number of precomputed landmarks, the subset used during the query is set in [`active_landmarks`](#ors-services-routing-profiles-default-params-executionmethods-lm) | `16` | + +##### **ors.services.routing.profiles.default_params.preparation.methods.core** + +| key | type | description | example value | +|------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| landmarks | number | Total number of precomputed landmarks, the subset used during the query is set in [`active_landmarks`](#ors-services-routing-profiles-default-params-execution-methods-core) | `32` | +| lmsets | string | | `"highways,tollways;highways;tollways;country_193;allow_all"` | + +--- + +##### **ors.services.routing.profiles.default_params.execution** + +| key | type | description | example value | +|---------|--------|-------------|----------------------------------------------------------------------------| +| methods | object | | [methods](#ors-services-routing-profiles-default-params-execution-methods) | + +##### **ors.services.routing.profiles.default_params.execution.methods** + +| key | type | description | example value | +|------|--------|-------------------------------------------------------|------------------------------------------------------------------------------| +| ch | object | Settings for using contraction hierarchies in routing | [ch](#ors-services-routing-profiles-default-params-execution-methods-ch) | +| lm | object | Settings for using landmarks in routing | [lm](#ors-services-routing-profiles-default-params-execution-methods-lm) | +| core | object | Settings for using landmarks in routing | [core](#ors-services-routing-profiles-default-params-execution-methods-core) | + +##### **ors.services.routing.profiles.default_params.execution.methods.lm** + +| key | type | description | example value | +|-------------------|---------|--------------------------------------------------|---------------| +| active_landmarks | number | Number of landmarks used for computing the route | `8` | + +##### **ors.services.routing.profiles.default_params.execution.methods.core** + +| key | type | description | example value | +|-------------------|---------|--------------------------------------------------|---------------| +| active_landmarks | number | Number of landmarks used for computing the route | `6` | + +--- + +##### **ors.services.routing.profiles.profile-XXX** + +| key | type | description | example value | +|------------|--------|-----------------------------------------------|---------------------------------------------------------------------| +| profiles | string | name of the profile when called via the API | `driving-car` | +| parameters | object | the specific profile parameters of an profile | [parameters](#ors-services-routing-profiles-profile-xxx-parameters) | + +##### **ors.services.routing.profiles.profile-XXX.parameters** + +| key | type | description | example value | +|-------------------------------------|---------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| encoder_options | string | | `"turn_costs=true\ |block_fords=false"` [encoder options](#ors-services-routing-profiles-profile-xxx-parametersencoder_options) | +| elevation | boolean | This will enable the elevation information in the response | `true` | +| maximum_distance | number | Maximum distance a route can have in meters | `100000` | +| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `100` | +| maximum_distance_round_trip_routes | number | The maximum allowed total distance of a route for the round trip route algo | `100000` | +| maximum_distance_alternative_routes | number | The maximum allowed total distance of a route for the alternative route algo | `100000` | +| maximum_alternative_routes | number | The maximum number of alternative routes in a request | `3` | +| maximum_avoid_polygon_area | number | The maximum allowed total area of a polygon in square kilometers, optional | `200000000` | +| maximum_avoid_polygon_extent | number | The maximum extent (i.e. envelope side length) of a polygon in kilometers, optional | `20000` | +| ext_storages | object | Controls which external storages are enabled | [external storages](#ors-services-routing-profiles-profile-xxx-parameters-ext-storages) | +| gtfs_file | string | Only for pt profile: location of gtfs-file used. Can either be a zip-file or the unzipped folder. | `"src/test/files/vrn_gtfs_cut.zip"` | + +##### **ors.services.routing.profiles.profile-XXX.parameters.encoder_options** + +| key | type | description | example value | +|--------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| +| problematic_speed_factor | number | For wheelchair profile only! Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such ways | `problematic_speed_factor=0.7` | +| preferred_speed_factor | number | For wheelchair profile only! Travel speeds on edges classified as preferable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such ways | `preferred_speed_factor=1.2` | + +##### **ors.services.routing.profiles.profile-XXX.parameters.ext_storages** + +| key | type | description | example value | +|------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| +| WayCategory | object | Returns the way category in the route response, Compatible for any profile type | `{}` | +| WaySurfaceType | object | Returns the way surface in the route response, Compatible for any profile type | `{}` | +| HillIndex | object | Returns the ascent/descent in the route response, Compatible for any profile type | `{}` | +| TrailDifficulty | object | Returns the trail difficulty in the route response, Compatible for profile-hiking | `{}` | +| RoadAccessRestrictions | object | RoadAccessRestrictions are where roads are restricted to certain vehicles to certain circumstances, e.g. access=destination. The use_for_warnings parameter tells the ors that this storage can be used for generating warning messages in the route response. For RoadAccessRestrictions, this means that whenever a route goes over a way which has some restrictions, a warning message will be delivered with the response and the roadaccessrestrictions extra info automatically added. | `{ use_for_warnings: true }` | +| Wheelchair | object | Compatible for wheelchair | `{ KerbsOnCrossings: "true" }` | +| OsmId | object | Returns the OsmId of the way, Compatible for wheelchair | `{}` | +| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible for any profile type | [Borders](#ors-services-routing-profiles-profile-xxx-parameters-ext-storages-borders) | + +##### **ors.services.routing.profiles.profile-XXX.parameters.ext_storages.Borders** + +| key | type | description | example value | +|-------------|--------|-----------------------------------------------------------------------------------------------------|----------------------------| +| boundaries | string | The path to a file containing geojson data representing the borders of countries | `'borders.geojson.tar.gz'` | +| ids | string | Path to a csv file containing a unique id for each country, its local name and its English name | `'ids.csv'` | +| openborders | string | Path to a csv file containing pairs of countries where the borders are open (i.e. Schengen borders) | `'openborders.csv'` | + +--- + +#### ors.services.isochrones + +| key | type | description | example value | +|------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| maximum_range_distance | list | Possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile | `[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]` | +| maximum_range_time | list | | `[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]` | +| maximum_intervals | number | Maximum number of intervals/isochrones computed for each location | `10` | +| maximum_locations | number | Maximum number of locations in one request | `2` | +| allow_compute_area | number | Specifies whether area computation is allowed | `true` | + +##### **ors.services.isochrones.fastisochrones** + +| key | type | description | example value | +|------------------------|------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| +| maximum_range_distance | list | Possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile | `[{profiles: "any", value: 50000}, {profiles: "driving-car, driving-hgv", value: 100000}]` | +| maximum_range_time | list | | `[{profiles: "any", value: 18000},{profiles: "driving-car, driving-hgv", value: 3600}]` | + +##### **ors.services.isochrones.fastisochrones.profiles.default_params** + +| key | type | description | example value | +|--------------|---------|----------------------------------------------------------|--------------------------| +| enabled | boolean | | `true` | +| threads | number | | `1` | +| weightings | string | | `"recommended,shortest"` | +| maxcellnodes | number | Maximum number of nodes allowed in single isochrone cell | `5000` | + +--- + +#### ors.services.matrix + +| key | type | description | example value | +|-------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| maximum_routes | number | Maximum amount of routes the matrix should compute. E.g. `2500` could be a 50x50 matrix or 1x2500 matrix | `2500` | +| maximum_routes_flexible | number | Maximum amount of routes for using custom profiles that do not support contraction hierarchies | `25` | +| maximum_search_radius | number | Maximum allowed distance between the requested coordinate and a point on the nearest road. The value is measured in meters | `5000` | +| maximum_visited_nodes | number | Maximum allowed number of visited nodes in shortest path computation. This threshold is applied only for Dijkstra algorithm | `100000` | +| allow_resolve_locations | number | Specifies whether the name of a nearest street to the location can be resolved or not. Default value is true | `true` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | + +--- +#### ors.services.snap + +| key | type | description | example value | +|-------------------|---------|----------------------------------------------------------------|------------------------------------------------------| +| enabled | boolean | Enables or disables (true/false) the end-point (default: true) | `true` | +| attribution | string | Attribution added to the response metadata | `"openrouteservice.org, OpenStreetMap contributors"` | +| maximum_locations | number | Maximum number of locations in one request | `5000` | + +--- + +#### ors.logging + +| key | type | description | example value | +|------------|---------|-----------------------------------------------------------------|------------------------| +| enabled | boolean | Enables or disables the end-point (default: true) | `true` | +| level_file | string | Can be either `DEBUG_LOGGING.json` or `PRODUCTION_LOGGING.json` | `"DEBUG_LOGGING.json"` | +| location | string | Location of the logs | `"/var/log/ors"` | +| stdout | boolean | | `true` | + +--- + +#### ors.system_message + +Array of message objects where each has + +| key | type | description | example value | +|-----------|---------|------------------------------------------------------------------|----------------------| +| active | boolean | Enables or disables this message | `true` | +| text | string | The message text | `"The message text"` | +| condition | object | optional; may contain any of the conditions from the table below | | + +| condition | value | description | +|--------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| time_before | ISO 8601 datetime string | message sent if server local time is before given point in time | +| time_after | ISO 8601 datetime string | message sent if server local time is after given point in time | +| api_version | 1 or 2 | message sent if API version requested through matches value | +| api_format | String with output formats ("json", "geojson", "gpx"), comma separated | message sent if requested output format matches value | +| request_service | String with service names ("routing", "matrix", "isochrones"), comma separated | message sent if requested service matches one of the given names | +| request_profile | String with profile names, comma separated | message sent if requested profile matches one of the given names | +| request_preference | String with preference (weightings for routing, metrics for matrix, rangetype for isochrones) names, comma separated | message sent if requested preference matches one of the given names | + +##### Example: + +``` +system_message: [ + { + active: true, + text: "This message would be sent with every routing bike fastest request. E.g. 'The fastest weighting for cycling profiles is deprecated, use recommended weighting instead. API will be kept for compatibility until release of version 7.0.0'", + condition: { + "request_service": "routing", + "request_profile": "cycling-regular,cycling-mountain,cycling-road,cycling-electric", + "request_preference": "fastest" + } + }, + { + active: true, + text: "This message would be sent with every request for geojson response.", + condition: { + "api_format": "geojson" + } + }, + { + active: true, + text: "This message would be sent with every request on API v1 from January 2020 until June 2050. E.g. 'The V1 API is deprecated. You should switch to using the V2 API.'", + condition: { + "api_version": "1", + "time_after": "2020-01-01T00:00:00Z", + "time_before": "2050-06-01T00:00:00Z" + } + }, + { + active: true, + text: "This message would be sent with every request. E.g. 'Scheduled downtime due to version upgrade on March 15th 2020, 12:00 AM CET for approx. 3 hours.'" + } +] +``` diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/cors/index.md b/docs/versions/v8.2.0/run-instance/configuration/ors/cors/index.md new file mode 100644 index 0000000000..073895f8a3 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/cors/index.md @@ -0,0 +1,9 @@ +# `ors.cors` + +Properties concerning cross-origin resource sharing: + +| key | type | description | default value | +|-------------------|-------------------------------|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| allowed_origins | string / comma separated list | Configures the Access-Control-Allow-Origins CORS header. `*` for all origins | `*` | +| allowed_headers | string / comma separated list | Configures the Access-Control-Allow-Headers CORS header. `*` for all headers s | `Content-Type, X-Requested-With, accept, Origin, Access-Control-Request-Method, Access-Control-Request-Headers, Authorization` | +| preflight_max_age | int | Duration in seconds. Specifies how long the OPTIONS response is cached by browsers | `600` | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/defaults.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/defaults.md new file mode 100644 index 0000000000..2852fd8b58 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/defaults.md @@ -0,0 +1,7 @@ +# `ors.endpoints.defaults` + +Common settings for all ors endpoints. + +| key | type | description | default value | +|-------------|--------|--------------------------------------------|---------------| +| attribution | string | Attribution added to the response metadata | _NA_ | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/index.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/index.md new file mode 100644 index 0000000000..844a5146bf --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/index.md @@ -0,0 +1,3 @@ +# `ors.endpoints` + +Settings beneath `ors.endpoints` are required at runtime to process API requests. diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/isochrones.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/isochrones.md new file mode 100644 index 0000000000..ad83a8a015 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/isochrones.md @@ -0,0 +1,73 @@ +# `ors.endpoints.isochrones` + +Settings for the isochrones endpoint. + +| key | type | description | default value | +|--------------------------------|---------|----------------------------------------------------------------------------------------------------|----------------------------------------------------| +| enabled | boolean | Enables or disables the end-point | `true` | +| attribution | string | Attribution added to the response metadata | `openrouteservice.org, OpenStreetMap contributors` | +| maximum_locations | number | Maximum number of locations per request | `2` | +| allow_compute_area | boolean | Toggles area computation on and off | `true` | +| maximum_intervals | number | Maximum number of intervals/isochrones computed for each location | `1` | +| fastisochrones | object | Range limits for [fastisochrones](#fastisochrones) | | +| statistics_providers | object | [Statistics providers properties](#statistics-providers) | | +| maximum_range_distance_default | number | Maximum default range in metres across all profiles; can be overridden in `maximum_range_distance` | `50000` | +| maximum_range_distance | object | List of [maximum range properties](#maximum-range-properties) | | +| maximum_range_time_default | number | Maximum default range in seconds across all profiles; can be overridden in `maximum_range_time` | `18000` | +| maximum_range_time | object | List of [maximum range properties](#maximum-range-properties) | | + +## fastisochrones + +Properties beneath `ors.endpoints.isochrones.fastisochrones` for fastisochrone only: + +| key | type | description | default value | +|--------------------------------|--------|----------------------------------------------------------------------------------------------------|---------------| +| maximum_range_distance_default | number | Maximum default range in metres across all profiles; can be overridden in `maximum_range_distance` | `50000` | +| maximum_range_distance | object | [`maximum range properties`](#maximum-range-properties) object | | +| maximum_range_time_default | number | Maximum default range in seconds across all profiles; can be overridden in `maximum_range_time` | `18000` | +| maximum_range_time | object | [`maximum range properties`](#maximum-range-properties) object | | + +### maximum_range properties +These properties can be nested beneath +* `ors.endpoints.isochrones.maximum_range_distance` +* `ors.endpoints.isochrones.maximum_range_time` +* `ors.endpoints.isochrones.fastisochrones.maximum_range_distance` +* `ors.endpoints.isochrones.fastisochrones.maximum_range_time` + +| key | type | description | example value | +|----------|--------|---------------------------------|----------------------------| +| profiles | list | List of profile names | `driving-car, driving-hgv` | +| value | number | Value of distance or time limit | `3600` | + + +## statistics_providers +Properties beneath `ors.endpoints.isochrones.statistics_providers`: + +| key | type | description | example value | +|---------------------|---------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| enabled | boolean | Enables or disables the provider | true | +| attribution | string | Provider attribution | OpenStreetMap contributors | +| provider_name | string | Internal name used to reference this provider (no effect) | my_statistics_provider_1 | +| provider_parameters | object | A list of provider configuration parameters | see [provider_parameters](#provider-parameters) | +| property_mapping | object | Key-Value pairs with the name of the value to request in the `attributes` parameter in an isochrones request | total_pop: total_pop (only supported currently) | + +::: warning +To adjust the `property_mapping` further implementations are needed in `IsochronesRequestEnums.java`, +`PostgresSQLStatisticsProvider.java`, `RoutingProfile.java` and `GeoJSONIsochroneProperties.java` are needed. +::: + +### provider_parameters + +Properties beneath `ors.endpoints.isochrones.statistics_providers.provider_parameters`: + +| key | type | description | example value | +|-----------------|--------|------------------------------------------------------------|---------------------| +| host | string | Host where the postgres/postgis DB is running on | "localhost", | +| port | number | Port the DB is running on | 5432, | +| user | string | DB user | "admin", | +| password | string | DB password for user | "my_safe_password", | +| db_name | string | Name of the database | "postgres", | +| table_name | string | Name of the table used in SQL query of | "pop_data", | +| geometry_column | string | Name of column used in SQL query of | "rast", | +| postgis_version | string | Postgis Version used for conditional logic in SQL query of | "3" | + diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/matrix.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/matrix.md new file mode 100644 index 0000000000..d69c9b789c --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/matrix.md @@ -0,0 +1,14 @@ + +# `ors.endpoints.matrix` + +Settings for the matrix endpoint. + +| key | type | description | default value | +|-------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| +| enabled | boolean | Enables or disables the end-point | `true` | +| attribution | string | Attribution added to the response metadata | `openrouteservice.org, OpenStreetMap contributors` | +| maximum_routes | number | Maximum amount of routes the matrix should compute; e.g. the value of `2500` could correspond to a 50x50 matrix or 1x2500 matrix | `2500` | +| maximum_routes_flexible | number | Maximum amount of routes for profiles that do not have the CH routing algorithm enabled | `25` | +| maximum_visited_nodes | number | Maximum allowed number of visited nodes in shortest path computation | `100000` | +| maximum_search_radius | number | Maximum allowed distance in meters between the requested coordinate and a point on the nearest road | `2000` | +| u_turn_cost | number | Penalty of performing a U-Turn; the value of `-1` prevents them entirely | `-1` | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/routing.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/routing.md new file mode 100644 index 0000000000..8b7089da1f --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/routing.md @@ -0,0 +1,18 @@ + +# `ors.endpoints.routing` + +Settings for routing endpoint. + +| key | type | description | default value | +|------------------------------|---------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| +| enabled | boolean | Enables or disables the end-point | `true` | +| attribution | string | Attribution added to the response metadata | `openrouteservice.org, OpenStreetMap contributors, tmc - BASt` | +| gpx_name | string | Specifies the `name` tag that is returned in `metadata` of a gpx response | `ORSRouting` | +| gpx_description | string | Specifies the `desc` tag that is returned in `metadata` of a gpx response | `This is a directions instructions file as GPX, generated from openrouteservice` | +| gpx_base_url | string | Specifies the `link` tag that is returned in `metadata/author` of a gpx response | `https://openrouteservice.org/` | +| gpx_support_mail | string | Specifies the `email` tag that is returned in `metadata/author` of a gpx response | `support@openrouteservice.org` | +| gpx_author | string | Specifies the `name` tag that is returned in `metadata/author` of a gpx response | `openrouteservice` | +| gpx_content_licence | string | Specifies the `license` tag that is returned in `metadata/copyright` of a gpx response | `LGPL 3.0` | +| maximum_avoid_polygon_area | number | The maximum allowed total area of a polygon in square kilometers, optional | `200000000` | +| maximum_avoid_polygon_extent | number | The maximum extent (i.e. envelope side length) of a polygon in kilometers, optional | `20000` | +| maximum_alternative_routes | number | The maximum number of alternative routes in a request | `3` | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/snap.md b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/snap.md new file mode 100644 index 0000000000..efd29760bb --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/endpoints/snap.md @@ -0,0 +1,11 @@ + +# `ors.endpoints.snap` + +Settings for the snapping endpoint. + +| key | type | description | default value | +|-------------------|---------|--------------------------------------------|----------------------------------------------------| +| enabled | boolean | Enables or disables the end-point | `true` | +| attribution | string | Attribution added to the response metadata | `openrouteservice.org, OpenStreetMap contributors` | +| maximum_locations | number | Maximum number of locations per request | `5000` | + diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/engine/elevation.md b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/elevation.md new file mode 100644 index 0000000000..2036f6b677 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/elevation.md @@ -0,0 +1,12 @@ + +# `ors.engine.elevation` + +Settings related to elevation information for graph building. + +| key | type | description | default value | +|--------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| +| preprocessed | boolean | Toggles reading of OSM `ele` node tags on and off. If enabled, graphhoppers' elevation lookup is prevented and all nodes without `ele` tag will default to 0. Intended to be used in combination with the ORS preprocessor | `false` | +| cache_clear | boolean | Keep elevation data once it has been downloaded | `false` | +| provider | string | The name of an elevation provider. Possible values are `multi`, `cgiar` or `srtm` | `multi` | +| cache_path | string | The path to a directory in which SRTM tiles will be stored | `./elevation_cache` | +| data_access | string | Defines how a DataAccess object is created.
- `MMAP`: memory mapped storage
- `RAM_STORE`: in-memory storage with a safe/flush option. Can be used for small areas
Further info in the [source code](https://github.com/GIScience/graphhopper/blob/ors_4.0/core/src/main/java/com/graphhopper/storage/DAType.java) | `MMAP` | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/engine/index.md b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/index.md new file mode 100644 index 0000000000..538353359f --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/index.md @@ -0,0 +1,21 @@ + +# `ors.engine` + +Engine properties are required at graph-build time during startup. + +::: warning +If you specified `profile_default` settings they might not be taken into account! +This will be fixed in the next patch release. +As a workaround, you can move all `profile_default` settings to the specific profile where you need them to work. +::: + +| key | type | description | default value | +|--------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| init_threads | number | The number of threads used to initialize (build/load) graphs. Higher numbers requires more RAM | `1` | +| preparation_mode | boolean | If set, graphs and preparations will be build, but the application will shut down immediately afterwards without starting up any services | `false` | +| source_file | string | The OSM file to be used, supported formats are `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` | `ors-api/src/test/files/heidelberg.osm.gz` | +| graphs_root_path | string | The root path to a directory for storing graphs | `./graphs` | +| graphs_data_access | string | Defines how a DataAccess object is created.
- `MMAP`: memory mapped storage
- `RAM_STORE`: in-memory storage with a safe/flush option.
Further info in the [source code](https://github.com/GIScience/graphhopper/blob/ors_4.0/core/src/main/java/com/graphhopper/storage/DAType.java) | `RAM_STORE` | +| elevation | object | See [elevation properties](elevation.md) | | +| profile_default | object | Described in [profile properties](profiles.md) | | +| profiles | object | Described in [profile properties](profiles.md) | | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/engine/profiles.md b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/profiles.md new file mode 100644 index 0000000000..523d8fdbc4 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/engine/profiles.md @@ -0,0 +1,237 @@ + +# `ors.engine.profiles` + +The profiles object contains key-object-pairs for each profile you are using. + +There are some default profile keys in our standard ors-config.yml with flag encoders and recommended profile-specific settings predefined. +These standard profiles are: + +| `*` in `ors.engine.profiles.*` | flag encoder `ors.engine.profiles.*.profile` | +|--------------------------------|----------------------------------------------| +| `car` | `driving-car` | +| `hgv` | `driving-hgv` | +| `bike-regular` | `cycling-regular` | +| `bike-mountain` | `cycling-mountain` | +| `bike-road` | `cycling-road` | +| `bike-electric` | `cycling-electric` | +| `walking` | `foot-car` | +| `hiking` | `foot-hgv` | +| `wheelchair` | `wheelchair` | +| `public-transport` | `public-transport` | + +::: warning +The predefined settings override settings specified in the `profile_default` in your ors-config.yml or ors-config.env! +If you want to specify your own profile settings based on your specific `profile_default` values, you can work around this by naming your profile differently, e.g. `custom-car` instead of `car`. +Note that the profile name can be chosen freely but cannot contain special characters that cannot be used for directory names on your operating system. +::: + +::: warning +In the directions endpoint, the profiles are addressed by their encoder name (e.g. `driving-car`)! +::: + +Properties for each (enabled) profile are set under `ors.engine.profiles.`, e.g. +- `ors.engine.profiles.car` +- `ors.engine.profiles.hiking` + +| key | type | description | default value | +|-------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| profile | string | Profile name for the directions endpoint. Also used as specification for the flag encoder during graph building. Possible values are restricted to those in the second column in above table! | _NA_ | +| enabled | boolean | Enables or disables the profile across **openrouteservice** endpoints | `true` | +| elevation | boolean | Specifies whether to use or not elevation data | `false` | +| elevation_smoothing | boolean | Smooth out elevation data | `false` | +| traffic | boolean | Use traffic data if available | `false` | +| interpolate_bridges_and_tunnels | boolean | Toggle elevation interpolation of bridges and tunnels on and off | `true` | +| instructions | boolean | Specifies whether way names will be stored during the import or not | `true` | +| optimize | boolean | Optimize the sort order when contracting nodes for CH. This is rather expensive, but yields a better contraction hierarchy. | `false` | +| graph_path | string | Subdirectory name under `ors.engine.graphs_root_path`. If left unset, the profile entry name on the `profiles` list is used | _NA_ | +| encoder_options | string | For details see [encoder_options](#encoder_options) below | | +| preparation | object | [Preparation settings](#preparation) for building the routing graphs | | +| execution | object | [Execution settings](#execution) relevant when querying services | | +| ext_storages | object | [External storages](#ext_storages) for returning extra information | | +| maximum_distance | number | The maximum allowed total distance of a route | `100000` | +| maximum_distance_dynamic_weights | number | The maximum allowed distance between two way points when dynamic weights are used | `100000` | +| maximum_distance_avoid_areas | number | The maximum allowed distance between two way points when areas to be avoided are provided | `100000` | +| maximum_distance_alternative_routes | number | The maximum allowed total distance of a route for the alternative routes algorithm | `100000` | +| maximum_distance_round_trip_routes | number | The maximum allowed total distance of a route for the round trip algorithm | `100000` | +| maximum_speed_lower_bound | number | Specifies the threshold for the query parameter `maximum_speed` | `80` | +| maximum_way_points | number | The maximum number of way points in a request | `50` | +| maximum_snapping_radius | number | Maximum distance around a given coordinate to find connectable edges | `400` | +| maximum_visited_nodes | number | Maximum allowed number of visited nodes in shortest path computation | `1000000` | +| encoder_flags_size | number | The number of bytes used for FlagEncoders | `8` | +| location_index_resolution | number | The minimum resolution in meters of tiles in the location index. Lower values yield faster queries at a cost of increased memory requirements. Reducing the resolution reduces the lookup radius which can be compensated by increasing `location_index_search_iterations`. Corresponds to GraphHopper's `index.high_resolution` configuration parameter. | `500` | +| location_index_search_iterations | number | The maximum number of iterations performed in coordinates lookup. Higher values yield a broader search area, but might reduce query performance. It only affects the storage lookup but not its layout so changing this parameter does not require rebuilding the location index. Corresponds to GraphHopper's `index.max_region_search` configuration parameter. | `4` | +| force_turn_costs | boolean | Should turn restrictions be obeyed | `false` | +| gtfs_file | string | Only for `pt` profile: location of GTFS data; can either be a zip-file or the unzipped folder | _NA_ | + +## encoder_options + +Properties beneath `ors.engine.profiles.*.encoder_options`: + +| key | type | profiles | description | example value | +|--------------------------|---------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| block_fords | boolean | * | Do not route through fords | `true` | +| consider_elevation | boolean | bike-* | The maximum possible speed is the bike-type specific maximum downhill speed, which is higher than the usual maximum speed | `true` | +| maximum_grade_level | number | car, hgv | Relates to the quality of tracks as described in [tracktype](https://wiki.openstreetmap.org/wiki/Key:tracktype). Specifying e.g. `maximum_grade_level=1` means that `tracktype=grade2` and below won't be considered for routing. Setting `maximum_grade_level=0` discards all tracks with a valid `tracktype` tag, while a negative value such as `maximum_grade_level=-1` entirely disables routing on tracks. | `3` | +| preferred_speed_factor | number | wheelchair | Travel speeds on edges classified as preferable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such ways | `1.2` | +| problematic_speed_factor | number | wheelchair | Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such ways | `0.7` | +| turn_costs | boolean | car, hgv, bike-* | Should turn restrictions be respected | `true` | +| use_acceleration | boolean | car, hgv | Models how a vehicle would accelerate on the road segment to the maximum allowed speed. In practice it reduces speed on shorter road segments such as ones between nearby intersections in a city | `true` | + +## preparation + +Properties beneath `ors.engine.profiles.*.preparation`: + +| key | type | description | default value | +|--------------------------|--------|-------------------------------------------------------------------|---------------| +| min_network_size | number | Minimum size (number of edges) of an independent routing subgraph | `200` | +| methods | object | see below | | + +### methods.ch + +Settings for preprocessing contraction hierarchies + +Properties beneath `ors.engine.profiles.*.preparation.methods.ch`: + +| key | type | description | example value | +|------------|---------|----------------------------------------------------------|------------------------| +| enabled | boolean | Enables or disables the routing algorithm | `true` | +| threads | number | Number of parallel threads for computing the preparation | `1` | +| weightings | string | Comma-separated list of weightings | `recommended,shortest` | + +### methods.lm +Settings for preprocessing A* with landmarks + +Properties beneath `ors.engine.profiles.*.preparation.methods.lm`: + +| key | type | description | default value | +|------------|---------|---------------------------------------------------------------------------------------------------------------------------|------------------------| +| enabled | boolean | Enables or disables the routing algorithm | `true` | +| threads | number | Number of parallel threads for computing the preparation | `1` | +| weightings | string | Comma-separated list of weightings | `recommended,shortest` | +| landmarks | number | Total number of precomputed landmarks; the subset used during the query is set in `execution.methods.lm.active_landmarks` | `16` | + +### methods.core +Settings for preprocessing core routing with landmarks + +Properties beneath `ors.engine.profiles.*.preparation.methods.core`: + +| key | type | description | example value | +|------------|---------|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| enabled | boolean | Enables or disables the routing algorithm | `true` | +| threads | number | Number of parallel threads for computing the preparation | `1` | +| weightings | string | Comma-separated list of weightings | `recommended,shortest` | +| landmarks | number | Total number of precomputed landmarks, the subset used during the query is set in `execution.methods.core.active_landmarks` | `32` | +| lmsets | string | Landmark sets tailored for specific avoid-filters enabled | `highways,tollways;highways;tollways;country_193;allow_all` | + +## execution + +Properties beneath `ors.engine.profiles.*.execution` are relevant when querying services. + +### methods.astar + +Parameters for beeline approximation in the A* routing algorithm. + +Properties beneath `ors.engine.profiles.*.execution.methods.astar`: + +| key | type | description | default value | +|---------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| approximation | string | Method to use for distance approximation. Can be either the faster `BeelineSimplification` or the more precise but slower `BeelineAccurate` | `BeelineSimplification` | +| epsilon | number | Factor to use for distance approximation | `1` | + +### methods.lm + +Settings for using landmarks in routing. + +Properties beneath `ors.engine.profiles.*.execution.methods.lm`: + +| key | type | description | default value | +|-------------------|---------|--------------------------------------------------|---------------| +| active_landmarks | number | Number of landmarks used for computing the route | `8` | + +### methods.core + +Settings for using landmarks in routing. + +Properties beneath `ors.engine.profiles.*.execution.methods.core`: + +| key | type | description | example value | +|-------------------|---------|--------------------------------------------------|---------------| +| active_landmarks | number | Number of landmarks used for computing the route | `6` | + +## ext_storages + +It can be defined for each profile which auxiliary metadata should be included in the graph. +This information is made available as `extra_info` in a routing response. +To do so, add a key from the list below. +Leave its value empty, unless you want to specify further options (currently only available for +[RoadAccessRestrictions](#roadaccessrestrictions), [Borders](#borders), [Wheelchair](#wheelchair) and [HeavyVehicle](#heavyvehicle)). + +::: warning +In addition to providing the information in query response, data from `WayCategory` and `Tollways` storages is being +used to filter out certain roads via the +[`options.avoid_features`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-features) +query parameter, and `Borders` is necessary for the functionality behind +[`options.avoid_borders`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-borders) and +[`options.avoid_countries`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-countries) +query parameters. Options from +[`options.profile_params.restrictions`](../../../../api-reference/endpoints/directions/routing-options.md#options-profile-params-restrictions) +require `HeavyVehicle` or `Wheelchair` storages being enabled. Furthermore, hgv profile-specific access restrictions specified in +[`options.vehicle_type`](../../../../api-reference/endpoints/directions/routing-options.md#options-vehicle-type) parameter +rely on the `HeavyVehicle` storage. +::: + +Properties beneath `ors.engine.profiles.*.ext_storages`: + +| key | type | description | example value | +|------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| +| WayCategory | object | Returns the way category in the route response, compatible with any profile type | | +| WaySurfaceType | object | Returns the way surface in the route response, compatible with any profile type | | +| Tollways | object | Returns way tolls in the route response, compatible with driving profiles | | +| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible with any profile type | [Borders](#borders) | +| RoadAccessRestrictions | object | Information on restriction of roads to certain vehicles or circumstances, e.g. `access=destination` | [RoadAccessRestrictions](#roadaccessrestrictions) | +| HeavyVehicle | object | Heavy vehicle-specific storage compatible only with that profile; it contains weight and size limits as well as vehicle-type access restrictions | [HeavyVehicle](#heavyvehicle) | +| HillIndex | object | Returns the ascent/descent in the route response, compatible with any profile type | | +| TrailDifficulty | object | Returns the trail difficulty in the route response, compatible with walking and cycling profiles | | +| Wheelchair | object | Wheelchair-specific attributes compatible only with that profile | [Wheelchair](#wheelchair) | +| OsmId | object | Returns the OsmId of the way, compatible only with wheelchair profile | | + +Check [this table](../../../../api-reference/endpoints/directions/extra-info/index.md#extra-info-availability) for extra info availability. +The following table summarizes which storages are enabled for which profile by default. + +| | WayCategory | WaySurfaceType | Tollways | Borders | RoadAccessRestrictions | HeavyVehicle | HillIndex | TrailDifficulty | Wheelchair | OsmId | +|:------------|:-----------:|:--------------:|:--------:|---------|:----------------------:|:------------:|:---------:|:---------------:|:----------:|:-----:| +| driving-car | x | x | x | | x | | | | | | +| driving-hgv | x | x | x | | | x | | | | | +| cycling-* | x | x | | | | | x | x | | | +| foot-* | x | x | | | | | x | x | | | +| wheelchair | x | x | | | | | | | x | x | + + +### RoadAccessRestrictions +The `use_for_warnings` parameter tells the ors that this storage can be used for generating warning messages in the route response. + +| key | type | description | example value | +|------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| use_for_warnings | boolean | Whenever a route goes over a way which has some restrictions, a warning message will be delivered with the response and the roadaccessrestrictions extra info will be added automatically. | `true` | + +### Wheelchair + +| key | type | description | example value | +|------------------|---------|------------------------------------------|---------------| +| KerbsOnCrossings | boolean | Kerb height is only parsed on crossings. | `true` | + +### Borders + +Properties beneath `ors.engine.profiles.*.ext_storages.Borders` allows to define restriction of routes to not cross country borders, compatible with any profile type. + +| key | type | description | example value | +|-------------|--------|-----------------------------------------------------------------------------------------------------|--------------------------| +| boundaries | string | The path to a geojson file containing polygons representing country borders | `borders.geojson.tar.gz` | +| ids | string | Path to a csv file containing a unique id for each country, its local name and its English name | `ids.csv` | +| openborders | string | Path to a csv file containing pairs of countries where the borders are open (i.e. Schengen borders) | `openborders.csv` | + +### HeavyVehicle + +| key | type | description | example value | +|--------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| restrictions | boolean | Encode certain size and weight limits such as ones contained in `maxheight`, `maxlength`, `maxwidth`, `maxweight` and `maxaxleload` OSM way tags. Includes also access restrictions for vehicles carrying hazardous materials as provided by the `hazmat` tag. | `true` | diff --git a/docs/versions/v8.2.0/run-instance/configuration/ors/messages/index.md b/docs/versions/v8.2.0/run-instance/configuration/ors/messages/index.md new file mode 100644 index 0000000000..4761fd1163 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/ors/messages/index.md @@ -0,0 +1,52 @@ + +# ors.messages + +System messages that can be sent with API responses following simple rules. + +The `ors.messages` block expects a list of elements, each of which having the following: + +| key | type | description | example value | +|-----------|---------|------------------------------------------------------------------|--------------------| +| active | boolean | Enables or disables this message | `true` | +| text | string | The message text | `The message text` | +| condition | list | optional; may contain any of the conditions from the table below | | + +## condition + +Properties beneath `ors.messages.condition`: + +| key | value | description | +|--------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +| time_before | ISO 8601 datetime string | message sent if server local time is before given point in time | +| time_after | ISO 8601 datetime string | message sent if server local time is after given point in time | +| api_version | 1 or 2 | message sent if API version requested through matches value | +| api_format | String with output formats ("json", "geojson", "gpx"), comma separated | message sent if requested output format matches value | +| request_service | String with service names ("routing", "matrix", "isochrones", "snap"), comma separated | message sent if requested service matches one of the given names | +| request_profile | String with profile names, comma separated | message sent if requested profile matches one of the given names | +| request_preference | String with preference (weightings for routing, metrics for matrix, rangetype for isochrones) names, comma separated | message sent if requested preference matches one of the given names | + +If multiple conditions are given, all must be fulfilled to trigger the sending of the corresponding message. + +Example: + +``` +messages: + - active: true + text: This message would be sent with every routing bike fastest request + condition: + - request_service: routing + - request_profile: cycling-regular,cycling-mountain,cycling-road,cycling-electric + - request_preference: fastest + - active: true + text: This message would be sent with every request for geojson response + condition: + - api_format: geojson + - active: true + text: This message would be sent with every request on API v1 from January 2020 until June 2050 + condition: + - api_version: 1 + - time_after: 2020-01-01T00:00:00Z + - time_before: 2050-06-01T00:00:00Z + - active: true + text: This message would be sent with every request +``` diff --git a/docs/versions/v8.2.0/run-instance/configuration/spring/index.md b/docs/versions/v8.2.0/run-instance/configuration/spring/index.md new file mode 100644 index 0000000000..29a4acec11 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/spring/index.md @@ -0,0 +1,5 @@ +# Spring Properties + +Since **openrouteservice** is based on spring, all common +[spring properties](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) can be set in the `ors-config.yml` file. + diff --git a/docs/versions/v8.2.0/run-instance/configuration/spring/logging.md b/docs/versions/v8.2.0/run-instance/configuration/spring/logging.md new file mode 100644 index 0000000000..b157386c28 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/spring/logging.md @@ -0,0 +1,16 @@ +# `logging` + +By default, openrouteservice logs status and error messages both to the console and a log file. No access logs are kept for requests. + +Logging can be configured using spring properties in the `logging.` space, for a full list see the [spring docs](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties.core). + +The most important ones are: + +| key | type | description | default value | +|--------------------------|--------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| logging.file.name | string | Path/filename of the log file | `./logs/ors.log` | +| logging.pattern.console | string | Pattern for log messages to console | `%d{YYYY-MM-dd HH:mm:ss} %highlight{%-7p} %style{%50t}{Cyan} %style{[ %-40.40c{1.} ]}{Bright Cyan} %m%n` | +| logging.pattern.file | string | Pattern for log messages to log file | `%d{YYYY-MM-dd HH:mm:ss} %-7p [ %-40.40c{1.} ] %m%n` | +| logging.level.root | string | Default log level | `WARN` | +| logging.level.org.heigit | string | Log level for message from the org.heigit namespace | `INFO` | + diff --git a/docs/versions/v8.2.0/run-instance/configuration/spring/server.md b/docs/versions/v8.2.0/run-instance/configuration/spring/server.md new file mode 100644 index 0000000000..2b6ead6e34 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/configuration/spring/server.md @@ -0,0 +1,13 @@ +# `server` + +General server properties used by spring + +| key | type | description | default value | +|-----------------------------|--------|---------------------------------|---------------| +| server.port | int | Server HTTP port | `8082` | +| server.servlet.context-path | string | Context path of the application | `/ors` | + +::: info +Other [spring server properties](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties.server) +might work out of the box, but are untested. +::: \ No newline at end of file diff --git a/docs/versions/v8.2.0/run-instance/data.md b/docs/versions/v8.2.0/run-instance/data.md new file mode 100644 index 0000000000..e4fc90923e --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/data.md @@ -0,0 +1,63 @@ +# Data: Input and output folders and files + +## Input Files + +The most important input file is the config file. +In the [Configuration](configuration/index.md) section you find everything about configuration options and files. + +Openrouteservice makes use of public open-source data. To generate the best routes, a number of different datasets are used. + +### OSM Data +The base data used for the road network and related information (road type, access restrictions etc.) is [OpenStreetMap](https://openstreetmap.org) (OSM). This dataset is a free and open dataset that can be edited by anyone. +You can download the latest OSM dataset from https://planet.openstreetmap.org/ or regional extracts from http://download.geofabrik.de/. + +The OSM file to be used needs be configured with the property [`ors.engine.source_file`](configuration/ors/engine/index.md). + +### Elevation +The data used for elevation are [SRTM](http://srtm.csi.cgiar.org/) and [GMTED](https://www.usgs.gov/coastal-changes-and-impacts/gmted2010). + +Configuration: [`ors.engine.elevation`](configuration/ors/engine/elevation.md) + +### Population +When requesting isochrones, you can also request to get population data for the isochrone areas. The data used for this is the [Global Human Settlement Layer (GHSL)](https://ghsl.jrc.ec.europa.eu/ghs_pop2023.php) from the European Commission. +Note, that while the dataset was published in 2023, the most recent data contained is from 2020. This is used by the openrouteservice at a resolution of 100m. + +### Borders +Data relating to the avoid borders features is derived from administrative boundaries features in OpenStreetMap. Information about open borders is obtained from [Wikipedia](https://en.wikipedia.org/wiki/Open_border). + +Configuration parameters: [`ors.engine.profiles.*.ext_storages.Borders`](configuration/ors/engine/profiles.md#borders) + +### GTFS +The public transport profile integrates [GTFS](https://developers.google.com/transit/gtfs) data for the public transit part. GTFS feeds can be obtained e.g. from sites like https://gtfs.de/ (for Germany), or from local public transport operators. + +Configuration parameters: [`ors.engine.profiles.*.gtfs_file`](configuration/ors/engine/profiles.md) + +### Green & Quiet +The data used to identify green and quiet routes were derived from research projects in the GIScience research group at Heidelberg University. +More information about these can be found on the GIScience news blog [here](https://giscienceblog.uni-heidelberg.de/2017/07/03/healthy-routing-prefering-green-areas-added-to-openrouteserviceorg/) and [here](http://giscienceblog.uni-heidelberg.de/2017/07/10/reducing-stress-by-avoiding-noise-with-quiet-routing-in-openrouteservice/) + +Configuration parameters: [`ors.engine.profiles.*.ext_storages`](configuration/ors/engine/profiles.md#ext-storages) + + +## Output Files + +Openrouteservice produces output files of three types, for which the paths can be configured. The directories these paths point to need to be *writable*. + +### Graphs + +openrouteservice reads the input data and computes a graph for each enabled routing profile. + +The root directory for the graphs can be configured with the configuration property [`ors.engine.graphs_root_path`](configuration/ors/engine/index.md). + +### Elevation Cache + +If elevation is activated in the configuration, openrouteservice will download and cache the elevation data tiles in a directory +which can be configured with the property [`ors.engine.elevation.cache_path`](configuration/ors/engine/index.md). + +### Logs + +Log output is written to auto-rotated log files. +See chapter [logging](configuration/spring/logging.md) for details on configuring the location of log files. + + + diff --git a/docs/versions/v8.2.0/run-instance/index.md b/docs/versions/v8.2.0/run-instance/index.md new file mode 100644 index 0000000000..609d0645e4 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/index.md @@ -0,0 +1,79 @@ +# Running your own openrouteservice instance + +If you need to customize the behavior of openrouteservice or if the features or quota provided by our public API is not +sufficient for your needs, you can run your own openrouteservice instance on a server or your local computer. In an own +instance, you can activate all endpoints, also those that are not available in our public API. + +There are different options to achieve this. The service can be built in the form of different artifact types: **WAR**, +**JAR** or as **Docker Image**. In the first column of the table below you find a link to some basic information about +each artifact type. + +No matter how you want to run your openrouteservice, you first need the corresponding artifact. The second and third +columns link to detail information about how to build a customized version yourself or where you can download the +artifact. + +For configuration, operation and troubleshooting it plays no role, if you run a downloaded or customized version (as +long as you don't change basic things like configuration). You find links to information about these topics in the three +right columns. + +But before you start operating your own openrouteservice in the technical way of your choice, please read the +documentation regarding [System Requirements](system-requirements) and [Data](data)! + +| Artifact | Download | or build yourself | Run | Configure | Trouble shoot | +|----------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------| +| [JAR](running-jar.md) | [Download JAR](running-jar.md#download) | [Build JAR](building-from-source.md#build-jar) | [Run JAR](running-jar.md#run) | [Configure JAR](running-jar.md#configure) | [Troubleshoot JAR](running-jar.md#troubleshoot) | +| [WAR](running-war.md) | [Download WAR](running-war.md#download) | [Build WAR](building-from-source.md#build-war) | [Run WAR](running-war.md#run) | [Configure WAR](running-war.md#configure) | [Troubleshoot WAR](running-war.md#troubleshoot) | +| [Docker Image](running-with-docker.md) | [Download Docker Image](running-with-docker.md#running-prebuilt-images) | [Build Docker Image](running-with-docker.md#build-image) | [Run Docker Image](running-with-docker.md#running-prebuilt-images) | [Configure Docker Image](running-with-docker.md#configure) | [Troubleshoot Docker Image](running-with-docker.md#troubleshoot) | +| [Source code](building-from-source.md) | [Download source code](building-from-source.md#download-source-code) | | [Run source code](building-from-source.md#run-source-code-directly) | [Configure](building-from-source.md#configure) | | + +[//]: # (TODO add row for rpm package once integrated) + +::: tip +We recommend to use the docker option for simplicity, or plain JAR if you do not want to install Docker. +::: + +## Checking + +By default, the service status can be queried via the [health endpoint](../api-reference/endpoints/health/index.md). + +```shell +curl 'http://localhost:8080/ors/v2/health' +# should result in an output like +# {"status":"ready"} +``` + +When the service is ready, you will be able to request the [status endpoint](../api-reference/endpoints/status/index.md) +for further information on the running services. + +```shell +curl 'http://localhost:8080/ors/v2/status' +# should result in an output like +# {"languages":["cs","cs-cz","de","de-de","en","en-us","eo","eo-eo","es","es-es","fr","fr-fr","gr","gr-gr","he","he-il","hu","hu-hu","id","id-id","it","it-it","ja","ja-jp","ne","ne-np","nl","nl-nl","pl","pl-pl","pt","pt-pt","ro","ro-ro","ru","ru-ru","tr","tr-tr","zh","zh-cn"],"engine":{"build_date":"2024-01-02T16:34:45Z","version":"8.0"},"profiles":{"profile 1":{"storages":{"WayCategory":{"gh_profile":"car_ors_fastest_with_turn_costs"},"HeavyVehicle":{"gh_profile":"car_ors_fastest_with_turn_costs"},"WaySurfaceType":{"gh_profile":"car_ors_fastest_with_turn_costs"},"RoadAccessRestrictions":{"gh_profile":"car_ors_fastest_with_turn_costs","use_for_warnings":"true"}},"profiles":"driving-car","creation_date":"","limits":{"maximum_distance":100000,"maximum_waypoints":50,"maximum_distance_dynamic_weights":100000,"maximum_distance_avoid_areas":100000}}},"services":["routing","isochrones","matrix","snap"]} +``` + +If you use the default dataset you will be able to request something like the following route request to the car profile +in Heidelberg. + +```shell +curl 'http://localhost:8080/ors/v2/directions/driving-car?start=8.681495,49.41461&end=8.687872,49.420318' +``` + + +## Instance infrastructure + +Though having a single instance of openrouteservice works great for smaller datasets or when the graph data doesn't need updating, in many +real world implementations having just the one instance isn't the most suitable solution. If you have one instance, +then all building and serving of routes happens through that single instance, meaning that when you rebuild graphs, you +can't make any requests to that instance for things like directions as there are no complete graphs that can be used to +generate routes with. If it is important that you have graph updates from new data whilst ensuring that there is a +minimal amount of time during which users cannot make requests, we would recommend having two instances - one that is +permanently active for serving requests, and one that gets fired up to rebuild graphs. + +In that setup, when graphs have been built you can simply stop the container serving requests, replace the graphs used ( +they are mapped to a folder on the host machine which is defined in the `docker-compose` file), and then restart the +"request" instance. The new graphs will be reloaded into memory (the amount of time needed for this depends on the size of the +graphs and the type of hard drive) and then ready to use for routing. The downtime from reloading already built graphs +is normally far less than the time needed to build the graphs. A thing to note though is that you should ensure that the +config files and the amount of RAM allocated (as described earlier) is the same on both the builder and the request +server else the newly built graphs may not load. **Also, ensure that `REBUILD_GRAPHS` parameter used by the request serving container +is set to false else it will try to build the graphs for itself!** diff --git a/docs/versions/v8.2.0/run-instance/running-jar.md b/docs/versions/v8.2.0/run-instance/running-jar.md new file mode 100644 index 0000000000..24b3d1b843 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/running-jar.md @@ -0,0 +1,89 @@ +# Running openrouteservice as JAR + +Since version 8, openrouteservice can be built as a fat JAR file that contains all its dependencies and can be run as stand-alone application. + +## Prerequisites + +* [java](https://www.java.com/en/) 17 (or higher) should be available, preferably as default Java environment. + +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details, see chapter [Data](data.md). + +## Download + +Starting with version 8 you can download the ready to use JAR file from the "Assets" section of the desired release from our GitHub [releases](https://github.com/GIScience/openrouteservice/releases) page. + +## Build + +How this is done is independent of the artifact type you want to use and is documented in [Building from Source](building-from-source.md). + +## Run + +To run the openrouteservice application, use the following command: + +```shell +java -jar ors.jar +``` + +## Configure + +The recommended way to configure an openrouteservice instance run plain using the JAR file is to use a YAML configuration file. You can download an example file by using the following command: + +```shell +wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/ors-config.yml +``` + +For details on how to make openrouteservice apply the settings in the configuration file (there are multiple options) see chapter [Configuration](configuration/index.md). + +## Troubleshooting + +The place where the log files are written is defined by the configuration property `logging.file.name`. +In the [logging documentation](configuration/spring/logging.md) you find more logging options like setting log level etc. + +The openrouteservice startup log looks similar to this: +```shell +ors-app | ▢ Startup command: java -Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost -jar /ors.jar +ors-app | +ors-app | . ____ _ __ _ _ +ors-app | /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ +ors-app | ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ +ors-app | \\/ ___)| |_)| | | | | || (_| | ) ) ) ) +ors-app | ' |____| .__|_| |_|_| |_\__, | / / / / +ors-app | =========|_|==============|___/=/_/_/_/ +ors-app | :: Spring Boot :: (v3.1.6) +ors-app | +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.Application ] Starting Application v8.0-SNAPSHOT using Java 21.0.2 with PID 1 (/ors.jar started by root in /home/ors) +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.Application ] The following 1 profile is active: "default" +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration lookup started. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration file set by environment variable. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Loaded file '/home/ors/config/ors-config.yml' +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration lookup finished. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.a.s.l.ORSInitContextListener ] Initializing ORS... +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] Total - 1024 MB, Free - 965.93 MB, Max: 2 GB, Used - 58.07 MB +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] ====> Initializing profiles from '/home/ors/files/example-heidelberg.osm.gz' (1 threads) ... +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] 2 profile configurations submitted as tasks. +ors-app | 2024-03-12 10:54:46 INFO ORS-pl-wheelchair [ o.h.o.r.RoutingProfile ] [1] Profiles: 'wheelchair', location: './graphs/wheelchair'. +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] version v4.9.1|2024-01-17T09:08:46Z (7,20,5,4,5,7) +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] graph wheelchair|RAM_STORE|3D|turn_cost|,,,,, details:edges:0(0MB), nodes:0(0MB), name:(0MB), geo:0(0MB), bounds:1.7976931348623157E308,-1.7976931348623157E308,1.7976931348623157E308,-1.7976931348623157E308,1.7976931348623157E308,-1.7976931348623157E308 +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] No custom areas are used, custom_areas.directory not given +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] start creating graph from /home/ors/files/example-heidelberg.osm.gz +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] using wheelchair|RAM_STORE|3D|turn_cost|,,,,, memory:totalMB:1024, usedMB:260 +ors-app | 2024-03-12 10:54:47 INFO main [ o.h.o.a.Application ] Started Application in 2.442 seconds (process running for 3.066) +ors-app | 2024-03-12 10:54:47 INFO main [ o.h.o.a.Application ] openrouteservice {"build_date":"2024-03-08T15:01:47Z","version":"8.0"} +``` + +Most important information here: + +* The version of openrouteservice and java: `Starting Application v8.0-SNAPSHOT using Java 21.0.2` +* The evaluated configuration file: `Loaded file '/home/ors/config/ors-config.yml'` +* Memory usage: `Total - 1024 MB, Free - 965.93 MB, Max: 2 GB, Used - 58.07 MB` +* The evaluated OSM file: `====> Initializing profiles from '/home/ors/files/example-heidelberg.osm.gz'` +* Potential errors with your setup + +After the startup section, you can find information about errors at run time. + +::: tip Hint +The output `The following 1 profile is active: "default"` is from spring, +it refers to the active **spring profile** and has nothing to do with routing profiles. +::: diff --git a/docs/versions/v8.2.0/run-instance/running-war.md b/docs/versions/v8.2.0/run-instance/running-war.md new file mode 100644 index 0000000000..23e066caf2 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/running-war.md @@ -0,0 +1,44 @@ +# Running openrouteservice as WAR + +Like older versions, ORS version 8 can still be built and run as a Web Application Resource aka Web Archive (WAR). +A WAR file can be deployed to a Servlet Container like Tomcat, which is running as a service. +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details see chapter [Data](data.md). + +## Prerequisites + +* [Tomcat](https://tomcat.apache.org/) 10 (or higher) should be installed. E.g. on Ubuntu 22.04, follow these [instructions](https://linuxize.com/post/how-to-install-tomcat-10-on-ubuntu-22-04/). + +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details, see chapter [Data](data.md). + +## Download + +Starting with version 8 you can download the ready to use WAR from the "Assets" section of the desired release from our GitHub [releases](https://github.com/GIScience/openrouteservice/releases) page. + +## Build + +How this is done is independent of the artifact type you want to use and is documented in [Building from Source](building-from-source.md). + +## Run + +Running a WAR file means deploying it to a Tomcat instance. To get openrouteservice up and running, simply copy the `ors.war` file to the Tomcat webapps folder. Tomcat should now automatically detect the new WAR file and deploy the service. + +## Configure + +When deploying openrouteservice within Tomcat, there are some important differences to note: +- The recommended way to pass instructions to openrouteservice is to use environment variables. You need to add these to the `setenv.sh` file in your tomcat bin folder, typically somewhere like `/usr/share/tomcat10/bin/`. If the file is not present, then you can create it. +- If you add new settings to the `setenv.sh` file, then you need to restart Tomcat for these to take effect using a command like `sudo systemctl restart tomcat.service`. +- Your configuration file and all input / output files and directories referenced by that configuration need to be accessible (and in case of the output folders, writable) to the user your Tomcat instance is running as. You might need to adjust the location of said files and folders or `chmod` / `chown` them accordingly. + +The recommended way to configure an openrouteservice instance is to use a YAML configuration file. You can download an example file by using the following command: + +```shell +wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/ors-config.yml +``` + +Then you need to add an environment variable to your `setenv.sh` pointing to that configuration file: + +```shell +ORS_CONFIG_LOCATION=/path/to/ors-config.yml +``` + +For details on how to make openrouteservice apply the settings in the configuration file (there are multiple options) see chapter [Configuration](configuration/index.md). diff --git a/docs/versions/v8.2.0/run-instance/running-with-docker.md b/docs/versions/v8.2.0/run-instance/running-with-docker.md new file mode 100644 index 0000000000..20e2ba79dc --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/running-with-docker.md @@ -0,0 +1,517 @@ +# Running with Docker + +If Docker is available on your system, the easiest way to run openrouteservice is starting a [prebuilt image](#running-prebuilt-images). +You don't need to clone the openrouteservice repository, the source code is not needed to run a prebuilt image. +Also, java and maven don't have to be installed. + +If you have special requirements, you can also [build your customized docker image](building-from-source.md#build-docker-image). + +::: warning +The docker documentation is only valid for openrouteservice since v8.0.0! +::: + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) has to be installed on your system. +- An OSM extract, e.g. from [Geofabrik](http://download.geofabrik.de) or for small areas directly export + from [osm.org](https://www.openstreetmap.org/export#map=15/49.4197/8.6893). + +No java or maven required unless you want to build a customized docker image :) + + +## Running prebuilt images + +The openrouteservice team provides a `docker compose` file that pulls and starts the prebuilt openrouteservice docker image for a specific version in one simple command. +Starting with openrouteservice v8.0.0, you can (and should) download the compose file from the "assets" section +on the [releases page](https://github.com/GIScience/openrouteservice/releases), in the browser or e.g. with + +```shell +wget https://github.com/GIScience/openrouteservice/releases/download/v8.0.0/docker-compose.yml +``` + +Now start openrouteservice in the background: +```shell +docker compose up -d +``` + +This will pull the openrouteservice of the selected version and start it up using an example setup +and the provided test OSM file for Heidelberg/Germany and surrounding area. + +To see the container's logs, run +```shell +docker compose logs +``` +or +```shell +docker compose logs -tf +``` +to follow the log. + +To stop the container again, execute +```shell +docker compose stop +``` +or +```shell +docker compose down +``` +to stop and remove the container. + +The file `docker-compose.yml` contains plenty of commented options with descriptions. +You can un-comment those options and set your custom option values. + +::: details Running without docker compose +It is easier to modify the Docker compose file, but to test a specific setup, you can also run a command similar to what docker compose would run directly on the command line. +Here is a basic example: +```shell +# create directories for volumes to mount as local user +mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/graphs ors-docker/files ors-docker/logs +docker run -dt --name ors-app \ + -p 8080:8082 \ + -v $PWD/ors-docker/config:/home/ors/config \ + -v $PWD/ors-docker/elevation_cache:/home/ors/elevation_cache \ + -v $PWD/ors-docker/graphs:/home/ors/graphs \ + -v $PWD/ors-docker/files:/home/ors/files \ + -v $PWD/ors-docker/logs:/home/ors/logs \ + -e "XMS=1g" \ + -e "XMX=2g" \ + local/openrouteservice:latest +``` +Add `-e "ors.engine.source_file=files/your.osm.pbf" \` to point to your own OSM file that lies in the mounted $PWD/ors-docker/files folder. +Add `-e "BUILD_GRAPHS=True" \` to trigger a graph rebuild. + +::: + + +## What you get + +After some time, your openrouteservice should be running: +```shell +curl http://localhost:8080/ors/v2/health +{"status":"ready"} +``` + +When you have started the container as described, a directory `ors-docker` with some sub directories and files are created by docker: +```shell +. +├── docker-compose.yml +└── ors-docker + ├── config + │   ├── example-ors-config.env + │   ├── example-ors-config.yml + │   └── ors-config.yml + ├── elevation_cache + │   ├── srtm_38_03.gh + │   └── srtm_38_03.zip + ├── files + │   └── example-heidelberg.osm.gz + ├── graphs + │   └── car + │   ├── edges + │   ├── ... + │   ├── ... + │   └── turn_costs + └── logs + └── ors.log + +8 directories, 35 files +``` + +* `example-ors-config.env`: env file template. A customized copy of this file can be used in combination with the `docker-compose.yml`, see [Set properties in an environment file](#set-openrouteservice-properties-in-an-environment-file). Do not edit this file directly since it will be overridden by docker! +* `example-ors-config.yml`: YAML file template. A customized copy of this file can be used as `ors-config.yml`, see [Use customized config file](#use-customized-config-file). Do not edit this file directly since it can be overridden by docker: If e.g. a newer docker image tag is used in the `docker-compose.yml`, the `example-ors-config.yml` might be updated if in the newer version of openrouteservice there are changes in the configuration properties or their default values. The updated file can be compared with the customized `ors-config.yml`. +* `ors-config.yml`: The default config used by the openrouteservice inside the container. This file will not be overridden by docker. Initially, the file is identical to `example-ors-config.yml`. See [Use customized config file](#use-customized-config-file) +* `elevation_cache`: Directory, where openrouteservice stores downloaded elevation data to avoid repeated downloads. +* `example-heidelberg.osm.gz`: The initial sample OSM data used to run the container in its initial setup. Normally, you will remove this file or add another OSM file to the same directory and adapt your config to use your file. +* `graphs`: Directory for the generated graphs. Initially, there is only `car` because this is the only enabled routing profile in the default `ors-config.yml` +* `logs`: Here, the openrouteservice logs are stored. :warning: Logs of several runs will be accumulated here. In contrast, the logs you get with `docker compose logs` are only logs of the current run, but on the other hand they contain very helpful logging from docker or the entrypoint script, which is not visible in the files in `logs`. + + +### Avoid files owned by root + +With the default `docker-compose.yml`, the generated files are owned by root. +If you don't have root permissions (sudo) or you just don't want root owned files in your bind-mounts from the container, e.g. cannot edit or add files in `ors-docker/config`, the container provides the possibility to be run with UID 1000 and GID 1000. To be able to access these files, you need to have either the UID 1000 or be part of the group 1000 on your docker host machine. +Of course, you can configure openrouteservice with the help of the `docker-compose.yml` (see [here](#set-openrouteservice-properties-in-docker-composeyml)) or a referenced environment file (see [there](#set-openrouteservice-properties-in-an-environment-file)), +which needs not to be located in the config folder because the openrouteservice running inside docker don't need to 'see' the environment file. + +But if you for example want to save a new pbf file to `ors-docker/files`, then you need sudo rights. + +To avoid root ownership of the generated folders and files, + +1. uncomment the 'user' line in your `docker-compose.yml`: + ```yaml + #user: "1000:1000" // [!code --] + user: "1000:1000" // [!code ++] + ``` +2. create the folders with your user, so your user should be owner of the folders: + ```shell + mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/files ors-docker/graphs ors-docker/logs + ``` + If the folders already exist (owned by root) and you don't want to delete them, you can change their ownership (again root permissions required). +3. When you now run `docker compose down && docker compose up -d`, the files and folders should be editable for your user. + +As you can see in the `docker-compose.yml` snippet above, this works for the user with user-id 1000 and group-id 1000, which is the default for the first normal user on a linux host. +But if you have different user- and group-id, the formula does not work for you. + +You can check your own user-id (uid) and group-id (gid) with the command +```shell +id +``` + +If you have different uid/gid, then what you still can do is building your own docker image after specifying your uid and gid in your docker compose file. +Let's say, you have uid=1003 and gid=1003: + +1. Edit your `docker-compose.yml`: + ```yaml + #user: "1000:1000" // [!code --] + user: "1003:1003" // [!code ++] + ``` +2. Build your docker image locally as described in [build your customized docker image](building-from-source.md#build-docker-image) +3. Now you should be able to do steps 2. and 3. as described above. + + +### Directories inside the Container and on the Host + +The docker container is a kind of minimalistic linux system with a specific openrouteservice setup. +Internally, the correct java version is installed which is used to run the openrouteservice fat jar. + +The **internal** working directory, where openrouteservice is started, is `/home/ors`. +The internal openrouteservice is configured to use the sub folders of this working directory as locations where +specific input files are expected or where generated data are written to: + +* `/home/ors/config` +* `/home/ors/graphs` +* `/home/ors/files` +* `/home/ors/logs` +* `/home/ors/elevation_cache` + + +Absolute paths in the yml like +```yaml + source_file: /home/ors/files/example-heidelberg.osm.gz +``` +are interpreted as absolute **inside** the container. + +Relative paths like +```yaml + cache_path: ./elevation_cache +``` +are intepreted as relative to the work directory `/home/ors` inside the container. + + +## Use different directories as your bind mounts + +If you want to mount existing folders of your host file system, that are not sub folders of your openrouteservice docker working directory `ors-docker`, +you can change the volumes section in your `docker-compose.yml`. + +In the following example, a user has a directory `/data/osm` with OSM files. The user wants to reference the files from there directly instead of copying the large files somewhere else. +And the graph files generated by openrouteservice should also be stored into a different location, where more disk space is available than in the home directory, let's say in `/data/ors/graphs`. + +The directories required by the internal openrouteservice are mounted individually, +the paths on the host system are defined before the colon, the (unchanged) directory inside the container behind the colon. + +```yaml + volumes: # Mount relative directories. ONLY for local container runtime. To switch to docker managed volumes see 'Docker Volumes configuration' section below. + - ./ors-docker:/home/ors // [!code --] + - /data/ors/graphs:/home/ors/graphs // [!code ++] + - ./ors-docker/elevation_cache:/home/ors/elevation_cache // [!code ++] + - ./ors-docker/config:/home/ors/config // [!code ++] + - ./ors-docker/logs:/home/ors/logs // [!code ++] + - /data/osm:/home/ors/files // [!code ++] +``` + +With these changes, a `source_file` configured in `ors-config.yml`: + +```yaml + source_file: ./files/andorra-latest.osm.pbf +``` + +now references the file `/data/osm/andorra-latest.osm.pbf` on the host file system. + +::: warning Note +When individual host directories are mounted to the internal sub directories of `/home/ors`, +no directory can be mounted directly to the internal `/home/ors`! +::: + +## Use Volumes + +Instead of using bind mounts, you can use volumes. Uncomment **and complete** the volume definition in the `docker-compose.yml` (see [docker compose documentation](https://docs.docker.com/compose/compose-file/07-volumes/)): + +```yaml +# ----------------- Docker Volumes configuration ------------------- # +# Define the Docker managed volumes for the ORS application. For more info on Docker Volumes see https://docs.docker.com/compose/compose-file/07-volumes/ +# Volumes are used to persist the data and configuration of the ORS application. +# If you want to use volumes, uncomment the following lines and remove the ./ prefix from the volume paths in 'services.ors-app.volumes'. +#volumes: // [!code --] +# graphs: // [!code --] +# elevation_cache: // [!code --] +# config: // [!code --] +# logs: // [!code --] +# files: // [!code --] +volumes: // [!code ++] + graphs: // [!code ++] + elevation_cache: // [!code ++] + config: // [!code ++] + logs: // [!code ++] + files: // [!code ++] +``` + +In the yml section services.ors-app.volumes of your `docker-compose.yml` you set the volume names instead of host paths on the left side of the colon: +```yaml +services: + ors-app: + volumes: + - ./ors-docker:/home/ors # Mount the ORS application directory (for logs, graphs, elevation_cache, etc.) into its own directory // [!code --] + #- ./graphs:/home/ors/graphs # Mount graphs directory individually // [!code --] + #- ./elevation_cache:/home/ors/elevation_cache # Mount elevation cache directory individually // [!code --] + #- ./config:/home/ors/config # Mount configuration directory individually // [!code --] + #- ./logs:/home/ors/logs # Mount logs directory individually // [!code --] + #- ./files:/home/ors/files # Mount files directory individually // [!code --] + #- ./ors-docker:/home/ors # Mount the ORS application directory (for logs, graphs, elevation_cache, etc.) into its own directory // [!code ++] + - graphs:/home/ors/graphs # Mount graphs directory individually // [!code ++] + - elevation_cache:/home/ors/elevation_cache # Mount elevation cache directory individually // [!code ++] + - config:/home/ors/config # Mount configuration directory individually // [!code ++] + - logs:/home/ors/logs # Mount logs directory individually // [!code ++] + - files:/home/ors/files # Mount files directory individually // [!code ++] +``` + +## Configure + +When using the openrouteservice docker image, you have several configuration options: + +* You can use a configuration file as you would do when running openrouteservice as JAR or WAR. If you are the owner of the files in `ors-docker/config`, this is straight forward (see [above](#avoid-files-owned-by-root)). +* You can set configuration properties as environment variables in the `docker-compose.yml` +* or you can set configuration properties in an environment file. This is good practice for docker containers in general and the preferred way to configure dockered openrouteservice when the files are owned by root. + +The following sections explain these options in more detail. +For detailed information on the configuration settings you can make, see the chapter +on [configuration](configuration/index.md). + +::: tip +If you want to re-build the graphs, many people just delete the graphs folders and restart openrouteservice. +If you are not owner of the graphs files (but root), you _cannot_ delete those files without root permissions. +In this case, you can set the environment variable `REBUILD_GRAPHS=True` in your [`docker-compose.yml`](#set-openrouteservice-properties-in-docker-composeyml) (the option is contained in the file, just un-comment it) +or in your [`ors-config.env`](#set-openrouteservice-properties-in-an-environment-file). +openrouteservice will then re-build all activated graphs on the next startup. +::: + +### Use (customized) config file + +As described in [Configuration > File location](configuration/index.md#file-location), +when openrouteservice is started, it looks for a file named `ors-config.yml` in different directories and uses the file, if it exists. +Alternatively, an individually named or located configuration file (YAML or the deprecated JSON config) can be used by setting the environment variable `ORS_CONFIG_LOCATION`. + +In the Docker version, there is an initialization script that is executed on each container start, +which is using a slightly different approach: + +* It checks if `ORS_CONFIG_LOCATION` is set and if the referenced file (YAML or the deprecated JSON config) can be found (the path is evaluated from [inside the container](#directories-inside-the-container-and-on-the-host)). + If this is the case, this config will be used. +* Otherwise, the file `/home/ors/config/ors-config.yml` or `/home/ors/config/ors-config.json` is searched (path inside container). If it is there, it will be loaded. + If not, it will be added as copy of `/home/ors/config/example-ors-config.yml` **and also be loaded!** + +This means, that in any case, a config file is loaded! +Even if you set environment variables as described in the next two sections, +you have to take care of the config file that is loaded, and in some cases you have to override single properties, +e.g. disable the routing profile `car` - which is enabled in the default `ors-config.yml` - if you don't want it to be enabled. + +You can configure your openrouteservice by editing the generated `ors-config.yml`. +This file will never been overridden by openrouteservice, if it still exists. +But you should never edit `example-ors-config.yml` `example-ors-config.env` - these files will be replaced in some cases. + + +### Set openrouteservice properties in `docker-compose.yml` + +It is possible to pass openrouteservice configuration properties into a docker container as environment variables. +The `docker-compose.yml` contains many available configuration options as comments, with a short description. +The following example snippet of the modified `docker-compose.yml` shows a setup where the car profile is disabled and wheelchair is enabled: + +```yaml + environment: + # ----------------- Properties configuration ------------------- # + # Configure your whole container with only property ENVs. + # These can be set alternatively or additionally to the yml configuration file. + # Note, that any values set will override the corresponding values from the yml configuration file. + # See the ors-config.env file for more options. + # To have a configuration file-less container, uncomment at least the following properties. + # The values are examples and provide the default configuration. + ors.engine.source_file: /home/ors/files/andorra-latest.osm.pbf + ors.engine.profiles.car.enabled: false + ors.engine.profiles.wheelchair.enabled: true + # Here you can also set more advanced spring and tomcat properties, such as proxy settings. + # See the spring documentation for a complete list of options: https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html + #server.tomcat.remote-ip-header=x-your-remote-ip-header + #server.tomcat.protocol-header=x-your-protocol-header +``` + +::: warning Hint +Remember that the container has to be newly created for the changes in `docker-compose.yml` to take effect! +`docker compose stop && docker compose start` or `docker compose restart` is not enough, you have to execute +```shell +docker compose down && docker compose up +``` +::: + +The syntax/name of the configuration properties is not yaml but instead the syntax from java properties files. +But it is just a different syntax. The properties are the same as described in [Configuration > File Formats](configuration/index.md#file-formats). + +### Set openrouteservice properties in an Environment file + +Configuring properties in `docker-compose.yml` is a good way to set a handful of properties. +If you want to customize a great number of properties or if you maybe have different configurations in use, +it is more convenient to save the properties to a separate file. + +The properties that were set in in the `docker-compose.yml` snippet in the previous section could instead be set in a separete file `ors-config.env`. +The only difference is, that equal signs are used instead of colons: + +``` +ors.engine.source_file=/home/ors/files/andorra-latest.osm.pbf +ors.engine.profiles.car.enabled=false +ors.engine.profiles.wheelchair.enabled=true +``` + +The env file has to be referenced in the `docker-compose.yml`: +```yaml + # ----------------- ENV file configuration ------------------- # + # Too many variables for your 'environment:' section? + # Use an env_file with the ENV properties instead and define everything in there: + # Values will be overwritten if set in the 'environment' section. +# env_file: ors-config.env // [!code --] + env_file: ors-config.env // [!code ++] +``` + +If you want to use this configuration option and you start creating your environment file, +you can use the file `ors-docker/config/example-ors-config.env` as a template. +Copy it next to your `docker-compose.yml` or rename it. +You should never edit the file `ors-docker/config/example-ors-config.env` because it will be replaced by openrouteservice in some cases! + + +## Troubleshooting + +If openrouteservice cannot be started or does not operate as expected, it is most important to check the logs. +There are two ways to inspect the logs, with some differences: `docker compose logs` and `ors-docker/logs/ors.log` + +| `docker compose logs` | `ors-docker/logs/ors.log` | +|--------------------------------------------------|-------------------------------------------------------------------------------------------------| +| logs from docker entrypoint and openrouteservice | logs from openrouteservice only | +| logs from the current container only | logs from previous containers that were removed with e.g. `docker compose down` still available | + +This section will focus on the logs from docker because they contain additional information. +To see the container's entrypoint logs, change into your directory with the `docker-compose.yml` and run +```shell +docker compose logs +``` + +The first logged lines are written by the entrypoint script inside the container +which is executed on each container start _before_ the internal openrouteservice is started. +Here you can gain an insight into the internal workings of the container: + +```shell +ors-app | 2024-03-12T08:13:19.118290567Z ################# +ors-app | 2024-03-12T08:13:19.118317827Z # Container ENV # +ors-app | 2024-03-12T08:13:19.118320018Z ################# +ors-app | 2024-03-12T08:13:19.118321664Z ✓ CONTAINER_LOG_LEVEL: INFO. Set CONTAINER_LOG_LEVEL=DEBUG for more details. +ors-app | 2024-03-12T08:13:19.125163248Z ⓘ Any config file settings can be overwritten by environment variables. +ors-app | 2024-03-12T08:13:19.125181048Z ⓘ Use 'CONTAINER_LOG_LEVEL=DEBUG' to see the full list of active environment variables for this container. +ors-app | 2024-03-12T08:13:19.125193428Z ########################### +ors-app | 2024-03-12T08:13:19.125195433Z # Container sanity checks # +ors-app | 2024-03-12T08:13:19.125208729Z ########################### +ors-app | 2024-03-12T08:13:19.127963029Z ⓘ Running container as user root with id 0 and group 0 +ors-app | 2024-03-12T08:13:19.130316750Z ✓ ORS_HOME: /home/ors exists and is writable. +ors-app | 2024-03-12T08:13:19.134116420Z ✓ The file /home/ors/config/example-ors-config.env is up to date +ors-app | 2024-03-12T08:13:19.135634341Z ✓ The file /home/ors/config/example-ors-config.yml is up to date +ors-app | 2024-03-12T08:13:19.135753416Z ✓ Using existing /home/ors/config/ors-config.yml +ors-app | 2024-03-12T08:13:19.142101283Z ⓘ Default to graphs folder: /home/ors/graphs +ors-app | 2024-03-12T08:13:19.142118351Z ⓘ Default to example osm source file: "/home/ors/files/example-heidelberg.osm.gz" +ors-app | 2024-03-12T08:13:19.142119978Z ⓘ Any ENV variables will have precedence over configuration variables from config files. +ors-app | 2024-03-12T08:13:19.142151919Z ✓ All checks passed. For details set CONTAINER_LOG_LEVEL=DEBUG. +ors-app | 2024-03-12T08:13:19.142159578Z ##################################### +ors-app | 2024-03-12T08:13:19.142160979Z # Container file system preparation # +ors-app | 2024-03-12T08:13:19.142162089Z ##################################### +ors-app | 2024-03-12T08:13:19.199741022Z ✓ The file /home/ors/files/example-heidelberg.osm.gz is up to date +ors-app | 2024-03-12T08:13:19.199762468Z ✓ Container file system preparation complete. For details set CONTAINER_LOG_LEVEL=DEBUG. +ors-app | 2024-03-12T08:13:19.199764187Z ####################################### +ors-app | 2024-03-12T08:13:19.199765671Z # Prepare CATALINA_OPTS and JAVA_OPTS # +ors-app | 2024-03-12T08:13:19.199766895Z ####################################### +ors-app | 2024-03-12T08:13:19.200084573Z ✓ CATALINA_OPTS and JAVA_OPTS ready. For details set CONTAINER_LOG_LEVEL=DEBUG. +ors-app | 2024-03-12T08:13:19.200120626Z ##################### +ors-app | 2024-03-12T08:13:19.200127702Z # ORS startup phase # +ors-app | 2024-03-12T08:13:19.200129261Z ##################### +ors-app | 2024-03-12T08:13:19.200130392Z ✓ 🙭 Ready to start the ORS application 🙭 +``` + +As explained in the log, by setting `CONTAINER_LOG_LEVEL=DEBUG` in the `docker-compose.yml` you get more information. +This setting is only relevant for the entrypoint logging, it does not change the log level of openrouteservice. +How you can achieve this is documented in the [logging documentation](configuration/spring/logging.md). + +::: warning Hint +Remember that the container has to be newly created for the changes in `docker-compose.yml` to take effect! +`docker compose stop && docker compose start` or `docker compose restart` is not enough, you have to execute +```shell +docker compose down && docker compose up +``` +::: + +::: details Follow logs +If you want to watch the logs while openrouteservice is running, you can also +```shell +docker compose logs -tf +``` +to follow the log. Press Ctrl+C to stop tailing the log, the container will not be stopped. +::: + +Important information, that you will find in the entrypoint section of the docker log: + +* The user that is used inside the container, with uid and gid +* All environment variables inside the container (only with `CONTAINER_LOG_LEVEL=DEBUG`) +* Information about resolved paths inside the container +* Information about generation or replacement of example files +* Errors concerning the setup + +After the entrypoint section, there are the logs from openrouteservice itself. +The openrouteservice startup log looks similar to this: +```shell +ors-app | ▢ Startup command: java -Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost -jar /ors.jar +ors-app | +ors-app | . ____ _ __ _ _ +ors-app | /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ +ors-app | ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ +ors-app | \\/ ___)| |_)| | | | | || (_| | ) ) ) ) +ors-app | ' |____| .__|_| |_|_| |_\__, | / / / / +ors-app | =========|_|==============|___/=/_/_/_/ +ors-app | :: Spring Boot :: (v3.1.6) +ors-app | +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.Application ] Starting Application v8.0-SNAPSHOT using Java 21.0.2 with PID 1 (/ors.jar started by root in /home/ors) +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.Application ] The following 1 profile is active: "default" +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration lookup started. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration file set by environment variable. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Loaded file '/home/ors/config/ors-config.yml' +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] Configuration lookup finished. +ors-app | 2024-03-12 10:54:45 INFO main [ o.h.o.a.ORSEnvironmentPostProcessor ] +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.a.s.l.ORSInitContextListener ] Initializing ORS... +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] Total - 1024 MB, Free - 965.93 MB, Max: 2 GB, Used - 58.07 MB +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] ====> Initializing profiles from '/home/ors/files/example-heidelberg.osm.gz' (1 threads) ... +ors-app | 2024-03-12 10:54:46 INFO ORS-Init [ o.h.o.r.RoutingProfileManager ] 2 profile configurations submitted as tasks. +ors-app | 2024-03-12 10:54:46 INFO ORS-pl-wheelchair [ o.h.o.r.RoutingProfile ] [1] Profiles: 'wheelchair', location: './graphs/wheelchair'. +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] version v4.9.1|2024-01-17T09:08:46Z (7,20,5,4,5,7) +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] graph wheelchair|RAM_STORE|3D|turn_cost|,,,,, details:edges:0(0MB), nodes:0(0MB), name:(0MB), geo:0(0MB), bounds:1.7976931348623157E308,-1.7976931348623157E308,1.7976931348623157E308,-1.7976931348623157E308,1.7976931348623157E308,-1.7976931348623157E308 +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] No custom areas are used, custom_areas.directory not given +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] start creating graph from /home/ors/files/example-heidelberg.osm.gz +ors-app | 2024-03-12 10:54:47 INFO ORS-pl-wheelchair [ o.h.o.r.g.e.ORSGraphHopper ] using wheelchair|RAM_STORE|3D|turn_cost|,,,,, memory:totalMB:1024, usedMB:260 +ors-app | 2024-03-12 10:54:47 INFO main [ o.h.o.a.Application ] Started Application in 2.442 seconds (process running for 3.066) +ors-app | 2024-03-12 10:54:47 INFO main [ o.h.o.a.Application ] openrouteservice {"build_date":"2024-03-08T15:01:47Z","version":"8.0"} +``` + +Most important information here: + +* The version of openrouteservice and java: `Starting Application v8.0-SNAPSHOT using Java 21.0.2` (you do not have to worry about the Java version in the Docker setup) +* The evaluated configuration file: `Loaded file '/home/ors/config/ors-config.yml'` (this is the path inside the container) +* Memory usage: `Total - 1024 MB, Free - 965.93 MB, Max: 2 GB, Used - 58.07 MB` +* The evaluated OSM file: `====> Initializing profiles from '/home/ors/files/example-heidelberg.osm.gz'` (also internal path) +* Potential errors with your setup + +And after the startup section you will find information about errors at run time. + +::: tip Hint +The output `The following 1 profile is active: "default"` is from spring, +it refers to the active **spring profile** and has nothing to do with routing profiles. +::: diff --git a/docs/versions/v8.2.0/run-instance/system-requirements.md b/docs/versions/v8.2.0/run-instance/system-requirements.md new file mode 100644 index 0000000000..b2972b3311 --- /dev/null +++ b/docs/versions/v8.2.0/run-instance/system-requirements.md @@ -0,0 +1,41 @@ +# System Requirements + +When running openrouteservice, by far the biggest consideration that needs to be made is the amount of RAM that is available. Smaller areas such as Baden-Württemberg in Germany can run happily on a mid-range system, but for larger areas you need more RAM. For example, in the openrouteservice public API infrastructure, each profile for the planet is running on a 128GB machine. Anything less than that and you will run out of memory during the build process. + +The main things that affect the amount of RAM needed are: +* The size of the data being loaded (OSM data) +* The profile(s) being built (bike and pedestrian need more space than driving profiles) +* The routing optimisations (having the optimised routing algorithms needs more RAM) +* Elevation (using elevation needs the elevation data to also be loaded into RAM, so the larger the geographic area, the more RAM is needed for elevation) +* Extra info (Each profile can have extra info calculated, each of these requires RAM for storage). + +As a guide, you can look at the size of OSM data extracts as a rough guide as to how much RAM you would need. [Geofabrik](https://download.geofabrik.de) provides a number of these extracts along with the file sizes of the pbf files. The planet file is around 50GB and for bike and pedestrian profiles, this needs around 100-105GB RAM. Germany is around 3GB and can normally be built on a reasonable system with around 8GB RAM, and Baden-Württemberg is 450MB which can be built on a machine with around 2-4GB RAM. In general though, having more RAM also speeds up the build process as less garbage collection actions need to be taken, and you should also be aware of any other services running in parallel to openrouteservice that consume RAM on the machine. + +[//]: # (TODO: @koebi was working on a set of example memory footprint values or something similar? Add here) + +## JVM configuration + +Independent of the configuration of the openrouteservice itself, you might need to adjust settings of the Java Virtual Machine (JVM) running the code. Since the memory requirements of openrouteservice are proportional to the size of the OSM data (and therefore the resulting graph), the setting that needs to be adjusted most often is the heap memory size. + +[//]: # (TODO: elaborate) + +``` +JAVA_OPTS="-Xms105g -Xmx105g " +``` + +## Memory mapping in large builds with a containerized openrouteservice instance +If you are running a large build (e.g. a planet file) then you may need to increase the number of memory mappings. You only need to do this on the host machine as this value is used by the Docker containers running on it as well. To do this, go into the system configuration file with `sudo nano /etc/sysctl.conf` and add the following line to the bottom of the file: + +```shell +vm.max_map_count=81920 +``` + +The usual sign that you need to do this change is if you see something similar to the following in your logs: + +```shell +# There is insufficient memory for the Java Runtime Environment to continue. +# Native memory allocation (mmap) failed to map 16384 bytes for committing reserved memory. +# An error report file with more information is saved as: +# /ors-core/hs_err_pid128.log +``` + diff --git a/docs/versions/v8.2.0/technical-details/country-list.md b/docs/versions/v8.2.0/technical-details/country-list.md new file mode 100644 index 0000000000..d1338a19bd --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/country-list.md @@ -0,0 +1,243 @@ +# Country List + +This table lists country ids for the `avoid_country`-parameter. For details, +see [routing options](../api-reference/endpoints/directions/routing-options.md#options-avoid-countries). + +| country_id | name | name:en | +|:----------:|:--------------------------------------------------:|:---------------------------------------------:| +| 1 | افغانستان | Afghanistan | +| 2 | Shqipëria | Albania | +| 3 | Algeria | Algeria | +| 4 | Andorra | Andorra | +| 5 | Angola | Angola | +| 6 | Anguilla | Anguilla | +| 7 | Antigua and Barbuda | Antigua and Barbuda | +| 8 | Argentina | Argentina | +| 9 | Հայաստան | Armenia | +| 10 | Australia | Australia | +| 11 | Österreich | Austria | +| 12 | Azərbaycan | Azerbaijan | +| 13 | البحرين | Bahrain | +| 14 | বাংলাদেশ | Bangladesh | +| 15 | Barbados | Barbados | +| 16 | Беларусь | Belarus | +| 17 | België - Belgique - Belgien | Belgium | +| 18 | Belize | Belize | +| 19 | Bénin | Benin | +| 20 | Bermuda | Bermuda | +| 21 | འབྲུག་ཡུལ་ | Bhutan | +| 22 | Bolivia | Bolivia | +| 23 | Bosna i Hercegovina | Bosnia and Herzegovina | +| 24 | Botswana | Botswana | +| 25 | Brasil | Brazil | +| 26 | British Indian Ocean Territory | British Indian Ocean Territory | +| 27 | British Sovereign Base Areas | British Sovereign Base Areas | +| 28 | British Virgin Islands | British Virgin Islands | +| 29 | Brunei Darussalam | Brunei | +| 30 | България | Bulgaria | +| 31 | Burkina Faso | Burkina Faso | +| 32 | Burundi | Burundi | +| 33 | ព្រះរាជាណាចក្រកម្ពុជា | Cambodia | +| 34 | Cameroun | Cameroon | +| 35 | Canada | Canada | +| 36 | Cabo Verde | Cape Verde | +| 37 | Cayman Islands | Cayman Islands | +| 38 | Ködörösêse tî Bêafrîka - République Centrafricaine | Central African Republic | +| 39 | Tchad تشاد | Chad | +| 40 | Chile | Chile | +| 41 | 中国 | China | +| 42 | Colombia | Colombia | +| 43 | Komori | Comoros | +| 44 | République du Congo | Congo-Brazzaville | +| 45 | République démocratique du Congo | Congo-Kinshasa | +| 46 | Cook Islands | Cook Islands | +| 47 | Costa Rica | Costa Rica | +| 48 | Côte d’Ivoire | Côte d'Ivoire | +| 49 | Hrvatska | Croatia | +| 50 | Cuba | Cuba | +| 51 | Κύπρος - Kıbrıs | Cyprus | +| 52 | Česko | Czech Republic | +| 53 | Danmark | Denmark | +| 54 | Djibouti | Djibouti | +| 55 | Dominica | Dominica | +| 56 | República Dominicana | Dominican Republic | +| 57 | Timór Loro Sa'e | East Timor | +| 58 | Ecuador | Ecuador | +| 59 | Egypt مصر | Egypt | +| 60 | El Salvador | El Salvador | +| 61 | Guinea Ecuatorial | Equatorial Guinea | +| 62 | ኤርትራ | Eritrea | +| 63 | Eesti | Estonia | +| 64 | ኢትዮጵያ Ethiopia | Ethiopia | +| 65 | Falkland Islands | Falkland Islands | +| 66 | Føroyar | Faroe Islands | +| 67 | Federated States of Micronesia | Federated States of Micronesia | +| 68 | Viti | Fiji | +| 69 | Suomi | Finland | +| 70 | France | France | +| 71 | Gabon | Gabon | +| 72 | Gambia | Gambia | +| 73 | საქართველო | Georgia | +| 74 | Deutschland | Germany | +| 75 | Deutschland - Belgique / België / Belgien | Germany - Belgium | +| 76 | Ghana | Ghana | +| 77 | Gibraltar | Gibraltar | +| 78 | Ελλάδα | Greece | +| 79 | Kalaallit Nunaat | Greenland | +| 80 | Grenada | Grenada | +| 81 | Guatemala | Guatemala | +| 82 | Guernsey | Guernsey | +| 83 | Guinée | Guinea | +| 84 | Guiné-Bissau | Guinea-Bissau | +| 85 | Guyana | Guyana | +| 86 | Ayiti | Haiti | +| 87 | Honduras | Honduras | +| 88 | Magyarország | Hungary | +| 89 | Ísland | Iceland | +| 90 | India | India | +| 91 | Indonesia | Indonesia | +| 92 | ‏ایران‎ | Iran | +| 93 | العراق | Iraq | +| 94 | Ireland | Ireland | +| 95 | Isle of Man | Isle of Man | +| 96 | מדינת ישראל | Israel | +| 97 | Italia | Italy | +| 98 | Jamaica | Jamaica | +| 99 | Jangy-ayyl | Jangy-ayyl | +| 100 | 日本 | Japan | +| 101 | Jersey | Jersey | +| 102 | الأردن | Jordan | +| 103 | Қазақстан | Kazakhstan | +| 104 | Kenya | Kenya | +| 105 | Kiribati | Kiribati | +| 106 | Kosovë | Kosovo | +| 107 | ‏الكويت‎ | Kuwait | +| 108 | Кыргызстан | Kyrgyzstan | +| 109 | ປະເທດລາວ | Laos | +| 110 | Latvija | Latvia | +| 111 | لبنان | Lebanon | +| 112 | Lesotho | Lesotho | +| 113 | Liberia | Liberia | +| 114 | Libya ⵍⵉⴱⵢⴰ ليبيا | Libya | +| 115 | Liechtenstein | Liechtenstein | +| 116 | Lietuva | Lithuania | +| 117 | Lëtzebuerg | Luxembourg | +| 118 | Македонија | Macedonia | +| 119 | Madagasikara | Madagascar | +| 120 | Malawi | Malawi | +| 121 | Malaysia | Malaysia | +| 122 | ދިވެހިރާއްޖެ | Maldives | +| 123 | Mali | Mali | +| 124 | Malta | Malta | +| 125 | Aelōn̄ in M̧ajeļ | Marshall Islands | +| 126 | Mauritanie موريتانيا | Mauritania | +| 127 | Mauritius | Mauritius | +| 128 | México | Mexico | +| 129 | Moldova | Moldova | +| 130 | Monaco | Monaco | +| 131 | Монгол улс | Mongolia | +| 132 | Црна Гора / Crna Gora | Montenegro | +| 133 | Montserrat | Montserrat | +| 134 | Maroc ⵍⵎⵖⵔⵉⴱ المغرب | Morocco | +| 135 | Moçambique | Mozambique | +| 136 | မြန်မာ | Myanmar | +| 137 | name | name:en | +| 138 | Namibia | Namibia | +| 139 | Naoero | Nauru | +| 140 | नेपाल | Nepal | +| 141 | Nederland - Belgique / België / Belgien | Netherlands - Belgium | +| 142 | New Zealand/Aotearoa | New Zealand | +| 143 | Nicaragua | Nicaragua | +| 144 | Niger | Niger | +| 145 | Nigeria | Nigeria | +| 146 | Niuē | Niue | +| 147 | 조선민주주의인민공화국 | North Korea | +| 148 | Norge | Norway | +| 149 | عمان | Oman | +| 150 | ‏پاکستان‎ | Pakistan | +| 151 | Belau | Palau | +| 152 | الضفة الغربية وقطاع غزة | Palestinian Territories | +| 153 | Panamá | Panama | +| 154 | Papua Niugini | Papua New Guinea | +| 155 | Paraguay | Paraguay | +| 156 | Perú | Peru | +| 157 | Philippines | Philippines | +| 158 | Pitcairn Islands | Pitcairn Islands | +| 159 | Polska | Poland | +| 160 | Portugal | Portugal | +| 161 | ‏قطر‎ | Qatar | +| 162 | România | Romania | +| 163 | Российская Федерация | Russian Federation | +| 164 | Rwanda | Rwanda | +| 165 | Sahrawi Arab Democratic Republic | Sahrawi Arab Democratic Republic | +| 166 | Saint Helena - Ascension and Tristan da Cunha | Saint Helena - Ascension and Tristan da Cunha | +| 167 | Saint Kitts and Nevis | Saint Kitts and Nevis | +| 168 | Saint Lucia | Saint Lucia | +| 169 | Saint Vincent and the Grenadines | Saint Vincent and the Grenadines | +| 170 | Sāmoa | Samoa | +| 171 | San Marino | San Marino | +| 172 | São Tomé e Príncipe | São Tomé and Príncipe | +| 173 | ‏المملكة العربية السعودية‎ | Saudi Arabia | +| 174 | Sénégal | Senegal | +| 175 | Србија | Serbia | +| 176 | Sesel | Seychelles | +| 177 | Sierra Leone | Sierra Leone | +| 178 | Singapore | Singapore | +| 179 | Slovensko | Slovakia | +| 180 | Slovenija | Slovenia | +| 181 | Solomon Islands | Solomon Islands | +| 182 | Soomaaliya | Somalia | +| 183 | South Africa | South Africa | +| 184 | South Georgia and South Sandwich Islands | South Georgia and the South Sandwich Islands | +| 185 | 대한민국 | South Korea | +| 186 | South Sudan | South Sudan | +| 187 | España | Spain | +| 188 | ශ්‍රී ලංකාව இலங்கை | Sri Lanka | +| 189 | Sudan السودان | Sudan | +| 190 | Suriname | Suriname | +| 191 | Swaziland | Swaziland | +| 192 | Sverige | Sweden | +| 193 | Schweiz - Suisse - Svizzera - Svizra | Switzerland | +| 194 | سوريا | Syria | +| 195 | 臺灣 | Taiwan | +| 196 | Тоҷикистон | Tajikistan | +| 197 | Tanzania | Tanzania | +| 198 | ประเทศไทย | Thailand | +| 199 | The Bahamas | The Bahamas | +| 200 | Nederland | The Netherlands | +| 201 | Togo | Togo | +| 202 | Tokelau | Tokelau | +| 203 | Tonga | Tonga | +| 204 | Trinidad and Tobago | Trinidad and Tobago | +| 205 | Tunisie ⵜⵓⵏⵙ تونس | Tunisia | +| 206 | Türkiye | Turkey | +| 207 | Türkmenistan | Turkmenistan | +| 208 | Turks and Caicos Islands | Turks and Caicos Islands | +| 209 | Tuvalu | Tuvalu | +| 210 | Uganda | Uganda | +| 211 | Україна | Ukraine | +| 212 | الإمارات العربيّة المتّحدة | United Arab Emirates | +| 213 | United Kingdom | United Kingdom | +| 214 | United States of America | United States of America | +| 215 | Uruguay | Uruguay | +| 216 | Oʻzbekiston | Uzbekistan | +| 217 | Vanuatu | Vanuatu | +| 218 | Città del Vaticano | Vatican City | +| 219 | Venezuela | Venezuela | +| 220 | Việt Nam | Vietnam | +| 221 | اليمن | Yemen | +| 222 | Zambia | Zambia | +| 223 | Zimbabwe | Zimbabwe | +| 224 | Border India - Bangladesh | | +| 225 | Île Verte | | +| 226 | Border Azerbaijan - Armenia (Enclave AZE) | | +| 227 | Freezland Rock | | +| 228 | Border SI-HR | | +| 229 | Willis Island | | +| 230 | Chong-Kara | | +| 231 | Ελλάδα - Παγγαίο | | +| 232 | Bristol Island | | +| 233 | Dist. Judges Court | | +| 234 | Border Kyrgyzstan - Uzbekistan | | +| 235 | Border Malawi - Mozambique | | +| 236 | 中華民國 | | \ No newline at end of file diff --git a/docs/versions/v8.2.0/technical-details/index.md b/docs/versions/v8.2.0/technical-details/index.md new file mode 100644 index 0000000000..3e794fe889 --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/index.md @@ -0,0 +1,10 @@ +# Technical details + +[//]: # (Attention: Pages in Technical details are linked from api-playground. When refactoring, adapt the links in the annotations in the java classes) + +In this section you can find additional information on some important value lists +and explanation about the internal workings of the openrouteservice: + +* [Country List](country-list.md) +* [Travel Speeds](travel-speeds/index.md) +* [Tag Filtering](tag-filtering.md) diff --git a/docs/versions/v8.2.0/technical-details/tag-filtering.md b/docs/versions/v8.2.0/technical-details/tag-filtering.md new file mode 100644 index 0000000000..dae83e209a --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/tag-filtering.md @@ -0,0 +1,169 @@ +# Tag Filtering + +During the graph build process, openrouteservice looks at various tags that are given to OSM ways as a means of identifying whether that way should be included into the routing graph or not. For example, in the foot profile any ways that are marked as `highway=motorway` are rejected and not included in the graph, meaning that they can never be routed over (for that profile). + +The following tables list what tags are taken into account during the initial filtering process. +`Reject` means that the tag value indicates that the way is explicitly rejected from graph building. +`Accept` means that the tag indicates that the way should be included. +`Conditional` means that the tag is taken into account during the filtering process, +but the acceptance/rejection is based on other tags and logic, such as the [`:conditional` suffix](https://wiki.openstreetmap.org/wiki/Conditional_restrictions). + +Support of temporal restrictions is limited to seasonal access restrictions, such as `vehicle:conditional=no @ (Nov 1-Mar 31)`. These restrictions are being resolved at graph build time. +Other time-dependent conditional restrictions are currently not being taken into account. This means, in particular, that ways which are regularly open but conditionally closed, or vice versa, remain accepted or rejected, respectively. + +**The order of items is important, as in many cases a more generic "catch" is introduced towards the end of processing if it has not already been explicitly rejected/accepted.** + +Notation: +_italic words_ are variables defined for the respective section and group several tags. +`monospace code` are tags from OpenStreetMap. +`[square brackets]` denote a range of possible tags. +`*` denotes any tag, `key != *` denotes the absence of `key`. + + +## Driving car + +Definitions: +_restrictedValues_ = `[private, agricultural, forestry, no, restricted, delivery, military, emergency]` +_intendedValues_ = `[yes, permissive, destination]` +_restrictions_ = `[motorcar, motor_vehicle, vehicle, access]` +_firstValue_ = value of the first encountered key from _restrictions_ +_wayTypesWithDefaultSpeed_ = `[motorway, motorway_link, motorroad, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, unclassified, residential, living_street, service, road, track]` + +| Tag combination | Reject | Accept | Conditional | +|-------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| `highway != *` AND `route != [shuttle_train, ferry]` | :heavy_check_mark: | | | +| `highway != *` AND `route = [shuttle_train, ferry]` AND _firstValue_ = _restrictedValues_ | :heavy_check_mark: | | | +| `highway != *` AND `route = [shuttle_train, ferry]` AND ( _firstValue_ = _intendedValues_ OR _firstValue_ != `*` AND `foot != *` AND `bicycle != *` ) | | :heavy_check_mark: | | +| `highway = track` AND `tracktype > grade3` | :heavy_check_mark: | | | +| `highway !=` _wayTypesWithDefaultSpeed_ | :heavy_check_mark: | | | +| `impassable = yes` OR `[status, smoothness] = impassable` | :heavy_check_mark: | | | +| _firstValue_ = _restrictedValues_ | | | :heavy_check_mark: | +| _firstValue_ = _intendedValues_ | | :heavy_check_mark: | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| `maxwidth < 2` | :heavy_check_mark: | | | +| Default case: Accept **if not conditionally restricted** | | | :heavy_check_mark: | + +## Driving HGV + +The profile differs from the above logic for driving car in the definitions of + +Definitions: +_restrictedValues_ = `[private, no, restricted, military]` +_intendedValues_ = `[yes, permissive, designated, destination, hgv, goods, bus, agricultural, forestry, delivery]` +_restrictions_ = `[hgv, motorcar, motor_vehicle, vehicle, access]` + +and the following additional rule which replace the check for `ford`: + +| Tag combination | Reject | Accept | Conditional | +|--------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------:|:------------------:| +| !(_restrictions_=_intendedValues_) AND (`highway = ford` OR `ford = *`) | | | :heavy_check_mark: | +| !(_restrictions_=_intendedValues_) AND _restrictions_=_restrictedValues_ AND !(`[hgv, goods, bus, agricultural, forestry, delivery]`=_intendedValues_) | :heavy_check_mark: | | | +| Default case: Accept **if not conditionally restricted** | | | :heavy_check_mark: | + +## cycling-regular [cycling-electric, cycling-road & cycling-mountain] + +Definitions: +_restrictions_ = `[bicycle, vehicle, access]` +_restrictedValues_ = `[private, no, restricted, military, emergency]` +_intendedValues_ = `[yes, designated, official, permissive]` +_wayTypesWithDefaultSpeed_ = `[unclassified, tertiary_link, primary_link, bridleway, tertiary, living_street, trunk, motorway_link, steps, motorway, secondary, path, residential, road, service, footway, pedestrian, track, secondary_link, cycleway, trunk_link, primary, construction]` + +| Tag combination | Reject | Accept | Conditional | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| `highway != *` AND (`man_made = pier` OR `railway = platform` OR ( `route = [shuttle_train, ferry]` AND (`bicycle = yes` OR ( `bicycle != *` AND `foot != *`)))) AND !(_restrictions_ = _restrictedValues_) | | :heavy_check_mark: | | +| `highway !=` _wayTypesWithDefaultSpeed_ | :heavy_check_mark: | | | +| `sac_scale = hiking` AND `highway = cycleway` | | :heavy_check_mark: | | +| _cycling-regular, cycling-electric:_
`sac_scale != hiking`

_cycling-road:_
`sac_scale = *`

_cycling-mountain:_
`sac_scale != [hiking, mountain_hiking, demanding_mountain_hiking, alpine_hiking]`
| :heavy_check_mark: | | | +| `bicycle = `_intendedValues_ OR `bicycle = dismount` OR `highway = cycleway` OR `bicycle_road = yes` | | :heavy_check_mark: | | +| `highway = [motorway, motorway_link, bridleway, construction]` OR `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| _restrictions_ = _restrictedValues_ **if not conditionally permitted** | :heavy_check_mark: | | | +| Default case: Accept **if not conditionally restricted** | | | :heavy_check_mark: | + + +## Foot + +Definitions: +_restrictions_ = `[foot, access]` +_restrictedValues_ = `[private, no, restricted, military, emergency]` +_intendedValues_ = `[yes, designated, permissive, official]` + +| Tag combination | Reject | Accept | Conditional | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------:|:------------------:| +| `sac_scale != hiking` | :heavy_check_mark: | | | +| `foot = ` _intendedValues_ | | | :heavy_check_mark: | +| _restrictions_ = _restrictedValues_ | | | :heavy_check_mark: | +| `sidewalk = [yes, both, left, right]` | | | :heavy_check_mark: | +| `highway != [footway, path, steps, pedestrian, living_street, track, residential, service, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, cycleway, unclassified, road]` | :heavy_check_mark: | | | +| `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| Default case: Accept **if not conditionally restricted** | | | :heavy_check_mark: | + + +The following are applicable only when no highway tag has been provided for the way + +| Tag combination | Reject | Accept | Conditional | +|-------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| `route = [shuttle_train, ferry]` AND (`foot != *` OR `foot = yes`) | | :heavy_check_mark: | | +| `railway = platform` | | :heavy_check_mark: | | +| `man_made = pier` | | :heavy_check_mark: | | +| `waterway = lock_gate` AND `foot =` _intendedValues_ | | :heavy_check_mark: | | +| _restrictions_ = _restrictedValues_ Reject **if not conditionally permitted** | | | :heavy_check_mark: | +| Default case: | :heavy_check_mark: | | | + + +## Hiking + +Same as [Foot](#foot) except for different `sac_scale` check with existing `highway` tag. + +| Tag combination | Reject | Accept | Conditional | +|------------------------------------------------------------------------------------|:------------------:|:------:|:-----------:| +| `sac_scale != [hiking, mountain_hiking, demanding_mountain_hiking, alpine_hiking]` | :heavy_check_mark: | | | + + +## Wheelchair + +Definitions: +_restrictions_ = `[foot, wheelchair, access]` +_restrictedValues_ = `[private, no, restricted, military, emergency]` +_intendedValues_ = `[yes, limited, designated, permissive, official]` + +The following check is done first, regardless of the `highway` value: +| Tag combination | Reject | Accept | Conditional | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| _restrictions_ = _restrictedValues_ AND _restrictions_ != _intendedValues_ AND `sidewalk != [yes, both, left, right]` | :heavy_check_mark: | | | + +If `highway` is present on the way: + +| Tag combination | Reject | Accept | Conditional | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------:|:------------------:|:------------------:| +| `sac_scale = [mountain_hiking, demanding_mountain_hiking, alpine_hiking, demanding_alpine_hiking, difficult_alpine_hiking]` | :heavy_check_mark: | | | +| `surface = [ sand, salt, grass, snow, earth, dirt, ice, mud]` | :heavy_check_mark: | | | +| `smoothness = [bad, very_bad, horrible, very_horrible]` | :heavy_check_mark: | | | +| `tracktype = [grade4, grade5]` | :heavy_check_mark: | | | +| `wheelchair =` _intendedValues_ | | :heavy_check_mark: | | +| `wheelchair =` _restrictedValues_ | :heavy_check_mark: | | | +| `highway = [steps, construction]` | :heavy_check_mark: | | | +| `foot =` _intendedValues_ | | :heavy_check_mark: | | +| `foot =` _restrictedValues_ | :heavy_check_mark: | | | +| `sidewalk = [yes, both, left, right]` | | :heavy_check_mark: | | +| `sidewalk = [no, none, separate]` | :heavy_check_mark: | | | +| `motorroad = yes` | :heavy_check_mark: | | | +| `highway = ford` OR `ford = *` | | | :heavy_check_mark: | +| `highway = bridleway` AND `foot !=` _intendedValues_ AND `wheelchair !=` _intendedValues_ | :heavy_check_mark: | | | +| `highway = [footway, pedestrian, living_street, residential, unclassified, service, tertiary, tertiary_link, road, trunk, trunk_link, primary, primary_link, secondary, secondary_link, path, track, bridleway]` | | :heavy_check_mark: | | +| Default case: | | :heavy_check_mark: | | + +The following are applicable only when no `highway` tag has been provided for the way + +| Tag combination | Reject | Accept | Conditional | +|-----------------------------------------------------------------------------------------------|:------------------:|:------------------:|:-----------:| +| `route = [shuttle_train, ferry]` AND `wheelchair =` _intendedValues_ | | :heavy_check_mark: | | +| `route = [shuttle_train, ferry]` AND `wheelchair =` _restrictedValues_ | :heavy_check_mark: | | | +| `route = [shuttle_train, ferry]` AND `foot =` _intendedValues_ | | :heavy_check_mark: | | +| `route = [shuttle_train, ferry]` AND `foot =` _restrictedValues_ | :heavy_check_mark: | | | +| (`public_transport = platform` OR `railway = platform`) AND `wheelchair =` _intendedValues_ | | :heavy_check_mark: | | +| (`public_transport = platform` OR `railway = platform`) AND `wheelchair =` _restrictedValues_ | :heavy_check_mark: | | | +| (`public_transport = platform` OR `railway = platform`) AND `foot =` _intendedValues_ | | :heavy_check_mark: | | +| (`public_transport = platform` OR `railway = platform`) AND `foot =` _restrictedValues_ | :heavy_check_mark: | | | +| Default case: | :heavy_check_mark: | | | diff --git a/docs/versions/v8.2.0/technical-details/travel-speeds/country-speeds.md b/docs/versions/v8.2.0/technical-details/travel-speeds/country-speeds.md new file mode 100644 index 0000000000..68820a24b1 --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/travel-speeds/country-speeds.md @@ -0,0 +1,94 @@ +# Country-specific Speeds +As there are various traffic regulations in different countries, if no [maximum +speed](http://wiki.openstreetmap.org/wiki/Key:maxspeed) tag is given in +OpenStreetMap, we adjust the maximum speed according to the following key +values taken from [country specific speed +limits](http://wiki.openstreetmap.org/wiki/Speed_limits). +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Country | Tags | driving-car | driving-hgv | + |:--------------:|:--------------------:|:-----------:|:-----------:| + | Austria | AT:urban | 50 | 50 | + | | AT:rural | 100 | 80 | + | | AT:trunk | 100 | 80 | + | | AT:motorway | 130 | 80 | + | Switzerland | CH:urban | 50 | 50 | + | | CH:rural | 80 | 80 | + | | CH:trunk | 100 | 80 | + | | CH:motorway | 120 | 80 | + | Czech Republic | CZ:urban | 50 | 50 | + | | CZ:rural | 90 | 90 | + | | CZ:trunk | 80 | 80 | + | | CZ:motorway | 80 | 80 | + | Denmark | DK:urban | 50 | 50 | + | | DK:rural | 80 | 80 | + | | DK:motorway | 130 | 80 | + | Germany | DE:living_street | 7 | 7 | + | | DE:urban | 50 | 50 | + | | DE:rural | 100 | 80 | + | | DE:motorway | 130 | 80 | + | Finland | FI:urban | 50 | 50 | + | | FI:rural | 80 | 80 | + | | FI:trunk | 100 | 80 | + | | FI:motorway | 120 | 80 | + | France | FR:urban | 50 | 50 | + | | FR:rural | 80 | 80 | + | | FR:trunk | 110 | 80 | + | | FR:motorway | 130 | 80 | + | Greece | GR:urban | 50 | 50 | + | | GR:rural | 90 | 80 | + | | GR:trunk | 110 | 80 | + | | GR:motorway | 130 | 80 | + | Hungary | HU:urban | 50 | 50 | + | | HU:rural | 90 | 80 | + | | HU:trunk | 110 | 80 | + | | HU:motorway | 130 | 80 | + | Italy | IT:urban | 50 | 50 | + | | IT:rural | 90 | 80 | + | | IT:trunk | 110 | 80 | + | | IT:motorway | 130 | 80 | + | Japan | JP:national | 60 | 60 | + | | JP:motorway | 100 | 80 | + | Poland | PL:living_street | 20 | 20 | + | | PL:urban | 50 | 50 | + | | PL:rural | 90 | 80 | + | | PL:motorway | 140 | 80 | + | Romania | RO:urban | 50 | 50 | + | | RO:rural | 90 | 80 | + | | RO:trunk | 100 | 80 | + | | RO:motorway | 130 | 80 | + | Russia | RU:living_street | 20 | 20 | + | | RU:rural | 90 | 80 | + | | RU:urban | 60 | 60 | + | | RU:motorway | 110 | 80 | + | Slovakia | SK:urban | 50 | 50 | + | | SK:rural | 90 | 80 | + | | SK:trunk | 90 | 80 | + | | SK:motorway | 90 | 80 | + | Slovenia | SI:urban | 50 | 50 | + | | SI:rural | 90 | 80 | + | | SI:trunk | 110 | 80 | + | | SI:motorway | 130 | 80 | + | Spain | ES:urban | 50 | 50 | + | | ES:rural | 90 | 80 | + | | ES:trunk | 100 | 80 | + | | ES:motorway | 120 | 80 | + | Sweden | SE:urban | 50 | 50 | + | | SE:rural | 70 | 70 | + | | SE:trunk | 90 | 80 | + | | SE:motorway | 110 | 80 | + | United Kingdom | GB:nsl_single | 95 | 90 | + | | GB:nsl_dual | 112 | 90 | + | | GB:motorway | 112 | 90 | + | Ukraine | UA:urban | 60 | 60 | + | | UA:rural | 90 | 80 | + | | UA:trunk | 110 | 80 | + | | UA:motorway | 130 | 80 | + | Uzbekistan | UZ:living_street | 30 | 30 | + | | UZ:urban | 70 | 70 | + | | UZ:rural | 100 | 90 | + | | UZ:motorway | 110 | 90 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v8.2.0/technical-details/travel-speeds/index.md b/docs/versions/v8.2.0/technical-details/travel-speeds/index.md new file mode 100644 index 0000000000..e0c31bf66d --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/travel-speeds/index.md @@ -0,0 +1,100 @@ +# Travel Speeds +A main component that determines things such as fastest routes and the travel +time for isochrones and route instructions is travel speed. This value is +determined differently depending on the profile and can be affected by a number +of aspects. + +## Travel Time Calculation + +The travel time is calculated for each segment by using speed-limits for +different [waytypes](https://wiki.openstreetmap.org/wiki/Key:highway) and +adjusting them for different +[surfaces](https://wiki.openstreetmap.org/wiki/Key:surface) or [surface +qualities](https://wiki.openstreetmap.org/wiki/Key:tracktype) of the road. If +multiple values apply at any point, the lowest value is used. + +The speed limits can be reduced by setting the `maximum_speed` parameter in a [directions request][api_docs]. +The final [average speed](../../api-reference/endpoints/directions/route-attributes.md) can be requested by adding `avgspeed` to the `attributes` parameter. + +### Driving profiles (car and HGV) +The base travel speed for any road is based on a cascading assessment: +1. When a tag explicitly stating the speed limit for a road is present on the + way in OSM (`maxspeed` or `maxspeed:forward / maxspeed:backward`), this is + used as the base speed. +2. If the way has a `zone:maxspeed` or `zone:traffic` tag, this is compared to + country-specific values in the `max_speeds` array of the + [speed value files][svf]. + An overview can be found in the [country speed table](country-speeds). + This value is then used as the base speed. +3. If neither of the above set a base speed, then the type of way (`highway=` + tag) determines the base speed. Values are defined in the + [speed value files][svf]. + The [waytype speed table](waytype-speeds) gives an overview. +4. If it is a track (`highway=track`) then the base speed is set based on the + `tracktype` tag compared to values in the [speed value files][svf]. + The [tracktype speed table](tracktype-speeds) gives an overview. + +If the determined base speed is one resulting from a `maxspeed`-tag or from a +[country speed table](country-speeds) (i.e. Steps 1 or 2), it is reduced to 90% +of its original value, since it is more common that you would be travelling +below the maximum speed value. The [waytype](waytype-speeds) and +[tracktype](tracktype-speeds) defaults have already been chosen rather +conservatively, so they are not adjusted. + +Following that, it is further modified based on a number of other factors: +* If a surface is defined (`surface=*`) then the surface value is set to be the + corresponding surface type value defined in the [speed value files][svf]. + An overview can be found in the [surface speed table](surface-speeds). +* Attempt to take into account reduced speeds in residential areas using + acceleration modifier or a residential penalty +* cap speed if it is entering a roundabout (based on number of lanes and + roundabout type - mini roundabout = 25km/h, 1 lane = 35km/h, 2 or more lanes += 40km/h) + +### Bike profiles +Bike profiles determine their speeds based on a number of defaults set in the +code based on surface, highway type, and track type. _Though there is currently +a speed_limits file present in the resources for bike profiles, these values +are not used in the calculation_ + +The speeds used can be found in the [CommonBikeFlagEncoder][cbfe] for the +default values and regular bike profile, [MountainBikeFlagEncoder][mbfe] for +the mountain bike profile, [RoadBikeFlagEncoder][rbfe] for the road bike, and +[ElectroBikeFlagEncoder][ebfe] for the electric bike. + +Note that each bike profile has a different value set for the maximum +downhill speed which is calculated when `consider_elevation=true` is set in the +ors-config.json. Currently, this option is turned off for openrouteservice live +servers as it can lead to undesirable routes. + +### Walking profiles +The travel speeds for `foot-*` profiles (walking and hiking) are set to +5 km/h on all allowed waytypes. +For ways with a [`sac_scale`](../../api-reference/endpoints/directions/extra-info/trail-difficulty.md) higher than +`hiking`, they are reduced to 2 km/h. + +Allowed waytypes consist of ways that are safe for use, ways that are better +avoided (but still allowed) and other allowed ways in between: + + | safe tags | avoid tags | other highway tags | + |:----------------------:|:----------------:|:-------------------:| + | footway | trunk | cycleway | + | path | trunk_link | unclassified | + | steps | primary | road | + | pedestrian | primary_link | | + | living_street | secondary | | + | track | secondary_link | | + | residential | tertiary | | + | service | tertiary_link | | + +### Wheelchair profile +The wheelchair profile has a base speed of 4km/h which is then modified based +on a number of parameters. As such, based on the presence of sidewalks and type +of way, the actual speed can range from 3 to 10km/h + +[svf]: https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/services/routing/speed_limits +[cbfe]: https://github.com/GIScience/openrouteservice/blob/main/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/CommonBikeFlagEncoder.java#L186 +[mbfe]: https://github.com/GIScience/openrouteservice/blob/main/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/MountainBikeFlagEncoder.java#L52 +[rbfe]: https://github.com/GIScience/openrouteservice/blob/main/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/RoadBikeFlagEncoder.java#L85 +[ebfe]: https://github.com/GIScience/openrouteservice/blob/main/ors-engine/src/main/java/org/heigit/ors/routing/graphhopper/extensions/flagencoders/bike/ElectroBikeFlagEncoder.java#L41 +[api_docs]: https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post diff --git a/docs/versions/v8.2.0/technical-details/travel-speeds/surface-speeds.md b/docs/versions/v8.2.0/technical-details/travel-speeds/surface-speeds.md new file mode 100644 index 0000000000..a825130481 --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/travel-speeds/surface-speeds.md @@ -0,0 +1,39 @@ +# Surface Speeds +The surfaces correspond to the OSM [surface](https://wiki.openstreetmap.org/wiki/Key:surface) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Surface \ Profile -> | driving-car | driving-hgv | cycling-regular | + |:--------------------:|:-----------:|:-----------:|:---------------:| + | asphalt | -1 | -1 | 18 | + | concrete | -1 | -1 | 18 | + | concrete:plates | -1 | -1 | 16 | + | concrete:lanes | -1 | -1 | 16 | + | paved | -1 | -1 | 18 | + | cement | 80 | 60 | -1 | + | compacted | 80 | 60 | 18 | + | fine_gravel | 60 | 50 | 16 | + | paving_stones | 40 | 40 | 12 | + | metal | 40 | 40 | 10 | + | bricks | 40 | 40 | -1 | + | grass | 30 | 30 | 8 | + | wood | 30 | 30 | 6 | + | sett | 30 | 30 | 10 | + | grass_paver | 30 | 30 | 8 | + | gravel | 30 | 30 | 12 | + | unpaved | 30 | 30 | 14 | + | ground | 30 | 30 | 12 | + | dirt | 30 | 30 | 10 | + | pebblestone | 30 | 30 | 16 | + | tartan | 30 | 30 | -1 | + | cobblestone | 20 | 20 | 8 | + | clay | 20 | 20 | -1 | + | earth | 15 | 15 | 12 | + | stone | 15 | 15 | -1 | + | rocky | 15 | 15 | -1 | + | sand | 15 | 15 | 6 | + | mud | 10 | 10 | 10 | + | unknown: | 30 | 30 | -1 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v8.2.0/technical-details/travel-speeds/tracktype-speeds.md b/docs/versions/v8.2.0/technical-details/travel-speeds/tracktype-speeds.md new file mode 100644 index 0000000000..28eba38200 --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/travel-speeds/tracktype-speeds.md @@ -0,0 +1,15 @@ +# Tracktype Speeds +The tracktypes corresponds to the OSM [tracktype](https://wiki.openstreetmap.org/wiki/Key:tracktype) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Tracktype \ Profile -> | driving-car | driving-hgv | cycling-regular| + |:----------------------:|:-----------:|:-----------:|:--------------:| + | grade1 | 40 | 40 | 18 | + | grade2 | 30 | 30 | 12 | + | grade3 | 20 | 20 | 8 | + | grade4 | 15 | 15 | 6 | + | grade5 | 10 | 10 | 4 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/docs/versions/v8.2.0/technical-details/travel-speeds/waytype-speeds.md b/docs/versions/v8.2.0/technical-details/travel-speeds/waytype-speeds.md new file mode 100644 index 0000000000..6cfa53351e --- /dev/null +++ b/docs/versions/v8.2.0/technical-details/travel-speeds/waytype-speeds.md @@ -0,0 +1,34 @@ +# Waytype Speeds +The waytypes correspond to the OSM [highway](https://wiki.openstreetmap.org/wiki/Key:highway) tag value. +This table aggregates the values in the [speed value files][svf]. + +_(all Values in km/h)_ + + | Waytype \ Profile -> | driving-car | driving-hgv | cycling-regular | + |:--------------------:|:-----------:|:-----------:|:---------------:| + | motorway | 100 | 85 | 18 | + | motorway_link | 60 | 50 | 18 | + | motorroad | 90 | 80 | - | + | trunk | 85 | 60 | 18 | + | trunk_link | 60 | 50 | 18 | + | primary | 65 | 60 | 18 | + | primary_link | 50 | 50 | 18 | + | secondary | 60 | 60 | 18 | + | secondary_link | 50 | 50 | 18 | + | tertiary | 50 | 50 | 18 | + | tertiary_link | 40 | 40 | 18 | + | unclassified | 30 | 30 | 16 | + | residential | 30 | 30 | 18 | + | living_street | 10 | 10 | 6 | + | service | 20 | 20 | 14 | + | road | 20 | 20 | 12 | + | track | 15 | 15 | 12 | + | path | - | - | 10 | + | cycleway | - | - | 18 | + | footway | - | - | 6 | + | pedestrian | - | - | 6 | + | bridleway | - | - | 6 | + | steps | - | - | 2 | + | construction | - | - | 10 | + +[svf]: https://github.com/GIScience/openrouteservice/tree/main/ors-engine/src/main/resources/resources/services/routing/speed_limits diff --git a/package-lock.json b/package-lock.json index 432e63d427..e79c1593f7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4,9 +4,12 @@ "requires": true, "packages": { "": { + "dependencies": { + "vitepress-versioning-plugin": "git+https://github.com/GIScience/vitepress-versioning-plugin.git#fix-sidebar-rewrites" + }, "devDependencies": { "mermaid": "^11.3.0", - "vitepress": "^1.0.0-rc.30", + "vitepress": "^1.5.0", "vitepress-plugin-mermaid": "^2.0.17" } }, @@ -14,7 +17,6 @@ "version": "1.9.3", "resolved": "https://registry.npmjs.org/@algolia/autocomplete-core/-/autocomplete-core-1.9.3.tgz", "integrity": "sha512-009HdfugtGCdC4JdXUbVJClA0q0zh24yyePn+KUGk3rP7j8FEe/m5Yo/z65gn6nP/cM39PxpzqKrL7A6fP6PPw==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/autocomplete-plugin-algolia-insights": "1.9.3", @@ -25,7 +27,6 @@ "version": "1.9.3", "resolved": "https://registry.npmjs.org/@algolia/autocomplete-plugin-algolia-insights/-/autocomplete-plugin-algolia-insights-1.9.3.tgz", "integrity": "sha512-a/yTUkcO/Vyy+JffmAnTWbr4/90cLzw+CC3bRbhnULr/EM0fGNvM13oQQ14f2moLMcVDyAx/leczLlAOovhSZg==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/autocomplete-shared": "1.9.3" @@ -38,7 +39,6 @@ "version": "1.9.3", "resolved": "https://registry.npmjs.org/@algolia/autocomplete-preset-algolia/-/autocomplete-preset-algolia-1.9.3.tgz", "integrity": "sha512-d4qlt6YmrLMYy95n5TB52wtNDr6EgAIPH81dvvvW8UmuWRgxEtY0NJiPwl/h95JtG2vmRM804M0DSwMCNZlzRA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/autocomplete-shared": "1.9.3" @@ -52,7 +52,6 @@ "version": "1.9.3", "resolved": "https://registry.npmjs.org/@algolia/autocomplete-shared/-/autocomplete-shared-1.9.3.tgz", "integrity": "sha512-Wnm9E4Ye6Rl6sTTqjoymD+l8DjSTHsHboVRYrKgEt8Q7UHm9nYbqhN/i0fhUYA3OAEH7WA8x3jfpnmJm3rKvaQ==", - "dev": true, "license": "MIT", "peerDependencies": { "@algolia/client-search": ">= 4.9.1 < 6", @@ -63,7 +62,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/cache-browser-local-storage/-/cache-browser-local-storage-4.24.0.tgz", "integrity": "sha512-t63W9BnoXVrGy9iYHBgObNXqYXM3tYXCjDSHeNwnsc324r4o5UiVKUiAB4THQ5z9U5hTj6qUvwg/Ez43ZD85ww==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/cache-common": "4.24.0" @@ -73,14 +71,12 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/cache-common/-/cache-common-4.24.0.tgz", "integrity": "sha512-emi+v+DmVLpMGhp0V9q9h5CdkURsNmFC+cOS6uK9ndeJm9J4TiqSvPYVu+THUP8P/S08rxf5x2P+p3CfID0Y4g==", - "dev": true, "license": "MIT" }, "node_modules/@algolia/cache-in-memory": { "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/cache-in-memory/-/cache-in-memory-4.24.0.tgz", "integrity": "sha512-gDrt2so19jW26jY3/MkFg5mEypFIPbPoXsQGQWAi6TrCPsNOSEYepBMPlucqWigsmEy/prp5ug2jy/N3PVG/8w==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/cache-common": "4.24.0" @@ -90,7 +86,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-account/-/client-account-4.24.0.tgz", "integrity": "sha512-adcvyJ3KjPZFDybxlqnf+5KgxJtBjwTPTeyG2aOyoJvx0Y8dUQAEOEVOJ/GBxX0WWNbmaSrhDURMhc+QeevDsA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -102,7 +97,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-4.24.0.tgz", "integrity": "sha512-bc2ROsNL6w6rqpl5jj/UywlIYC21TwSSoFHKl01lYirGMW+9Eek6r02Tocg4gZ8HAw3iBvu6XQiM3BEbmEMoiA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0", @@ -113,7 +107,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-4.24.0.tgz", "integrity": "sha512-uRW6EpNapmLAD0mW47OXqTP8eiIx5F6qN9/x/7HHO6owL3N1IXqydGwW5nhDFBrV+ldouro2W1VX3XlcUXEFCA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -125,7 +118,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-analytics/-/client-analytics-4.24.0.tgz", "integrity": "sha512-y8jOZt1OjwWU4N2qr8G4AxXAzaa8DBvyHTWlHzX/7Me1LX8OayfgHexqrsL4vSBcoMmVw2XnVW9MhL+Y2ZDJXg==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -138,7 +130,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-4.24.0.tgz", "integrity": "sha512-bc2ROsNL6w6rqpl5jj/UywlIYC21TwSSoFHKl01lYirGMW+9Eek6r02Tocg4gZ8HAw3iBvu6XQiM3BEbmEMoiA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0", @@ -149,7 +140,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-4.24.0.tgz", "integrity": "sha512-uRW6EpNapmLAD0mW47OXqTP8eiIx5F6qN9/x/7HHO6owL3N1IXqydGwW5nhDFBrV+ldouro2W1VX3XlcUXEFCA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -161,7 +151,6 @@ "version": "5.10.2", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-5.10.2.tgz", "integrity": "sha512-eE4OaTlb5KZdCehWmDARq2KEmMF7DEeFLjKqFDcZNb56k1DMSsa9zCQRXZMovlf2AXLsx0A/1q+SGAEgzF7G3w==", - "dev": true, "license": "MIT", "peer": true, "engines": { @@ -172,7 +161,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-personalization/-/client-personalization-4.24.0.tgz", "integrity": "sha512-l5FRFm/yngztweU0HdUzz1rC4yoWCFo3IF+dVIVTfEPg906eZg5BOd1k0K6rZx5JzyyoP4LdmOikfkfGsKVE9w==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -184,7 +172,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-4.24.0.tgz", "integrity": "sha512-bc2ROsNL6w6rqpl5jj/UywlIYC21TwSSoFHKl01lYirGMW+9Eek6r02Tocg4gZ8HAw3iBvu6XQiM3BEbmEMoiA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0", @@ -195,7 +182,6 @@ "version": "5.10.2", "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.10.2.tgz", "integrity": "sha512-rGX8uil2uvPycFgtS9Fzwvh4tgKvfFWG5RIh3E77W42HrO66bykCf9jHqhIIlCxdDJih1PuUqBYZIkIAAoSkww==", - "dev": true, "license": "MIT", "peer": true, "dependencies": { @@ -212,14 +198,12 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/logger-common/-/logger-common-4.24.0.tgz", "integrity": "sha512-LLUNjkahj9KtKYrQhFKCzMx0BY3RnNP4FEtO+sBybCjJ73E8jNdaKJ/Dd8A/VA4imVHP5tADZ8pn5B8Ga/wTMA==", - "dev": true, "license": "MIT" }, "node_modules/@algolia/logger-console": { "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/logger-console/-/logger-console-4.24.0.tgz", "integrity": "sha512-X4C8IoHgHfiUROfoRCV+lzSy+LHMgkoEEU1BbKcsfnV0i0S20zyy0NLww9dwVHUWNfPPxdMU+/wKmLGYf96yTg==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/logger-common": "4.24.0" @@ -229,7 +213,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/recommend/-/recommend-4.24.0.tgz", "integrity": "sha512-P9kcgerfVBpfYHDfVZDvvdJv0lEoCvzNlOy2nykyt5bK8TyieYyiD0lguIJdRZZYGre03WIAFf14pgE+V+IBlw==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/cache-browser-local-storage": "4.24.0", @@ -249,7 +232,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-4.24.0.tgz", "integrity": "sha512-bc2ROsNL6w6rqpl5jj/UywlIYC21TwSSoFHKl01lYirGMW+9Eek6r02Tocg4gZ8HAw3iBvu6XQiM3BEbmEMoiA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0", @@ -260,7 +242,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-4.24.0.tgz", "integrity": "sha512-uRW6EpNapmLAD0mW47OXqTP8eiIx5F6qN9/x/7HHO6owL3N1IXqydGwW5nhDFBrV+ldouro2W1VX3XlcUXEFCA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -272,7 +253,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/requester-browser-xhr/-/requester-browser-xhr-4.24.0.tgz", "integrity": "sha512-Z2NxZMb6+nVXSjF13YpjYTdvV3032YTBSGm2vnYvYPA6mMxzM3v5rsCiSspndn9rzIW4Qp1lPHBvuoKJV6jnAA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0" @@ -282,7 +262,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/requester-node-http/-/requester-node-http-4.24.0.tgz", "integrity": "sha512-JF18yTjNOVYvU/L3UosRcvbPMGT9B+/GQWNWnenIImglzNVGpyzChkXLnrSf6uxwVNO6ESGu6oN8MqcGQcjQJw==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0" @@ -292,7 +271,6 @@ "version": "5.10.2", "resolved": "https://registry.npmjs.org/@algolia/requester-browser-xhr/-/requester-browser-xhr-5.10.2.tgz", "integrity": "sha512-gzlfE/H05ggDiEWNi8WaDSRhpE5X8rD1JqYKPPeM31JRI3TutQIKAk3MSUsa1bHM/Di56r2Gm6L1g3ZlZv2ETA==", - "dev": true, "license": "MIT", "peer": true, "dependencies": { @@ -306,14 +284,12 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/requester-common/-/requester-common-4.24.0.tgz", "integrity": "sha512-k3CXJ2OVnvgE3HMwcojpvY6d9kgKMPRxs/kVohrwF5WMr2fnqojnycZkxPoEg+bXm8fi5BBfFmOqgYztRtHsQA==", - "dev": true, "license": "MIT" }, "node_modules/@algolia/requester-fetch": { "version": "5.10.2", "resolved": "https://registry.npmjs.org/@algolia/requester-fetch/-/requester-fetch-5.10.2.tgz", "integrity": "sha512-Q27ciW9WRdq3pUITVlxpHIwe9QWOe+oPvgs8Z+gsv8vMkwXnLfANvSgeZCyQgx3SqzUPzhel0ozVq7Qoh8xIkg==", - "dev": true, "license": "MIT", "peer": true, "dependencies": { @@ -327,7 +303,6 @@ "version": "5.10.2", "resolved": "https://registry.npmjs.org/@algolia/requester-node-http/-/requester-node-http-5.10.2.tgz", "integrity": "sha512-WMUQ4iFhNnQXC4F1Yj51x8tgIvq5h8jtTLMBs7LbMiW6JhnLHfBVl7IVk6X1fZJO5YcvXW051HN8aFlfAb5QEw==", - "dev": true, "license": "MIT", "peer": true, "dependencies": { @@ -341,7 +316,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/transporter/-/transporter-4.24.0.tgz", "integrity": "sha512-86nI7w6NzWxd1Zp9q3413dRshDqAzSbsQjhcDhPIatEFiZrL1/TjnHL8S7jVKFePlIMzDsZWXAXwXzcok9c5oA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/cache-common": "4.24.0", @@ -377,7 +351,6 @@ "version": "7.25.9", "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.25.9.tgz", "integrity": "sha512-4A/SCr/2KLd5jrtOMFzaKjVtAei3+2r/NChoBNoZ3EyP/+GlhoaEGoWOZUmFmoITP7zOJyHIMm+DYRd8o3PvHA==", - "dev": true, "license": "MIT", "engines": { "node": ">=6.9.0" @@ -387,7 +360,6 @@ "version": "7.25.9", "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.25.9.tgz", "integrity": "sha512-Ed61U6XJc3CVRfkERJWDz4dJwKe7iLmmJsbOGu9wSloNSFttHV0I8g6UAgb7qnK5ly5bGLPd4oXZlxCdANBOWQ==", - "dev": true, "license": "MIT", "engines": { "node": ">=6.9.0" @@ -397,7 +369,6 @@ "version": "7.25.9", "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.25.9.tgz", "integrity": "sha512-aI3jjAAO1fh7vY/pBGsn1i9LDbRP43+asrRlkPuTXW5yHXtd1NgTEMudbBoDDxrf1daEEfPJqR+JBMakzrR4Dg==", - "dev": true, "license": "MIT", "dependencies": { "@babel/types": "^7.25.9" @@ -413,7 +384,6 @@ "version": "7.25.9", "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.25.9.tgz", "integrity": "sha512-OwS2CM5KocvQ/k7dFJa8i5bNGJP0hXWfVCfDkqRFP1IreH1JDC7wG6eCYCi0+McbfT8OR/kNqsI0UU0xP9H6PQ==", - "dev": true, "license": "MIT", "dependencies": { "@babel/helper-string-parser": "^7.25.9", @@ -478,14 +448,12 @@ "version": "3.6.2", "resolved": "https://registry.npmjs.org/@docsearch/css/-/css-3.6.2.tgz", "integrity": "sha512-vKNZepO2j7MrYBTZIGXvlUOIR+v9KRf70FApRgovWrj3GTs1EITz/Xb0AOlm1xsQBp16clVZj1SY/qaOJbQtZw==", - "dev": true, "license": "MIT" }, "node_modules/@docsearch/js": { "version": "3.6.2", "resolved": "https://registry.npmjs.org/@docsearch/js/-/js-3.6.2.tgz", "integrity": "sha512-pS4YZF+VzUogYrkblCucQ0Oy2m8Wggk8Kk7lECmZM60hTbaydSIhJTTiCrmoxtBqV8wxORnOqcqqOfbmkkQEcA==", - "dev": true, "license": "MIT", "dependencies": { "@docsearch/react": "3.6.2", @@ -496,7 +464,6 @@ "version": "3.6.2", "resolved": "https://registry.npmjs.org/@docsearch/react/-/react-3.6.2.tgz", "integrity": "sha512-rtZce46OOkVflCQH71IdbXSFK+S8iJZlUF56XBW5rIgx/eG5qoomC7Ag3anZson1bBac/JFQn7XOBfved/IMRA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/autocomplete-core": "1.9.3", @@ -532,7 +499,6 @@ "cpu": [ "x64" ], - "dev": true, "license": "MIT", "optional": true, "os": [ @@ -542,6 +508,15 @@ "node": ">=12" } }, + "node_modules/@iconify-json/simple-icons": { + "version": "1.2.13", + "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.13.tgz", + "integrity": "sha512-rRQjMoIt/kPfaD+fnBC9YZQpso3hkn8xPeadl+YWhscJ5SVUCdB9oTeR9VIpt+/5Yi8vEkh2UOWFPq4lz3ee2A==", + "dev": true, + "dependencies": { + "@iconify/types": "*" + } + }, "node_modules/@iconify/types": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/@iconify/types/-/types-2.0.0.tgz", @@ -569,7 +544,6 @@ "version": "1.5.0", "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.0.tgz", "integrity": "sha512-gv3ZRaISU3fjPAgNsriBRqGWQL6quFx04YMPW/zD8XMLsU32mhCCbfbO6KZFLjvYpCZ8zyDEgqsgf+PwPaM7GQ==", - "dev": true, "license": "MIT" }, "node_modules/@mermaid-js/mermaid-mindmap": { @@ -614,7 +588,6 @@ "cpu": [ "x64" ], - "dev": true, "license": "MIT", "optional": true, "os": [ @@ -628,7 +601,6 @@ "cpu": [ "x64" ], - "dev": true, "license": "MIT", "optional": true, "os": [ @@ -636,59 +608,49 @@ ] }, "node_modules/@shikijs/core": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.22.1.tgz", - "integrity": "sha512-bqAhT/Ri5ixV4oYsvJNH8UJjpjbINWlWyXY6tBTsP4OmD6XnFv43nRJ+lTdxd2rmG5pgam/x+zGR6kLRXrpEKA==", - "dev": true, - "license": "MIT", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.24.0.tgz", + "integrity": "sha512-6pvdH0KoahMzr6689yh0QJ3rCgF4j1XsXRHNEeEN6M4xJTfQ6QPWrmHzIddotg+xPJUPEPzYzYCKzpYyhTI6Gw==", "dependencies": { - "@shikijs/engine-javascript": "1.22.1", - "@shikijs/engine-oniguruma": "1.22.1", - "@shikijs/types": "1.22.1", + "@shikijs/engine-javascript": "1.24.0", + "@shikijs/engine-oniguruma": "1.24.0", + "@shikijs/types": "1.24.0", "@shikijs/vscode-textmate": "^9.3.0", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.3" } }, "node_modules/@shikijs/engine-javascript": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-1.22.1.tgz", - "integrity": "sha512-540pyoy0LWe4jj2BVbgELwOFu1uFvRI7lg4hdsExrSXA9x7gqfzZ/Nnh4RfX86aDAgJ647gx4TCmRwACbnQSvw==", - "dev": true, - "license": "MIT", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-1.24.0.tgz", + "integrity": "sha512-ZA6sCeSsF3Mnlxxr+4wGEJ9Tto4RHmfIS7ox8KIAbH0MTVUkw3roHPHZN+LlJMOHJJOVupe6tvuAzRpN8qK1vA==", "dependencies": { - "@shikijs/types": "1.22.1", + "@shikijs/types": "1.24.0", "@shikijs/vscode-textmate": "^9.3.0", - "oniguruma-to-js": "0.4.3" + "oniguruma-to-es": "0.7.0" } }, "node_modules/@shikijs/engine-oniguruma": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-1.22.1.tgz", - "integrity": "sha512-L+1Vmd+a2kk8HtogUFymQS6BjUfJnzcWoUp1BUgxoDiklbKSMvrsMuLZGevTOP1m0rEjgnC5MsDmsr8lX1lC+Q==", - "dev": true, - "license": "MIT", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-1.24.0.tgz", + "integrity": "sha512-Eua0qNOL73Y82lGA4GF5P+G2+VXX9XnuUxkiUuwcxQPH4wom+tE39kZpBFXfUuwNYxHSkrSxpB1p4kyRW0moSg==", "dependencies": { - "@shikijs/types": "1.22.1", + "@shikijs/types": "1.24.0", "@shikijs/vscode-textmate": "^9.3.0" } }, "node_modules/@shikijs/transformers": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-1.22.1.tgz", - "integrity": "sha512-KvG49YFV6gV116sC4L3Sn1Rp6HXsioMKBBG373j088rw849440hm8s2r+/dgjsGLvT4p+QB7newev+5a3ARM6w==", - "dev": true, - "license": "MIT", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-1.24.0.tgz", + "integrity": "sha512-Qf/hby+PRPkoHncjYnJf5svK1aCsOUtQhuLzKPnmeXJtuUZCmbH0pTpdNtXe9tgln/RHlyRJnv7q46HHS1sO0Q==", "dependencies": { - "shiki": "1.22.1" + "shiki": "1.24.0" } }, "node_modules/@shikijs/types": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-1.22.1.tgz", - "integrity": "sha512-+45f8mu/Hxqs6Kyhfm98Nld5n7Q7lwhjU8UtdQwrOPs7BnM4VAb929O3IQ2ce+4D7SlNFlZGd8CnKRSnwbQreQ==", - "dev": true, - "license": "MIT", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-1.24.0.tgz", + "integrity": "sha512-aptbEuq1Pk88DMlCe+FzXNnBZ17LCiLIGWAeCWhoFDzia5Q5Krx3DgnULLiouSdd6+LUM39XwXGppqYE0Ghtug==", "dependencies": { "@shikijs/vscode-textmate": "^9.3.0", "@types/hast": "^3.0.4" @@ -698,7 +660,6 @@ "version": "9.3.0", "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-9.3.0.tgz", "integrity": "sha512-jn7/7ky30idSkd/O5yDBfAnVt+JJpepofP/POZ1iMOxK59cOfqIgg/Dj0eFsjOTMw+4ycJN0uhZH/Eb0bs/EUA==", - "dev": true, "license": "MIT" }, "node_modules/@types/d3": { @@ -999,7 +960,6 @@ "version": "1.0.6", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.6.tgz", "integrity": "sha512-AYnb1nQyY49te+VRAVgmzfcgjYS91mY5P0TKUDCLEM+gNnA+3T6rWITXRLYCpahpqSQbN5cE+gHpnPyXjHWxcw==", - "dev": true, "license": "MIT" }, "node_modules/@types/geojson": { @@ -1013,7 +973,6 @@ "version": "3.0.4", "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "*" @@ -1023,14 +982,17 @@ "version": "5.0.0", "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-5.0.0.tgz", "integrity": "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==", - "dev": true, "license": "MIT" }, + "node_modules/@types/lodash": { + "version": "4.17.13", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.17.13.tgz", + "integrity": "sha512-lfx+dftrEZcdBPczf9d0Qv0x+j/rfNCMuC6OcfXmO8gkfeNAY88PgKUbvG56whcN23gc27yenwF6oJZXGFpYxg==" + }, "node_modules/@types/markdown-it": { "version": "14.1.2", "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-14.1.2.tgz", "integrity": "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==", - "dev": true, "license": "MIT", "dependencies": { "@types/linkify-it": "^5", @@ -1041,7 +1003,6 @@ "version": "4.0.4", "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "*" @@ -1051,7 +1012,6 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-2.0.0.tgz", "integrity": "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==", - "dev": true, "license": "MIT" }, "node_modules/@types/trusted-types": { @@ -1065,28 +1025,24 @@ "version": "3.0.3", "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", - "dev": true, "license": "MIT" }, "node_modules/@types/web-bluetooth": { "version": "0.0.20", "resolved": "https://registry.npmjs.org/@types/web-bluetooth/-/web-bluetooth-0.0.20.tgz", "integrity": "sha512-g9gZnnXVq7gM7v3tJCWV/qw7w+KeOlSHAhgF9RytFyifW6AF61hdT2ucrYhPq9hLs5JIryeupHV3qGk95dH9ow==", - "dev": true, "license": "MIT" }, "node_modules/@ungap/structured-clone": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.2.0.tgz", "integrity": "sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==", - "dev": true, "license": "ISC" }, "node_modules/@vitejs/plugin-vue": { "version": "5.1.4", "resolved": "https://registry.npmjs.org/@vitejs/plugin-vue/-/plugin-vue-5.1.4.tgz", "integrity": "sha512-N2XSI2n3sQqp5w7Y/AN/L2XDjBIRGqXko+eDp42sydYSBeJuSm5a1sLf8zakmo8u7tA8NmBgoDLA1HeOESjp9A==", - "dev": true, "license": "MIT", "engines": { "node": "^18.0.0 || >=20.0.0" @@ -1100,7 +1056,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.5.12.tgz", "integrity": "sha512-ISyBTRMmMYagUxhcpyEH0hpXRd/KqDU4ymofPgl2XAkY9ZhQ+h0ovEZJIiPop13UmR/54oA2cgMDjgroRelaEw==", - "dev": true, "license": "MIT", "dependencies": { "@babel/parser": "^7.25.3", @@ -1114,7 +1069,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/compiler-dom/-/compiler-dom-3.5.12.tgz", "integrity": "sha512-9G6PbJ03uwxLHKQ3P42cMTi85lDRvGLB2rSGOiQqtXELat6uI4n8cNz9yjfVHRPIu+MsK6TE418Giruvgptckg==", - "dev": true, "license": "MIT", "dependencies": { "@vue/compiler-core": "3.5.12", @@ -1125,7 +1079,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/compiler-sfc/-/compiler-sfc-3.5.12.tgz", "integrity": "sha512-2k973OGo2JuAa5+ZlekuQJtitI5CgLMOwgl94BzMCsKZCX/xiqzJYzapl4opFogKHqwJk34vfsaKpfEhd1k5nw==", - "dev": true, "license": "MIT", "dependencies": { "@babel/parser": "^7.25.3", @@ -1143,7 +1096,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/compiler-ssr/-/compiler-ssr-3.5.12.tgz", "integrity": "sha512-eLwc7v6bfGBSM7wZOGPmRavSWzNFF6+PdRhE+VFJhNCgHiF8AM7ccoqcv5kBXA2eWUfigD7byekvf/JsOfKvPA==", - "dev": true, "license": "MIT", "dependencies": { "@vue/compiler-dom": "3.5.12", @@ -1154,7 +1106,6 @@ "version": "7.5.4", "resolved": "https://registry.npmjs.org/@vue/devtools-api/-/devtools-api-7.5.4.tgz", "integrity": "sha512-j9UC/KeYUNZ6AyCJxBROBCbogB5YHW6PZv9VnCNp2ntE4rq426Lfc8WP5B9V+rXBwqWmrgZTGYBa31CBSxdAUg==", - "dev": true, "license": "MIT", "dependencies": { "@vue/devtools-kit": "^7.5.4" @@ -1164,7 +1115,6 @@ "version": "7.5.4", "resolved": "https://registry.npmjs.org/@vue/devtools-kit/-/devtools-kit-7.5.4.tgz", "integrity": "sha512-0i7WFgc1B2TL52tstn82zlb9opSA0aIiHfkUYFXtZb8CIpmlFMTkHtgwVl6PMWNBj3LNhYou1YJCLpCYvJYYoA==", - "dev": true, "license": "MIT", "dependencies": { "@vue/devtools-shared": "^7.5.4", @@ -1180,7 +1130,6 @@ "version": "7.5.4", "resolved": "https://registry.npmjs.org/@vue/devtools-shared/-/devtools-shared-7.5.4.tgz", "integrity": "sha512-dwuq4YmwTyLc7eBOqX63s3JB8il7qnKsNgENglSMkUPwiItHkVAYYfPESN1rxSdYkl1RCux1l5TBidYqfUDNAA==", - "dev": true, "license": "MIT", "dependencies": { "rfdc": "^1.4.1" @@ -1190,7 +1139,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/reactivity/-/reactivity-3.5.12.tgz", "integrity": "sha512-UzaN3Da7xnJXdz4Okb/BGbAaomRHc3RdoWqTzlvd9+WBR5m3J39J1fGcHes7U3za0ruYn/iYy/a1euhMEHvTAg==", - "dev": true, "license": "MIT", "dependencies": { "@vue/shared": "3.5.12" @@ -1200,7 +1148,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/runtime-core/-/runtime-core-3.5.12.tgz", "integrity": "sha512-hrMUYV6tpocr3TL3Ad8DqxOdpDe4zuQY4HPY3X/VRh+L2myQO8MFXPAMarIOSGNu0bFAjh1yBkMPXZBqCk62Uw==", - "dev": true, "license": "MIT", "dependencies": { "@vue/reactivity": "3.5.12", @@ -1211,7 +1158,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/runtime-dom/-/runtime-dom-3.5.12.tgz", "integrity": "sha512-q8VFxR9A2MRfBr6/55Q3umyoN7ya836FzRXajPB6/Vvuv0zOPL+qltd9rIMzG/DbRLAIlREmnLsplEF/kotXKA==", - "dev": true, "license": "MIT", "dependencies": { "@vue/reactivity": "3.5.12", @@ -1224,7 +1170,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/server-renderer/-/server-renderer-3.5.12.tgz", "integrity": "sha512-I3QoeDDeEPZm8yR28JtY+rk880Oqmj43hreIBVTicisFTx/Dl7JpG72g/X7YF8hnQD3IFhkky5i2bPonwrTVPg==", - "dev": true, "license": "MIT", "dependencies": { "@vue/compiler-ssr": "3.5.12", @@ -1238,7 +1183,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/@vue/shared/-/shared-3.5.12.tgz", "integrity": "sha512-L2RPSAwUFbgZH20etwrXyVyCBu9OxRSi8T/38QsvnkJyvq2LufW2lDCOzm7t/U9C1mkhJGWYfCuFBCmIuNivrg==", - "dev": true, "license": "MIT" }, "node_modules/@vueuse/core": { @@ -1445,7 +1389,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-4.24.0.tgz", "integrity": "sha512-bf0QV/9jVejssFBmz2HQLxUadxk574t4iwjCKp5E7NBzwKkrDEhKPISIIjAU/p6K5qDx3qoeh4+26zWN1jmw3g==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/cache-browser-local-storage": "4.24.0", @@ -1469,7 +1412,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-4.24.0.tgz", "integrity": "sha512-bc2ROsNL6w6rqpl5jj/UywlIYC21TwSSoFHKl01lYirGMW+9Eek6r02Tocg4gZ8HAw3iBvu6XQiM3BEbmEMoiA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0", @@ -1480,7 +1422,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-4.24.0.tgz", "integrity": "sha512-uRW6EpNapmLAD0mW47OXqTP8eiIx5F6qN9/x/7HHO6owL3N1IXqydGwW5nhDFBrV+ldouro2W1VX3XlcUXEFCA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/client-common": "4.24.0", @@ -1492,7 +1433,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/requester-browser-xhr/-/requester-browser-xhr-4.24.0.tgz", "integrity": "sha512-Z2NxZMb6+nVXSjF13YpjYTdvV3032YTBSGm2vnYvYPA6mMxzM3v5rsCiSspndn9rzIW4Qp1lPHBvuoKJV6jnAA==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0" @@ -1502,7 +1442,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/@algolia/requester-node-http/-/requester-node-http-4.24.0.tgz", "integrity": "sha512-JF18yTjNOVYvU/L3UosRcvbPMGT9B+/GQWNWnenIImglzNVGpyzChkXLnrSf6uxwVNO6ESGu6oN8MqcGQcjQJw==", - "dev": true, "license": "MIT", "dependencies": { "@algolia/requester-common": "4.24.0" @@ -1512,7 +1451,6 @@ "version": "0.2.19", "resolved": "https://registry.npmjs.org/birpc/-/birpc-0.2.19.tgz", "integrity": "sha512-5WeXXAvTmitV1RqJFppT5QtUiz2p1mRSYU000Jkft5ZUCLJIk4uQriYNO50HknxKwM6jd8utNc66K1qGIwwWBQ==", - "dev": true, "license": "MIT", "funding": { "url": "https://github.com/sponsors/antfu" @@ -1522,7 +1460,6 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -1533,7 +1470,6 @@ "version": "2.1.0", "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -1544,7 +1480,6 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -1579,11 +1514,25 @@ "chevrotain": "^11.0.0" } }, + "node_modules/cli-color": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/cli-color/-/cli-color-2.0.4.tgz", + "integrity": "sha512-zlnpg0jNcibNrO7GG9IeHH7maWFeCz+Ja1wx/7tZNU5ASSSSZ+/qZciM0/LHCYxSdqv5h2sdbQ/PXYdOuetXvA==", + "dependencies": { + "d": "^1.0.1", + "es5-ext": "^0.10.64", + "es6-iterator": "^2.0.3", + "memoizee": "^0.4.15", + "timers-ext": "^0.1.7" + }, + "engines": { + "node": ">=0.10" + } + }, "node_modules/comma-separated-tokens": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -1611,7 +1560,6 @@ "version": "3.0.5", "resolved": "https://registry.npmjs.org/copy-anything/-/copy-anything-3.0.5.tgz", "integrity": "sha512-yCEafptTtb4bk7GLEQoM8KVJpxAfdBJYaXyzQEgQQQgYrZiDp8SJmGKlYza6CYjEDNstAdNdKA3UuoULlEbS6w==", - "dev": true, "license": "MIT", "dependencies": { "is-what": "^4.1.8" @@ -1637,7 +1585,6 @@ "version": "3.1.3", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz", "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==", - "dev": true, "license": "MIT" }, "node_modules/cytoscape": { @@ -1693,6 +1640,18 @@ "dev": true, "license": "MIT" }, + "node_modules/d": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/d/-/d-1.0.2.tgz", + "integrity": "sha512-MOqHvMWF9/9MX6nza0KgvFH4HpMU0EF5uUDXqX/BtxtU8NfB0QzRtJ8Oe/6SuS4kbhyzVJwjd97EA4PKrzJ8bw==", + "dependencies": { + "es5-ext": "^0.10.64", + "type": "^2.7.2" + }, + "engines": { + "node": ">=0.12" + } + }, "node_modules/d3": { "version": "7.9.0", "resolved": "https://registry.npmjs.org/d3/-/d3-7.9.0.tgz", @@ -2220,7 +2179,6 @@ "version": "2.0.3", "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", - "dev": true, "license": "MIT", "engines": { "node": ">=6" @@ -2230,7 +2188,6 @@ "version": "1.1.0", "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", - "dev": true, "license": "MIT", "dependencies": { "dequal": "^2.0.0" @@ -2247,11 +2204,15 @@ "dev": true, "license": "(MPL-2.0 OR Apache-2.0)" }, + "node_modules/emoji-regex-xs": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex-xs/-/emoji-regex-xs-1.0.0.tgz", + "integrity": "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==" + }, "node_modules/entities": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", - "dev": true, "license": "BSD-2-Clause", "engines": { "node": ">=0.12" @@ -2260,11 +2221,58 @@ "url": "https://github.com/fb55/entities?sponsor=1" } }, + "node_modules/es5-ext": { + "version": "0.10.64", + "resolved": "https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.64.tgz", + "integrity": "sha512-p2snDhiLaXe6dahss1LddxqEm+SkuDvV8dnIQG0MWjyHpcMNfXKPE+/Cc0y+PhxJX3A4xGNeFCj5oc0BUh6deg==", + "hasInstallScript": true, + "dependencies": { + "es6-iterator": "^2.0.3", + "es6-symbol": "^3.1.3", + "esniff": "^2.0.1", + "next-tick": "^1.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/es6-iterator": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/es6-iterator/-/es6-iterator-2.0.3.tgz", + "integrity": "sha512-zw4SRzoUkd+cl+ZoE15A9o1oQd920Bb0iOJMQkQhl3jNc03YqVjAhG7scf9C5KWRU/R13Orf588uCC6525o02g==", + "dependencies": { + "d": "1", + "es5-ext": "^0.10.35", + "es6-symbol": "^3.1.1" + } + }, + "node_modules/es6-symbol": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/es6-symbol/-/es6-symbol-3.1.4.tgz", + "integrity": "sha512-U9bFFjX8tFiATgtkJ1zg25+KviIXpgRvRHS8sau3GfhVzThRQrOeksPeT0BWW2MNZs1OEWJ1DPXOQMn0KKRkvg==", + "dependencies": { + "d": "^1.0.2", + "ext": "^1.7.0" + }, + "engines": { + "node": ">=0.12" + } + }, + "node_modules/es6-weak-map": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/es6-weak-map/-/es6-weak-map-2.0.3.tgz", + "integrity": "sha512-p5um32HOTO1kP+w7PRnB+5lQ43Z6muuMuIMffvDN8ZB4GcnjLBV6zGStpbASIMk4DCAvEaamhe2zhyCb/QXXsA==", + "dependencies": { + "d": "1", + "es5-ext": "^0.10.46", + "es6-iterator": "^2.0.3", + "es6-symbol": "^3.1.1" + } + }, "node_modules/esbuild": { "version": "0.21.5", "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", - "dev": true, "hasInstallScript": true, "license": "MIT", "bin": { @@ -2299,18 +2307,47 @@ "@esbuild/win32-x64": "0.21.5" } }, + "node_modules/esniff": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/esniff/-/esniff-2.0.1.tgz", + "integrity": "sha512-kTUIGKQ/mDPFoJ0oVfcmyJn4iBDRptjNVIzwIFR7tqWXdVI9xfA2RMwY/gbSpJG3lkdWNEjLap/NqVHZiJsdfg==", + "dependencies": { + "d": "^1.0.1", + "es5-ext": "^0.10.62", + "event-emitter": "^0.3.5", + "type": "^2.7.2" + }, + "engines": { + "node": ">=0.10" + } + }, "node_modules/estree-walker": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz", "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==", - "dev": true, "license": "MIT" }, + "node_modules/event-emitter": { + "version": "0.3.5", + "resolved": "https://registry.npmjs.org/event-emitter/-/event-emitter-0.3.5.tgz", + "integrity": "sha512-D9rRn9y7kLPnJ+hMq7S/nhvoKwwvVJahBi2BPmx3bvbsEdK3W9ii8cBSGjP+72/LnM4n6fo3+dkCX5FeTQruXA==", + "dependencies": { + "d": "1", + "es5-ext": "~0.10.14" + } + }, + "node_modules/ext": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz", + "integrity": "sha512-6hxeJYaL110a9b5TEJSj0gojyHQAmA2ch5Os+ySCiA1QGdS697XWY1pzsrSjqA9LDEEgdB/KypIlR59RcLuHYw==", + "dependencies": { + "type": "^2.7.2" + } + }, "node_modules/focus-trap": { "version": "7.6.0", "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.0.tgz", "integrity": "sha512-1td0l3pMkWJLFipobUcGaf+5DTY4PLDDrcqoSaKP8ediO/CoWCCYk/fT/Y2A4e6TNB+Sh6clRJCjOPPnKoNHnQ==", - "dev": true, "license": "MIT", "dependencies": { "tabbable": "^6.2.0" @@ -2327,7 +2364,6 @@ "version": "9.0.3", "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.3.tgz", "integrity": "sha512-M17uBDzMJ9RPCqLMO92gNNUDuBSq10a25SDBI08iCCxmorf4Yy6sYHK57n9WAbRAAaU+DuR4W6GN9K4DFZesYg==", - "dev": true, "license": "MIT", "dependencies": { "@types/hast": "^3.0.0", @@ -2351,7 +2387,6 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", - "dev": true, "license": "MIT", "dependencies": { "@types/hast": "^3.0.0" @@ -2365,14 +2400,12 @@ "version": "5.5.3", "resolved": "https://registry.npmjs.org/hookable/-/hookable-5.5.3.tgz", "integrity": "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==", - "dev": true, "license": "MIT" }, "node_modules/html-void-elements": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -2402,11 +2435,15 @@ "node": ">=12" } }, + "node_modules/is-promise": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-2.2.2.tgz", + "integrity": "sha512-+lP4/6lKUBfQjZ2pdxThZvLUAafmZb8OAxFb8XXtiQmS35INgr85hdOGoEs124ez1FCnZJt6jau/T+alh58QFQ==" + }, "node_modules/is-what": { "version": "4.1.16", "resolved": "https://registry.npmjs.org/is-what/-/is-what-4.1.16.tgz", "integrity": "sha512-ZhMwEosbFJkA0YhFnNDgTM4ZxDRsS6HqTo7qsZM08fehyRYIYa0yHu5R6mgo1n/8MgaPBXiPimPD77baVFYg+A==", - "dev": true, "license": "MIT", "engines": { "node": ">=12.13" @@ -2415,6 +2452,17 @@ "url": "https://github.com/sponsors/mesqueeb" } }, + "node_modules/json5": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", + "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", + "bin": { + "json5": "lib/cli.js" + }, + "engines": { + "node": ">=6" + } + }, "node_modules/katex": { "version": "0.16.11", "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.11.tgz", @@ -2496,6 +2544,11 @@ "url": "https://github.com/sponsors/antfu" } }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" + }, "node_modules/lodash-es": { "version": "4.17.21", "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", @@ -2503,11 +2556,18 @@ "dev": true, "license": "MIT" }, + "node_modules/lru-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/lru-queue/-/lru-queue-0.1.0.tgz", + "integrity": "sha512-BpdYkt9EvGl8OfWHDQPISVpcl5xZthb+XPsbELj5AQXxIC8IriDZIQYjBJPEm5rS420sjZ0TLEzRcq5KdBhYrQ==", + "dependencies": { + "es5-ext": "~0.10.2" + } + }, "node_modules/magic-string": { "version": "0.30.12", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.12.tgz", "integrity": "sha512-Ea8I3sQMVXr8JhN4z+H/d8zwo+tYDgHE9+5G4Wnrwhs0gaK9fXTKx0Tw5Xwsd/bCPTTZNRAdpyzvoeORe9LYpw==", - "dev": true, "license": "MIT", "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0" @@ -2516,8 +2576,7 @@ "node_modules/mark.js": { "version": "8.11.1", "resolved": "https://registry.npmjs.org/mark.js/-/mark.js-8.11.1.tgz", - "integrity": "sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==", - "dev": true + "integrity": "sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==" }, "node_modules/marked": { "version": "13.0.3", @@ -2536,7 +2595,6 @@ "version": "13.2.0", "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz", "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", - "dev": true, "license": "MIT", "dependencies": { "@types/hast": "^3.0.0", @@ -2554,6 +2612,24 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/memoizee": { + "version": "0.4.17", + "resolved": "https://registry.npmjs.org/memoizee/-/memoizee-0.4.17.tgz", + "integrity": "sha512-DGqD7Hjpi/1or4F/aYAspXKNm5Yili0QDAFAY4QYvpqpgiY6+1jOfqpmByzjxbWd/T9mChbCArXAbDAsTm5oXA==", + "dependencies": { + "d": "^1.0.2", + "es5-ext": "^0.10.64", + "es6-weak-map": "^2.0.3", + "event-emitter": "^0.3.5", + "is-promise": "^2.2.2", + "lru-queue": "^0.1.0", + "next-tick": "^1.1.0", + "timers-ext": "^0.1.7" + }, + "engines": { + "node": ">=0.12" + } + }, "node_modules/mermaid": { "version": "11.4.0", "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.4.0.tgz", @@ -2588,7 +2664,6 @@ "version": "2.1.0", "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.0.tgz", "integrity": "sha512-KvOVV+X1yLBfs9dCBSopq/+G1PcgT3lAK07mC4BzXi5E7ahzMAF8oIupDDJ6mievI6F+lAATkbQQlQixJfT3aQ==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2609,7 +2684,6 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.0.tgz", "integrity": "sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2626,7 +2700,6 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.0.tgz", "integrity": "sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2648,7 +2721,6 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.0.tgz", "integrity": "sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2665,7 +2737,6 @@ "version": "2.0.0", "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.0.tgz", "integrity": "sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w==", - "dev": true, "funding": [ { "type": "GitHub Sponsors", @@ -2682,14 +2753,12 @@ "version": "7.1.0", "resolved": "https://registry.npmjs.org/minisearch/-/minisearch-7.1.0.tgz", "integrity": "sha512-tv7c/uefWdEhcu6hvrfTihflgeEi2tN6VV7HJnCjK6VxM75QQJh4t9FwJCsA2EsRS8LCnu3W87CuGPWMocOLCA==", - "dev": true, "license": "MIT" }, "node_modules/mitt": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz", "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==", - "dev": true, "license": "MIT" }, "node_modules/mlly": { @@ -2716,7 +2785,6 @@ "version": "3.3.7", "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.7.tgz", "integrity": "sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==", - "dev": true, "funding": [ { "type": "github", @@ -2731,6 +2799,11 @@ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" } }, + "node_modules/next-tick": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/next-tick/-/next-tick-1.1.0.tgz", + "integrity": "sha512-CXdUiJembsNjuToQvxayPZF9Vqht7hewsvy2sOWafLvi2awflj9mOC6bHIg50orX8IJvWKY9wYQ/zB2kogPslQ==" + }, "node_modules/non-layered-tidy-tree-layout": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/non-layered-tidy-tree-layout/-/non-layered-tidy-tree-layout-2.0.2.tgz", @@ -2739,17 +2812,14 @@ "license": "MIT", "optional": true }, - "node_modules/oniguruma-to-js": { - "version": "0.4.3", - "resolved": "https://registry.npmjs.org/oniguruma-to-js/-/oniguruma-to-js-0.4.3.tgz", - "integrity": "sha512-X0jWUcAlxORhOqqBREgPMgnshB7ZGYszBNspP+tS9hPD3l13CdaXcHbgImoHUHlrvGx/7AvFEkTRhAGYh+jzjQ==", - "dev": true, - "license": "MIT", + "node_modules/oniguruma-to-es": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-0.7.0.tgz", + "integrity": "sha512-HRaRh09cE0gRS3+wi2zxekB+I5L8C/gN60S+vb11eADHUaB/q4u8wGGOX3GvwvitG8ixaeycZfeoyruKQzUgNg==", "dependencies": { - "regex": "^4.3.2" - }, - "funding": { - "url": "https://github.com/sponsors/antfu" + "emoji-regex-xs": "^1.0.0", + "regex": "^5.0.2", + "regex-recursion": "^4.3.0" } }, "node_modules/package-manager-detector": { @@ -2777,14 +2847,12 @@ "version": "1.0.0", "resolved": "https://registry.npmjs.org/perfect-debounce/-/perfect-debounce-1.0.0.tgz", "integrity": "sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA==", - "dev": true, "license": "MIT" }, "node_modules/picocolors": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", - "dev": true, "license": "ISC" }, "node_modules/pkg-types": { @@ -2821,7 +2889,6 @@ "version": "8.4.47", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.47.tgz", "integrity": "sha512-56rxCq7G/XfB4EkXq9Egn5GCqugWvDFjafDOThIdMBsI15iqPqR5r15TfSr1YPYeEI19YeaXMCbY6u88Y76GLQ==", - "dev": true, "funding": [ { "type": "opencollective", @@ -2850,7 +2917,6 @@ "version": "10.24.3", "resolved": "https://registry.npmjs.org/preact/-/preact-10.24.3.tgz", "integrity": "sha512-Z2dPnBnMUfyQfSQ+GBdsGa16hz35YmLmtTLhM169uW944hYL6xzTYkJjC07j+Wosz733pMWx0fgON3JNw1jJQA==", - "dev": true, "license": "MIT", "funding": { "type": "opencollective", @@ -2861,7 +2927,6 @@ "version": "6.5.0", "resolved": "https://registry.npmjs.org/property-information/-/property-information-6.5.0.tgz", "integrity": "sha512-PgTgs/BlvHxOu8QuEN7wi5A0OmXaBcHpmCSTehcs6Uuu9IkDIEo13Hy7n898RHfrQ49vKCoGeWZSaAK01nwVig==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -2869,17 +2934,30 @@ } }, "node_modules/regex": { - "version": "4.3.3", - "resolved": "https://registry.npmjs.org/regex/-/regex-4.3.3.tgz", - "integrity": "sha512-r/AadFO7owAq1QJVeZ/nq9jNS1vyZt+6t1p/E59B56Rn2GCya+gr1KSyOzNL/er+r+B7phv5jG2xU2Nz1YkmJg==", - "dev": true, - "license": "MIT" + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/regex/-/regex-5.0.2.tgz", + "integrity": "sha512-/pczGbKIQgfTMRV0XjABvc5RzLqQmwqxLHdQao2RTXPk+pmTXB2P0IaUHYdYyk412YLwUIkaeMd5T+RzVgTqnQ==", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-4.3.0.tgz", + "integrity": "sha512-5LcLnizwjcQ2ALfOj95MjcatxyqF5RPySx9yT+PaXu3Gox2vyAtLDjHB8NTJLtMGkvyau6nI3CfpwFCjPUIs/A==", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==" }, "node_modules/rfdc": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz", "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==", - "dev": true, "license": "MIT" }, "node_modules/robust-predicates": { @@ -2893,7 +2971,6 @@ "version": "4.24.0", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.24.0.tgz", "integrity": "sha512-DOmrlGSXNk1DM0ljiQA+i+o0rSLhtii1je5wgk60j49d1jHT5YYttBv1iWOnYSTG+fZZESUOSNiAl89SIet+Cg==", - "dev": true, "license": "MIT", "dependencies": { "@types/estree": "1.0.6" @@ -2956,21 +3033,18 @@ "version": "2.17.2", "resolved": "https://registry.npmjs.org/search-insights/-/search-insights-2.17.2.tgz", "integrity": "sha512-zFNpOpUO+tY2D85KrxJ+aqwnIfdEGi06UH2+xEb+Bp9Mwznmauqc9djbnBibJO5mpfUPPa8st6Sx65+vbeO45g==", - "dev": true, "license": "MIT", "peer": true }, "node_modules/shiki": { - "version": "1.22.1", - "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.22.1.tgz", - "integrity": "sha512-PbJ6XxrWLMwB2rm3qdjIHNm3zq4SfFnOx0B3rEoi4AN8AUngsdyZ1tRe5slMPtn6jQkbUURLNZPpLR7Do3k78g==", - "dev": true, - "license": "MIT", - "dependencies": { - "@shikijs/core": "1.22.1", - "@shikijs/engine-javascript": "1.22.1", - "@shikijs/engine-oniguruma": "1.22.1", - "@shikijs/types": "1.22.1", + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.24.0.tgz", + "integrity": "sha512-qIneep7QRwxRd5oiHb8jaRzH15V/S8F3saCXOdjwRLgozZJr5x2yeBhQtqkO3FSzQDwYEFAYuifg4oHjpDghrg==", + "dependencies": { + "@shikijs/core": "1.24.0", + "@shikijs/engine-javascript": "1.24.0", + "@shikijs/engine-oniguruma": "1.24.0", + "@shikijs/types": "1.24.0", "@shikijs/vscode-textmate": "^9.3.0", "@types/hast": "^3.0.4" } @@ -2979,7 +3053,6 @@ "version": "1.2.1", "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", - "dev": true, "license": "BSD-3-Clause", "engines": { "node": ">=0.10.0" @@ -2989,7 +3062,6 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -3000,7 +3072,6 @@ "version": "14.0.1", "resolved": "https://registry.npmjs.org/speakingurl/-/speakingurl-14.0.1.tgz", "integrity": "sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==", - "dev": true, "license": "BSD-3-Clause", "engines": { "node": ">=0.10.0" @@ -3010,7 +3081,6 @@ "version": "4.0.4", "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", - "dev": true, "license": "MIT", "dependencies": { "character-entities-html4": "^2.0.0", @@ -3032,7 +3102,6 @@ "version": "2.2.1", "resolved": "https://registry.npmjs.org/superjson/-/superjson-2.2.1.tgz", "integrity": "sha512-8iGv75BYOa0xRJHK5vRLEjE2H/i4lulTjzpUXic3Eg8akftYjkmQDa8JARQ42rlczXyFR3IeRoeFCc7RxHsYZA==", - "dev": true, "license": "MIT", "dependencies": { "copy-anything": "^3.0.2" @@ -3045,9 +3114,20 @@ "version": "6.2.0", "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", "integrity": "sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==", - "dev": true, "license": "MIT" }, + "node_modules/timers-ext": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/timers-ext/-/timers-ext-0.1.8.tgz", + "integrity": "sha512-wFH7+SEAcKfJpfLPkrgMPvvwnEtj8W4IurvEyrKsDleXnKLCDw71w8jltvfLa8Rm4qQxxT4jmDBYbJG/z7qoww==", + "dependencies": { + "es5-ext": "^0.10.64", + "next-tick": "^1.1.0" + }, + "engines": { + "node": ">=0.12" + } + }, "node_modules/tinyexec": { "version": "0.3.1", "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.1.tgz", @@ -3059,7 +3139,6 @@ "version": "3.0.1", "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", - "dev": true, "license": "MIT", "funding": { "type": "github", @@ -3076,6 +3155,11 @@ "node": ">=6.10" } }, + "node_modules/type": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/type/-/type-2.7.3.tgz", + "integrity": "sha512-8j+1QmAbPvLZow5Qpi6NCaN8FB60p/6x8/vfNqOk/hC+HuvFZhL4+WfekuhQLiqFZXOgQdrs3B+XxEmCc6b3FQ==" + }, "node_modules/ufo": { "version": "1.5.4", "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.5.4.tgz", @@ -3087,7 +3171,6 @@ "version": "6.0.0", "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz", "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0" @@ -3101,7 +3184,6 @@ "version": "5.0.0", "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0" @@ -3115,7 +3197,6 @@ "version": "4.0.0", "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0" @@ -3129,7 +3210,6 @@ "version": "5.0.0", "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz", "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0", @@ -3145,7 +3225,6 @@ "version": "6.0.1", "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.1.tgz", "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0", @@ -3174,7 +3253,6 @@ "version": "6.0.3", "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0", @@ -3189,7 +3267,6 @@ "version": "4.0.2", "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz", "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==", - "dev": true, "license": "MIT", "dependencies": { "@types/unist": "^3.0.0", @@ -3204,7 +3281,6 @@ "version": "5.4.10", "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.10.tgz", "integrity": "sha512-1hvaPshuPUtxeQ0hsVH3Mud0ZanOLwVTneA1EgbAM5LhaZEqyPWGRQ7BtaMvUrTDeEaC8pxtj6a6jku3x4z6SQ==", - "dev": true, "license": "MIT", "dependencies": { "esbuild": "^0.21.3", @@ -3261,28 +3337,28 @@ } }, "node_modules/vitepress": { - "version": "1.4.1", - "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.4.1.tgz", - "integrity": "sha512-C2rQ7PMlDVqgsaHOa0uJtgGGWaGv74QMaGL62lxKbtFkYtosJB5HAfZ8+pEbfzzvLemYaYwaiQdFLBlexK2sFw==", + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.5.0.tgz", + "integrity": "sha512-q4Q/G2zjvynvizdB3/bupdYkCJe2umSAMv9Ju4d92E6/NXJ59z70xB0q5p/4lpRyAwflDsbwy1mLV9Q5+nlB+g==", "dev": true, - "license": "MIT", "dependencies": { "@docsearch/css": "^3.6.2", "@docsearch/js": "^3.6.2", - "@shikijs/core": "^1.22.0", - "@shikijs/transformers": "^1.22.0", - "@shikijs/types": "^1.22.0", + "@iconify-json/simple-icons": "^1.2.10", + "@shikijs/core": "^1.22.2", + "@shikijs/transformers": "^1.22.2", + "@shikijs/types": "^1.22.2", "@types/markdown-it": "^14.1.2", "@vitejs/plugin-vue": "^5.1.4", - "@vue/devtools-api": "^7.4.6", + "@vue/devtools-api": "^7.5.4", "@vue/shared": "^3.5.12", "@vueuse/core": "^11.1.0", "@vueuse/integrations": "^11.1.0", "focus-trap": "^7.6.0", "mark.js": "8.11.1", "minisearch": "^7.1.0", - "shiki": "^1.22.0", - "vite": "^5.4.8", + "shiki": "^1.22.2", + "vite": "^5.4.10", "vue": "^3.5.12" }, "bin": { @@ -3315,6 +3391,229 @@ "vitepress": "^1.0.0 || ^1.0.0-alpha" } }, + "node_modules/vitepress-versioning-plugin": { + "version": "1.2.1", + "resolved": "git+ssh://git@github.com/GIScience/vitepress-versioning-plugin.git#d67244c11ecf0eec26185bf42b4beeb490321ead", + "dependencies": { + "@types/lodash": "^4.17.7", + "cli-color": "^2.0.4", + "json5": "^2.2.3", + "lodash": "^4.17.21", + "vite": "^5.3.4", + "vitepress": "1.3.1" + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/core": { + "version": "10.11.1", + "resolved": "https://registry.npmjs.org/@vueuse/core/-/core-10.11.1.tgz", + "integrity": "sha512-guoy26JQktXPcz+0n3GukWIy/JDNKti9v6VEMu6kV2sYBsWuGiTU8OWdg+ADfUbHg3/3DlqySDe7JmdHrktiww==", + "dependencies": { + "@types/web-bluetooth": "^0.0.20", + "@vueuse/metadata": "10.11.1", + "@vueuse/shared": "10.11.1", + "vue-demi": ">=0.14.8" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/core/node_modules/vue-demi": { + "version": "0.14.10", + "resolved": "https://registry.npmjs.org/vue-demi/-/vue-demi-0.14.10.tgz", + "integrity": "sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==", + "hasInstallScript": true, + "bin": { + "vue-demi-fix": "bin/vue-demi-fix.js", + "vue-demi-switch": "bin/vue-demi-switch.js" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "@vue/composition-api": "^1.0.0-rc.1", + "vue": "^3.0.0-0 || ^2.6.0" + }, + "peerDependenciesMeta": { + "@vue/composition-api": { + "optional": true + } + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/integrations": { + "version": "10.11.1", + "resolved": "https://registry.npmjs.org/@vueuse/integrations/-/integrations-10.11.1.tgz", + "integrity": "sha512-Y5hCGBguN+vuVYTZmdd/IMXLOdfS60zAmDmFYc4BKBcMUPZH1n4tdyDECCPjXm0bNT3ZRUy1xzTLGaUje8Xyaw==", + "dependencies": { + "@vueuse/core": "10.11.1", + "@vueuse/shared": "10.11.1", + "vue-demi": ">=0.14.8" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "async-validator": "^4", + "axios": "^1", + "change-case": "^4", + "drauu": "^0.3", + "focus-trap": "^7", + "fuse.js": "^6", + "idb-keyval": "^6", + "jwt-decode": "^3", + "nprogress": "^0.2", + "qrcode": "^1.5", + "sortablejs": "^1", + "universal-cookie": "^6" + }, + "peerDependenciesMeta": { + "async-validator": { + "optional": true + }, + "axios": { + "optional": true + }, + "change-case": { + "optional": true + }, + "drauu": { + "optional": true + }, + "focus-trap": { + "optional": true + }, + "fuse.js": { + "optional": true + }, + "idb-keyval": { + "optional": true + }, + "jwt-decode": { + "optional": true + }, + "nprogress": { + "optional": true + }, + "qrcode": { + "optional": true + }, + "sortablejs": { + "optional": true + }, + "universal-cookie": { + "optional": true + } + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/integrations/node_modules/vue-demi": { + "version": "0.14.10", + "resolved": "https://registry.npmjs.org/vue-demi/-/vue-demi-0.14.10.tgz", + "integrity": "sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==", + "hasInstallScript": true, + "bin": { + "vue-demi-fix": "bin/vue-demi-fix.js", + "vue-demi-switch": "bin/vue-demi-switch.js" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "@vue/composition-api": "^1.0.0-rc.1", + "vue": "^3.0.0-0 || ^2.6.0" + }, + "peerDependenciesMeta": { + "@vue/composition-api": { + "optional": true + } + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/metadata": { + "version": "10.11.1", + "resolved": "https://registry.npmjs.org/@vueuse/metadata/-/metadata-10.11.1.tgz", + "integrity": "sha512-IGa5FXd003Ug1qAZmyE8wF3sJ81xGLSqTqtQ6jaVfkeZ4i5kS2mwQF61yhVqojRnenVew5PldLyRgvdl4YYuSw==", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/shared": { + "version": "10.11.1", + "resolved": "https://registry.npmjs.org/@vueuse/shared/-/shared-10.11.1.tgz", + "integrity": "sha512-LHpC8711VFZlDaYUXEBbFBCQ7GS3dVU9mjOhhMhXP6txTV4EhYQg/KGnQuvt/sPAtoUKq7VVUnL6mVtFoL42sA==", + "dependencies": { + "vue-demi": ">=0.14.8" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/@vueuse/shared/node_modules/vue-demi": { + "version": "0.14.10", + "resolved": "https://registry.npmjs.org/vue-demi/-/vue-demi-0.14.10.tgz", + "integrity": "sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==", + "hasInstallScript": true, + "bin": { + "vue-demi-fix": "bin/vue-demi-fix.js", + "vue-demi-switch": "bin/vue-demi-switch.js" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "@vue/composition-api": "^1.0.0-rc.1", + "vue": "^3.0.0-0 || ^2.6.0" + }, + "peerDependenciesMeta": { + "@vue/composition-api": { + "optional": true + } + } + }, + "node_modules/vitepress-versioning-plugin/node_modules/vitepress": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.3.1.tgz", + "integrity": "sha512-soZDpg2rRVJNIM/IYMNDPPr+zTHDA5RbLDHAxacRu+Q9iZ2GwSR0QSUlLs+aEZTkG0SOX1dc8RmUYwyuxK8dfQ==", + "dependencies": { + "@docsearch/css": "^3.6.0", + "@docsearch/js": "^3.6.0", + "@shikijs/core": "^1.10.3", + "@shikijs/transformers": "^1.10.3", + "@types/markdown-it": "^14.1.1", + "@vitejs/plugin-vue": "^5.0.5", + "@vue/devtools-api": "^7.3.5", + "@vue/shared": "^3.4.31", + "@vueuse/core": "^10.11.0", + "@vueuse/integrations": "^10.11.0", + "focus-trap": "^7.5.4", + "mark.js": "8.11.1", + "minisearch": "^7.0.0", + "shiki": "^1.10.3", + "vite": "^5.3.3", + "vue": "^3.4.31" + }, + "bin": { + "vitepress": "bin/vitepress.js" + }, + "peerDependencies": { + "markdown-it-mathjax3": "^4", + "postcss": "^8" + }, + "peerDependenciesMeta": { + "markdown-it-mathjax3": { + "optional": true + }, + "postcss": { + "optional": true + } + } + }, "node_modules/vscode-jsonrpc": { "version": "8.2.0", "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz", @@ -3374,7 +3673,6 @@ "version": "3.5.12", "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.12.tgz", "integrity": "sha512-CLVZtXtn2ItBIi/zHZ0Sg1Xkb7+PU32bJJ8Bmy7ts3jxXTcbfsEfBivFYYWz1Hur+lalqGAh65Coin0r+HRUfg==", - "dev": true, "license": "MIT", "dependencies": { "@vue/compiler-dom": "3.5.12", @@ -3396,7 +3694,6 @@ "version": "2.0.4", "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", - "dev": true, "license": "MIT", "funding": { "type": "github", diff --git a/package.json b/package.json index e7a84565cd..551312126a 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { "type": "module", "devDependencies": { - "vitepress": "^1.0.0-rc.30", "mermaid": "^11.3.0", + "vitepress": "^1.5.0", "vitepress-plugin-mermaid": "^2.0.17" }, "scripts": { @@ -10,5 +10,8 @@ "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs", "build-preview": "vitepress build docs && vitepress preview docs" + }, + "dependencies": { + "vitepress-versioning-plugin": "git+https://github.com/GIScience/vitepress-versioning-plugin.git#fix-sidebar-rewrites" } }