Openpoiservice (ops)

repository·main·Indexed 41 days ago

https://github.com/giscience/openpoiservice

A Flask-based service providing a customizable points of interest (POI) database derived from OpenStreetMap (OSM) data. It features a /pois API endpoint for querying POIs based on spatial geometry (bbox, geojson, buffer) and specific OSM tags, with support for deployment via Docker and PostGIS.

Tokens: 2.3K
Snippets: 9
Records: 10
Agent score: 2%

What's inside Openpoiservice

Initialize, update, or manage the POI database with Docker
main
After deploying your containers, use docker exec to run management commands inside the container.
Database Management
- Create an empty database:
  docker exec -it container_name /ops_venv/bin/python manage.py create-db
- Delete the database:
  docker exec -it container_name /ops_venv/bin/python manage.py drop-db
- Import OSM data:
  docker exec -it container_name /ops_venv/bin/python manage.py import-data
Using Docker Compose for Init/Update
Alternatively, you can use the init or update services defined in your docker-compose file:
- Initialize: docker-compose -f /path/to/docker-compose.yml up init
- Update: docker-compose -f /path/to/docker-compose.yml up update
```
docker exec -it container_name /ops_venv/bin/python manage.py import-data
```
https://github.com/giscience/openpoiservice/blob/main/README.md
Install and run Openpoiservice on a host machine
main
To run Openpoiservice directly on your host machine:
1. Requirements: Python 3.5 or greater.
2. Database: Requires a psql/postgis setup.
3. Setup Settings: Update openpoiservice/server/ops_settings.yml and export the configuration environment variable:
  export APP_SETTINGS="openpoiservice.server.config.ProductionConfig|DevelopmentConfig"
4. Database Operations:
  Create DB: python manage.py create-db
  Drop DB: python manage.py drop-db
  Import Data: python manage.py import-data
5. Run the Application:
  python manage.py run
  The service defaults to http://localhost:5000/. To use a different port:
  python manage.py run -h 0.0.0.0 -p 8080
```
python manage.py run
```
https://github.com/giscience/openpoiservice/blob/main/README.md
Install and run Openpoiservice via Docker
main
You can deploy Openpoiservice using Docker. The provided Dockerfile installs a WSGI server (gunicorn) which starts the Flask service on port 5000.
All-in-one deployment (with PostGIS)
Use the docker-compose-with-postgis.yml to run Openpoiservice along with a psql/postgis image.
Note: The database is not exposed by default. To access it from outside the container, add the following to the database definition in docker-compose-with-postgis.yml:
```
ports:
   - <PORT YOU WANT>:5432
```
Ensure the hostname and port in ops_settings_docker.yml match the database container settings (default hostname: psql_postgis_db, default port: 5432).
To run the all-in-one container:
```
docker-compose -f /path/to/docker-compose.yml up api -d
```
Standalone deployment
If you want to manage the database yourself, use the standalone configuration:
```
docker-compose -f /path/to/docker-compose-standalone.yml up api -d
```
https://github.com/giscience/openpoiservice/blob/main/README.md
Configure Category IDs and OSM tag mappings
main
Openpoiservice maps OpenStreetMap tags to custom category IDs during import.
Category Configuration
Edit openpoiservice/server/categories/categories.yml to define the hierarchy and IDs. For example:
```
transport:
    id: 580
    children:
        aeroway:
            aerodrome: 581        
            aeroport: 582 
```
OSM Tag Mapping
In openpoiservice/server/ops_settings.yml, the column_mappings section controls which OSM tags are imported and made available for API filtering (e.g., wheelchair, smoking, fees). If a tag is listed here, it will be saved to the database and can be used in the filters object of an API request.
https://github.com/giscience/openpoiservice/blob/main/README.md
Configure OpenPOIservice with Docker Compose
main
To run OpenPOIservice using Docker Compose, you must manage two primary configuration files that are mounted into the containers:
1. ops_settings_docker.yml: This file must be updated to match the database connection details. Specifically, the host name must be set to the name of the database service defined in the compose file (e.g., db), and the port should be set to 5432 since they share the same network.
2. categories_docker.yml: Used for category definitions.
Database Credentials Synchronization: The environment variables in the db service must match the credentials configured in ops_settings_docker.yml:
- POSTGRES_USER
- POSTGRES_PASSWORD
- POSTGRES_DBNAME (or POSTGRES_DB)
Volumes:
- ./osm: Local directory containing OSM data files, mounted to /deploy/app/osm in the containers.
- ./import-log.json: Used by init and update services to track import progress.
https://github.com/giscience/openpoiservice/blob/main/docker-compose.yml
Initialize or Update the POI Database using Docker Compose
main
The init and update services are not started by default. They are used to perform specific database lifecycle tasks. You can run them manually using docker-compose up followed by the service name.
- Initialize the DB: Use docker-compose up init to create the initial database structure and import data.
- Update the DB: Use docker-compose up update to perform updates to the existing database.
Both services require the db service to be healthy before they start and require access to the ./osm directory and configuration files.
```
docker-compose up init
docker-compose up update
```
https://github.com/giscience/openpoiservice/blob/main/docker-compose.yml

