{"id":15611472,"url":"https://github.com/giscience/openpoiservice","last_synced_at":"2025-04-05T23:07:44.882Z","repository":{"id":28865191,"uuid":"119561991","full_name":"GIScience/openpoiservice","owner":"GIScience","description":":round_pushpin: Openpoiservice is a flask application which hosts a highly customizable points of interest database derived from OpenStreetMap data.","archived":false,"fork":false,"pushed_at":"2024-05-14T22:16:39.000Z","size":17488,"stargazers_count":176,"open_issues_count":34,"forks_count":22,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-05T23:07:39.205Z","etag":null,"topics":["giscience","openstreetmap","openstreetmap-data","openstreetmap-protobuffer-format"],"latest_commit_sha":null,"homepage":"https://openrouteservice.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-30T16:21:50.000Z","updated_at":"2025-03-27T19:33:27.000Z","dependencies_parsed_at":"2024-02-19T14:02:40.519Z","dependency_job_id":"2f8f9f57-bfb4-432d-8687-e0cb96b71637","html_url":"https://github.com/GIScience/openpoiservice","commit_stats":{"total_commits":188,"total_committers":17,"mean_commits":"11.058823529411764","dds":0.5797872340425532,"last_synced_commit":"a6baad38c9d423b12c499e8f67569d1c831e2b79"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenpoiservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenpoiservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenpoiservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenpoiservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/openpoiservice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411234,"owners_count":20934653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["giscience","openstreetmap","openstreetmap-data","openstreetmap-protobuffer-format"],"created_at":"2024-10-03T06:04:41.767Z","updated_at":"2025-04-05T23:07:44.863Z","avatar_url":"https://github.com/GIScience.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Openpoiservice \n\n[![Tests](https://github.com/GIScience/openpoiservice/workflows/run%20tests/badge.svg)](https://github.com/GIScience/openpoiservice/actions?query=workflow%3A%22run+tests%22)\n\nOpenpoiservice (ops) is a flask application which hosts a highly customizable points of interest database derived from \nOpenStreetMap.org data and thereby **exploits** its notion of tags...\n\n\u003e OpenStreetMap [tags](https://wiki.openstreetmap.org/wiki/Tags) consisting of a key and value describe specific features of \n\u003e map elements (nodes, ways, or relations) or changesets.  Both items are free format text fields, but often represent numeric \n\u003e or other structured items. \n\nThis service consumes OSM tags on nodes, ways and relations by grouping them into predefined categories. \nIf it picks up an OSM object tagged with one of the osm keys defined in `categories.yml` it will import this \npoint of interest with specific additional tags which may be defined in `ops_settings.yml`. Any additional tag, \nfor instance `wheelchair` or `smoking` may then be used to query the service via the API after import.\n\nFor instance, if you want to request all pois accessible by wheelchair within a geometry, you could add then add \n`wheelchair: ['yes', 'dedicated]` in `filters` within the body of your HTTP POST request. \n\nYou may pass 3 different types of geometry within the request to the database. Currently, \"Point\" and \"LineString\" with\na corresponding and buffer are supported as well as a polygon. Points of interest will be returned within the given geometry.\n\nYou can control the maximum size of geometries and further restrictions in the settings file of this service.\n\n#### Import Process \n\nThe osm file(s) to be imported are parsed several times to extract points of interest from relations (osm_type 3), \nways (osm_type 2) and nodes (osm_type 1) in order. Which type the specific point of interest originated from will be \nreturned within the response - this will help you find the object directly on [OpenStreetMap.org](https://www.openstreetmap.org). \n\n## Installation\n\nYou can either run **openpoiservice** on your host machine in a virtual environment or simply with Docker. The Dockerfile \nprovided installs a WSGI server (gunicorn) which starts the flask service on port 5000.\n\n\n### Technical specs for storing and importing OSM files\n\n##### Python version\n\nAs this service makes use of the python collections library, in particular the notion of deque's and its functions\nit only supports python 3.5 and greater.\n\n##### Database\nThis application uses a psql/postgis setup for storing the points of interest. We highly recommend [using this](https://github.com/kartoza/docker-postgis) \ndocker container.\n\n##### Importer\nPlease consider the following technical requirements for parsing \u0026 importing osm files.\n\n| Region        | Memory        | \n| ------------- |:-------------:|\n| Germany       | 8 GB         |\n| Europe        | 32 GB         | \n| Planet        | 128 GB        | \n\n**Note:** Openpoiservice will import any osm pbf file located in the osm folder or subdirectory within. \nThis way you can split the planet file into smaller regions (e.g. download from Geofabrik, scraper script for the download\nlinks to be found in the osm folder) and use a *smaller* instance to import the global data set (as long as\nthe OSM files don't exceed 5 GB of disk space, 16 GB of memory will suffice to import the entire planet).\n\n### Run as Docker Container (Flask + Gunicorn)\n\nMake your necessary changes to the settings in the file `ops_settings_docker.yml` and to categories if you need inside `categories_docker.yml`. These files are mounted as volumes to the docker container.\nIf you are planning to import a different osm file, please download it to the `osm folder` (any folder within will be scanned\nfor osm files) as this will be a shared volume. \n\n### Docker Compose\n\n#### All-in-one docker image\n\nThis docker-compose will allow you to run openpoiservice with `psql/postgis` image. This will allow you to deploy this project fast.\n\n**Important :** The database is not exposed, you won't be able to access it from outside the container. If you want to acces it simply adds those lines to the database definition inside the `docker-compose-with-postgis.yml`:\n\n```sh\nports:\n   - \u003cPORT YOU WANT\u003e:5432\n```\n\nDon't forget to change the host name and port inside `ops_settings_docker.yml` by the one given to docker container for database.\n\n* Hostname default value : `psql_postgis_db`\n* Port default value : `5432`\n\n\n**Notes :** If openpoiservice can't connect to the database, it's probably because you don't have the same settings inside `ops_settings_docker.yml` and `docker-compose-with-postgis.yml`.\n\nCommand to use to run all-in-one docker container\n\n```sh\ndocker-compose -f /path/to/docker-compose.yml up api -d\n```\n\n#### Only deploy openpoiservice\n\nThis will only run openpoiservice inside a container, meaning that you will need to handle the database yourself and connect it to this container.\n\n```sh\ndocker-compose -f /path/to/docker-compose-standalone.yml up api -d\n```\n\n#### After deploy\n\nOnce the container is built you can either, create the empty database:\n\n```sh\n$ docker exec -it container_name /ops_venv/bin/python manage.py create-db\n```\n\nDelete the database:\n\n```sh\n$ docker exec -it container_name /ops_venv/bin/python manage.py drop-db\n```\n\nOr import the OSM data:\n\n```sh\n$ docker exec -it container_name /ops_venv/bin/python manage.py import-data\n```\n\n### Init and Update DB with docker\nYou can initialize POI database with docker service init\n\n```sh\ndocker-compose -f /path/to/docker-compose.yml up init\n```\n\nOr updating POI database\n```sh\ndocker-compose -f /path/to/docker-compose.yml up update\n```\n\n\n### Protocol Buffers (protobuf) for imposm.parser \n\nThis repository uses [imposm.parser](https://imposm.org/docs/imposm.parser/latest/index.html) to parse the \nOpenStreetMap pbf files which uses `google's protobuf library` under its hood.\n\n**The imposm.parser requirement will not build with pip unless you are running [protobuf 3.0.0](https://github.com/protocolbuffers/protobuf/releases/tag/v3.0.0).** \n\nTo this end, please make sure that you are running the aforementioned version of protobuf if `pip install -r requirements.txt` fails (install protobuf [from source](https://github.com/google/protobuf/blob/master/src/README.md)) \n\n### Prepare settings.yml\n\nUpdate `openpoiservice/server/ops_settings.yml` with your necessary settings and then run one of the following\ncommands.\n\n[\n```sh\n$ export APP_SETTINGS=\"openpoiservice.server.config.ProductionConfig|DevelopmentConfig\"\n```\n]\n\n\n### Create the POI DB\n\n```sh\n$ python manage.py create-db\n```\n### Drop the POI DB\n\n```sh\n$ python manage.py drop-db\n```\n\n### Parse and import OSM data\n\n```sh\n$ python manage.py import-data\n```\n\n### Run the Application with Flask-Werkzeug\n\n```sh\n$ python manage.py run\n```\n\nPer default you can access the application at the address [http://localhost:5000/](http://localhost:5000/)\n\n\u003e Want to specify a different port?\n\n\u003e ```sh\n\u003e $ python manage.py run -h 0.0.0.0 -p 8080\n\u003e ```\n\n### Tests\n\n```sh\n$ export TESTING=\"True\" \u0026\u0026 python manage.py test\n```\n\n\n### Category IDs and their configuration\n\n`openpoiservice/server/categories/categories.yml` is a list of (**note:** not all!) OpenStreetMap tags with arbitrary category IDs. \nIf you keep the structure as follows, you can manipulate this list as you wish.\n \n ```yaml\n transport:\n    id: 580\n    children:\n        aeroway:\n            aerodrome: 581        \n            aeroport: 582 \n            helipad: 598         \n            heliport: 599 \n        amenity:\n            bicycle_parking: 583  \n            \n sustenance:\n    id: 560             \n    children:\n        amenity:\n            bar: 561             \n            bbq: 562   \n ...\n ```\n \n Openpoiservice uses this mapping while it imports pois from the OpenStreetMap data and assigns the custom category IDs\n accordingly.\n\n`column_mappings` in `openpoiservice/server/ops_settings.yml` controls which OSM information will be considered in the database and also if \nthese may be queried by the user via the API , e.g.\n\n```yaml\nwheelchair:\n\nsmoking:\n\nfees:\n```\n\nFor instance means that the OpenStreetMap tag [wheelchair](https://wiki.openstreetmap.org/wiki/Key:wheelchair) will be considered\nduring import and save to the database. A user may then add a list of common values in the filters object `wheelchair: ['yes', 'dedicated', ...]` \nwhich correspond to the OSM common values of the tag itself, e.g. \n[https://wiki.openstreetmap.org/wiki/Key:wheelchair](https://wiki.openstreetmap.org/wiki/Key:wheelchair).\n\n### API Documentation\n\nThe documentation for this flask service is provided via [flasgger](https://github.com/rochacbruno/flasgger) and can be\naccessed via `http://localhost:5000/apidocs/`.\n\nGenerally you have three different request types `pois`, `stats` and\n`list`.\n\nUsing `request=pois` in the POST body will return a GeoJSON FeatureCollection\nin your specified bounding box or geometry. \n\nUsing `request=stats` will do the same but group by the categories, ultimately\nreturning a JSON object with the absolute numbers of pois of a certain group. \n\nFinally, `request=list` will return a JSON object generated from \n`openpoiservice/server/categories/categories.yml`.\n\n### Endpoints\n\nThe default base url is `http://localhost:5000/`.\n\nThe openpoiservice holds the endpoint `/pois`:\n\n| Method allowed | Parameter | Values \\[optional\\]                            \t\t\t     |\n|----------------|:----------|:----------------------------------------------------------------------|\n| POST           | request   | pois, stats, list                 \t\t\t\t     |\n|                | geometry  | bbox, geojson, buffer             \t\t\t\t     |\n|                | filter    | category_group_ids, category_ids, \\[name, wheelchair, smoking, fee\\]  | \n|                | limit     | integer                           \t\t\t\t     |\n|                | sortby    | category, distance                \t\t\t\t     |\n\n### Examples\n\n##### POIS around a buffered point\n\n```sh\ncurl -X POST \\\n  http://localhost:5000/pois \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"request\": \"pois\",\n  \"geometry\": {\n    \"bbox\": [\n      [8.8034, 53.0756],\n      [8.7834, 53.0456]\n    ],\n    \"geojson\": {\n      \"type\": \"Point\",\n      \"coordinates\": [8.8034, 53.0756]\n    },\n    \"buffer\": 250  \n  }\n}'\n```\n\n##### POIs of given categories\n```sh\ncurl -X POST \\\n  http://localhost:5000/pois \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"request\": \"pois\",\n  \"geometry\": {\n    \"bbox\": [\n      [8.8034, 53.0756],\n      [8.7834, 53.0456]\n    ],\n    \"geojson\": {\n      \"type\": \"Point\",\n      \"coordinates\": [8.8034, 53.0756]\n    },\n    \"buffer\": 100  \n  },\n  \"limit\": 200,\n  \"filters\": {\n    \"category_ids\": [180, 245]\n  } \n}'\n```\n\n##### POIs of given category groups\n\n```sh\ncurl -X POST \\\n  http://localhost:5000/pois \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"request\": \"pois\",\n  \"geometry\": {\n    \"bbox\": [\n      [8.8034, 53.0756],\n      [8.7834, 53.0456]\n    ],\n    \"geojson\": {\n      \"type\": \"Point\",\n      \"coordinates\": [8.8034, 53.0756]\n    },\n    \"buffer\": 100  \n  },\n  \"limit\": 200,\n  \"filters\": {\n    \"category_group_ids\": [160]\n  } \n}'\n```\n\n##### POI Statistics\n```sh\ncurl -X POST \\\n  http://129.206.7.157:5005/pois \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"request\": \"stats\",\n  \"geometry\": {\n    \"bbox\": [\n      [8.8034, 53.0756],\n      [8.7834, 53.0456]\n    ],\n    \"geojson\": {\n      \"type\": \"Point\",\n      \"coordinates\": [8.8034, 53.0756]\n    },\n    \"buffer\": 100  \n  }\n}'\n```\n\n##### POI Categories as a list\n\n```sh\ncurl -X POST \\\n  http://127.0.0.1:5000/pois \\\n  -H 'content-type: application/json' \\\n  -d '{\n\t\"request\": \"list\"\n}'\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fopenpoiservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiscience%2Fopenpoiservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiscience%2Fopenpoiservice/lists"}