From 14a1ce4ff5d4a5e3cd66d3e3a01d9344428f5e77 Mon Sep 17 00:00:00 2001 From: aoles Date: Wed, 22 May 2024 14:26:01 +0200 Subject: [PATCH] docs: snapping endpoint now available in the public API --- README.md | 236 +++++++++--------- docs/api-reference/endpoints/index.md | 2 +- .../api-reference/endpoints/snapping/index.md | 10 +- docs/api-reference/index.md | 2 +- docs/getting-started.md | 2 +- 5 files changed, 123 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index 3f68173335..749f319505 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,118 @@ -# Openrouteservice - -[![Docker Nightly Build Status](https://img.shields.io/github/actions/workflow/status/GIScience/openrouteservice/docker-nightly-image.yml?style=flat&label=Docker%20Nightly&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fheigit%2Fopenrouteservice%2Ftags)](https://hub.docker.com/r/heigit/openrouteservice/tags) -[![Docker Version Status](https://img.shields.io/github/actions/workflow/status/GIScience/openrouteservice/publish-tagged-release.yml?style=flat&label=Docker%20Latest&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fheigit%2Fopenrouteservice%2Ftags)](https://hub.docker.com/r/heigit/openrouteservice/tags) -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) -[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) -[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) -[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) -[![Release](https://img.shields.io/github/v/release/GIScience/openrouteservice)](https://github.com/GIScience/openrouteservice/releases/latest) -[![LICENSE](https://img.shields.io/github/license/GIScience/openrouteservice)](LICENSE) - -Openrouteservice is a highly customizable, performant routing service written in Java. -It uses a [forked and edited version of graphhopper 4.0](https://github.com/GIScience/graphhopper) -and provides global spatial services by consuming user-generated and collaboratively collected free geographic data directly from [OpenStreetMap](http://www.openstreetmap.org): - -* [Directions Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/directions/): Get directions for different modes of transport -* [Isochrones Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/isochrones/): Obtain areas of reachability from given locations -* [Matrix Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/matrix/): Obtain one-to-many, many-to-one and many-to-many matrices for time and distance -* [Snapping Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/snapping/)¹: Snap coordinates to the graph edges -* [Export Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/export/)¹: Export the base graph for different modes of transport -* [Health Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/health/)¹: Get information on the health of the running openrouteservice instance -* [Status Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/status/)¹: Get information on the status of the openrouteservice instance - -¹) **Snapping, Export, Health and Status Endpoint are not available in our public openrouteservice API aka "live API"!** -You can use them by running your own instance of openrouteservice. - -And to avoid any misunderstandings, it should also be mentioned at this point that our live API provides several other endpoints -that are **not part of the openrouteservice software/repository**: - -* [openpoiservice](https://github.com/GIScience/openpoiservice): A stand-alone service from HeiGIT that returns points of interest in the area surrounding a geometry -* [openelevationservice](https://github.com/GIScience/openelevationservice): A stand-alone service from HeiGIT that returns the elevation for point or line geometries -* [Pelias](https://www.pelias.io): A (reverse) geocoder hosted by HeiGIT that resolves geographic coordinates to addresses and vice versa -* [VROOM](https://github.com/VROOM-Project/vroom): The Vehicle Routing Open-source Optimization Machine hosted by HeiGIT - -To play around with openrouteservice you may use our [demonstration server](https://maps.openrouteservice.org) which comes with both the backend and a [frontend](https://github.com/GIScience/ors-map-client). -Or simply [sign up](https://openrouteservice.org/dev/#/signup) for an API key and fire your requests against the API directly. -You can also do this in our [API Playground](https://openrouteservice.org/dev/#/api-docs) - take a look at the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) to get more information. - -![map-client-isochrones](docs/public/map-client-isochrones.png) - - -## Installation - -You can easily [run openrouteservice](https://giscience.github.io/openrouteservice/run-instance/) yourself! - -**tl;dr:** We suggest [using docker](https://giscience.github.io/openrouteservice/run-instance/running-with-docker) to install and launch openrouteservice. -In short, a machine with a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker) will get everything done for you. - -Change to the directory where you want to install your local openrouteservice and first create some directories, where openrouteservice will persist its data: -```shell -mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/graphs ors-docker/files ors-docker/logs -``` - -Only use nightly (main branch) if you know what you do. -We recommend running docker compose with the latest release version. -Get the docker compose file for a release, e.g. v8.0.0: -```shell -wget https://github.com/GIScience/openrouteservice/releases/download/v8.0.0/docker-compose.yml -``` - -Start openrouteservice in the background: -```shell -docker compose up -d -``` - -This will pull the openrouteservice docker image 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 -``` - -Stop the container with: -```shell -docker compose down -``` - -## Usage - -The above mentioned endpoints will be available on port 8080: - -- `http://localhost:8080/ors/v2/directions` -- `http://localhost:8080/ors/v2/isochrones` -- `http://localhost:8080/ors/v2/matrix` -- `http://localhost:8080/ors/v2/snap` -- `http://localhost:8080/ors/v2/export` -- `http://localhost:8080/ors/v2/health` -- `http://localhost:8080/ors/v2/status` - -You can find more information in the endpoint documentation pages linked above. - -On the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) there is also a description -how you can use the Swagger-UI and the API Playground for local instances of openrouteservice. - - -## Changelog/latest changes - -[Openrouteservice CHANGELOG](https://github.com/GIScience/openrouteservice/blob/main/CHANGELOG.md) - - -## Contribute - -We appreciate any kind of contribution - bug reports, new feature suggestion or improving our translations are greatly appreciated. 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-map-client/issues). - -If you want to contribute your improvements, please follow the steps outlined in [our CONTRIBUTION guidelines](./CONTRIBUTE.md) - -The [sourcespy dashboard](https://sourcespy.com/github/giscienceopenrouteservice/) provides a high level overview of the repository including technology summary, module dependencies and other components of the system. - - -## Questions - -For questions please use our [community forum](https://ask.openrouteservice.org). - - -## Translations - -If you notice anything wrong with translations, or you want to add a new language to the ORS instructions, we have some instructions in our [backend documentation](https://GIScience.github.io/openrouteservice/contributing/contributing-translations) about how you can submit an update. You can also look over at our [maps client GitHub](https://github.com/GIScience/ors-map-client/#add-language) if you want to contribute the language to there as well (adding or editing the language in the openrouteservice GitHub repo only affects the instructions - any new language also needs adding to the client). +# Openrouteservice + +[![Docker Nightly Build Status](https://img.shields.io/github/actions/workflow/status/GIScience/openrouteservice/docker-nightly-image.yml?style=flat&label=Docker%20Nightly&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fheigit%2Fopenrouteservice%2Ftags)](https://hub.docker.com/r/heigit/openrouteservice/tags) +[![Docker Version Status](https://img.shields.io/github/actions/workflow/status/GIScience/openrouteservice/publish-tagged-release.yml?style=flat&label=Docker%20Latest&link=https%3A%2F%2Fhub.docker.com%2Fr%2Fheigit%2Fopenrouteservice%2Ftags)](https://hub.docker.com/r/heigit/openrouteservice/tags) +[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) +[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) +[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) +[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=GIScience_openrouteservice&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=GIScience_openrouteservice) +[![Release](https://img.shields.io/github/v/release/GIScience/openrouteservice)](https://github.com/GIScience/openrouteservice/releases/latest) +[![LICENSE](https://img.shields.io/github/license/GIScience/openrouteservice)](LICENSE) + +Openrouteservice is a highly customizable, performant routing service written in Java. +It uses a [forked and edited version of graphhopper 4.0](https://github.com/GIScience/graphhopper) +and provides global spatial services by consuming user-generated and collaboratively collected free geographic data directly from [OpenStreetMap](http://www.openstreetmap.org): + +* [Directions Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/directions/): Get directions for different modes of transport +* [Isochrones Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/isochrones/): Obtain areas of reachability from given locations +* [Matrix Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/matrix/): Obtain one-to-many, many-to-one and many-to-many matrices for time and distance +* [Snapping Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/snapping/): Snap coordinates to the graph edges +* [Export Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/export/)¹: Export the base graph for different modes of transport +* [Health Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/health/)¹: Get information on the health of the running openrouteservice instance +* [Status Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/status/)¹: Get information on the status of the openrouteservice instance + +¹) **Export, Health and Status Endpoint are not available in our public openrouteservice API aka "live API"!** +You can use them by running your own instance of openrouteservice. + +And to avoid any misunderstandings, it should also be mentioned at this point that our live API provides several other endpoints +that are **not part of the openrouteservice software/repository**: + +* [openpoiservice](https://github.com/GIScience/openpoiservice): A stand-alone service from HeiGIT that returns points of interest in the area surrounding a geometry +* [openelevationservice](https://github.com/GIScience/openelevationservice): A stand-alone service from HeiGIT that returns the elevation for point or line geometries +* [Pelias](https://www.pelias.io): A (reverse) geocoder hosted by HeiGIT that resolves geographic coordinates to addresses and vice versa +* [VROOM](https://github.com/VROOM-Project/vroom): The Vehicle Routing Open-source Optimization Machine hosted by HeiGIT + +To play around with openrouteservice you may use our [demonstration server](https://maps.openrouteservice.org) which comes with both the backend and a [frontend](https://github.com/GIScience/ors-map-client). +Or simply [sign up](https://openrouteservice.org/dev/#/signup) for an API key and fire your requests against the API directly. +You can also do this in our [API Playground](https://openrouteservice.org/dev/#/api-docs) - take a look at the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) to get more information. + +![map-client-isochrones](docs/public/map-client-isochrones.png) + + +## Installation + +You can easily [run openrouteservice](https://giscience.github.io/openrouteservice/run-instance/) yourself! + +**tl;dr:** We suggest [using docker](https://giscience.github.io/openrouteservice/run-instance/running-with-docker) to install and launch openrouteservice. +In short, a machine with a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker) will get everything done for you. + +Change to the directory where you want to install your local openrouteservice and first create some directories, where openrouteservice will persist its data: +```shell +mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/graphs ors-docker/files ors-docker/logs +``` + +Only use nightly (main branch) if you know what you do. +We recommend running docker compose with the latest release version. +Get the docker compose file for a release, e.g. v8.0.0: +```shell +wget https://github.com/GIScience/openrouteservice/releases/download/v8.0.0/docker-compose.yml +``` + +Start openrouteservice in the background: +```shell +docker compose up -d +``` + +This will pull the openrouteservice docker image 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 +``` + +Stop the container with: +```shell +docker compose down +``` + +## Usage + +The above mentioned endpoints will be available on port 8080: + +- `http://localhost:8080/ors/v2/directions` +- `http://localhost:8080/ors/v2/isochrones` +- `http://localhost:8080/ors/v2/matrix` +- `http://localhost:8080/ors/v2/snap` +- `http://localhost:8080/ors/v2/export` +- `http://localhost:8080/ors/v2/health` +- `http://localhost:8080/ors/v2/status` + +You can find more information in the endpoint documentation pages linked above. + +On the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) there is also a description +how you can use the Swagger-UI and the API Playground for local instances of openrouteservice. + + +## Changelog/latest changes + +[Openrouteservice CHANGELOG](https://github.com/GIScience/openrouteservice/blob/main/CHANGELOG.md) + + +## Contribute + +We appreciate any kind of contribution - bug reports, new feature suggestion or improving our translations are greatly appreciated. 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-map-client/issues). + +If you want to contribute your improvements, please follow the steps outlined in [our CONTRIBUTION guidelines](./CONTRIBUTE.md) + +The [sourcespy dashboard](https://sourcespy.com/github/giscienceopenrouteservice/) provides a high level overview of the repository including technology summary, module dependencies and other components of the system. + + +## Questions + +For questions please use our [community forum](https://ask.openrouteservice.org). + + +## Translations + +If you notice anything wrong with translations, or you want to add a new language to the ORS instructions, we have some instructions in our [backend documentation](https://GIScience.github.io/openrouteservice/contributing/contributing-translations) about how you can submit an update. You can also look over at our [maps client GitHub](https://github.com/GIScience/ors-map-client/#add-language) if you want to contribute the language to there as well (adding or editing the language in the openrouteservice GitHub repo only affects the instructions - any new language also needs adding to the client). diff --git a/docs/api-reference/endpoints/index.md b/docs/api-reference/endpoints/index.md index 79eb899866..e8e40c5d6e 100644 --- a/docs/api-reference/endpoints/index.md +++ b/docs/api-reference/endpoints/index.md @@ -12,7 +12,7 @@ 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 graph edges _(:warning: not available in our live API)_ +* [Snapping Service](snapping/index.md): Snap coordinates to the graph edges ## Technical Endpoints diff --git a/docs/api-reference/endpoints/snapping/index.md b/docs/api-reference/endpoints/snapping/index.md index ce97e3b639..18913491ae 100644 --- a/docs/api-reference/endpoints/snapping/index.md +++ b/docs/api-reference/endpoints/snapping/index.md @@ -1,15 +1,9 @@ # Snapping 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). -::: - 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. +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, @@ -19,7 +13,7 @@ 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. +and therefore the first entry in the result `locations` is `null`. Request: ```shell diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index 300bd83273..62d8f71859 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -8,7 +8,7 @@ The following chapter [Endpoints](endpoints/index.md) contains explanation and e 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), [Snapping](endpoints/snapping/index.md), [Health](endpoints/health/index.md) and [Status](endpoints/status/index.md). +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). diff --git a/docs/getting-started.md b/docs/getting-started.md index 91f591bf8a..d4630a6995 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,7 +7,7 @@ The fastest way to get to the info you are looking for is **the search bar above * [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 _(not available in our live API)_ + * [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)