Filter POIs by category or OSM tags

main

When querying the /pois endpoint, you can use the filters object to narrow down results.

Filtering by Category IDs

To find POIs belonging to specific categories, use category_ids:

{
  "request": "pois",
  "geometry": { ... },
  "filters": {
    "category_ids": [180, 245]
  }
}

Filtering by Category Groups

To find POIs belonging to entire groups of categories, use category_group_ids:

{
  "request": "pois",
  "geometry": { ... },
  "filters": {
    "category_group_ids": [160]
  }
}

Filtering by OSM Tags

If the tags are configured in column_mappings within ops_settings.yml, you can filter by specific tag values (e.g., wheelchair or smoking):

{
  "request": "pois",
  "geometry": { ... },
  "filters": {
    "wheelchair": ["yes", "dedicated"]
  }
}

{
  "request": "pois",
  "geometry": {
    "bbox": [
      [8.8034, 53.0756],
      [8.7834, 53.0456]
    ],
    "geojson": {
      "type": "Point",
      "coordinates": [8.8034, 53.0756]
    },
    "buffer": 100
  },
  "limit": 200,
  "filters": {
    "category_ids": [180, 245]
  } 
}

Use the /pois API endpoint

main

The /pois endpoint is used to query points of interest. It accepts POST requests with a JSON body.

Request Parameters

Parameter	Values	Description
`request`	`pois`, `stats`, `list`	Determines the response type
`geometry`	`bbox`, `geojson`, `buffer`	Defines the spatial search area
`filter`	`category_group_ids`, `category_ids`, `[name, wheelchair, smoking, fee]`	Filters results by category or specific OSM tags
`limit`	integer	Maximum number of results
`sortby`	`category`, `distance`	Sorting criteria

Request Types

request=pois: Returns a GeoJSON FeatureCollection within the specified geometry.
request=stats: Returns a JSON object with absolute counts of POIs grouped by categories.
request=list: Returns a JSON object containing the list of categories defined in categories.yml.

Example: Query POIs around a buffered point

curl -X POST http://localhost:5000/pois \
  -H 'Content-Type: application/json' \
  -d '{
  "request": "pois",
  "geometry": {
    "bbox": [[8.8034, 53.0756], [8.7834, 53.0456]],
    "geojson": {"type": "Point", "coordinates": [8.8034, 53.0756]},
    "buffer": 250
  }
}'

curl -X POST \
  http://localhost:5000/pois \
  -H 'Content-Type: application/json' \
  -d '{
  "request": "pois",
  "geometry": {
    "bbox": [
      [8.8034, 53.0756],
      [8.7834, 53.0456]
    ],
    "geojson": {
      "type": "Point",
      "coordinates": [8.8034, 53.0756]
    },
    "buffer": 250
  }
}'

Reference: Docker Compose Service Environment Variables for Task Services
main
The following environment variables trigger specific behaviors in the application containers when run as standalone services.
```
# init service
INIT_DB: 1

# update service
UPDATE_DB: 1

# test service
TESTING: True
```
https://github.com/giscience/openpoiservice/blob/main/docker-compose.yml

Reference: Docker Compose Service Environment Variables

main

The following environment variables are used within the db service to configure the PostGIS instance and access control.

# db service environment variables
POSTGRES_DB: "gis"             # The name of the database to create
POSTGRES_USER: "gis_admin"      # Database user (must match ops_settings_docker.yml)
POSTGRES_PASSWORD: "admin"      # Database password (must match ops_settings_docker.yml)
POSTGRES_DBNAME: "gis"         # Database name (must match ops_settings_docker.yml)
ALLOW_IP_RANGE: "0.0.0.0/0"     # Network access control

Openpoiservice (ops)

What's inside Openpoiservice

Database Management

Using Docker Compose for Init/Update

All-in-one deployment (with PostGIS)

Standalone deployment

Category Configuration

OSM Tag Mapping

Filtering by Category IDs

Filtering by Category Groups

Filtering by OSM Tags

Request Parameters

Request Types

Example: Query POIs around a buffered point