poiidx

Efficient spatial indexing and querying of Points of Interest using PostgreSQL and PostGIS

poiidx is a Python library that makes it easy to work with OpenStreetMap Points of Interest (POIs) and administrative boundaries. It provides fast spatial queries using PostgreSQL/PostGIS and handles data downloading and indexing automatically.

Features

• 🚀 Fast spatial queries using PostGIS spatial indexes
• 📍 Find nearest POIs with distance filtering and ranking
• 🗺️ Administrative boundaries with hierarchical queries and localization
• 🔄 Automatic data management - downloads OSM data on-demand from Geofabrik
• 🎯 Flexible filtering - configure which POI types to index
• 🌍 Global coverage - supports all regions available on Geofabrik
• 💾 Efficient storage - only stores the POI types you need

Database Data is Temporary

poiidx automatically detects schema changes (from model updates or filter configuration changes) and will drop and recreate all data when outdated schemas are detected. Do not rely on the database for persistent storage - treat all data as temporary and regeneratable.

Quick Example

import yaml
import poiidx
from shapely.geometry import Point

# Configure which POI types to index
filter_config = [
    {
        'symbol': 'restaurant',
        'description': 'Restaurants and dining',
        'filters': [
            {'amenity': 'restaurant'},
            {'amenity': 'cafe'},
            {'amenity': 'bar'}
        ]
    }
]

# Initialize database
poiidx.init(
    filter_config=filter_config,
    host='localhost',
    database='poiidx_db',
    user='poiidx_user',
    password='your_password'
)

# Find nearby restaurants in Berlin
berlin = Point(13.4050, 52.5200)
pois = poiidx.get_nearest_pois(
    berlin,
    max_distance=1000,  # within 1km
    limit=5
)

for poi in pois:
    print(f"{poi['name']} - {poi['symbol']}")

# Get administrative hierarchy
hierarchy = poiidx.get_administrative_hierarchy_string(berlin)
print(hierarchy)  # "Berlin, Deutschland"

poiidx.close()

Installation

pip install poiidx

Requirements

• Python 3.8+
• PostgreSQL 12+ with PostGIS extension

Documentation Structure

This documentation follows the Diátaxis framework:

Tutorial

Learning-oriented - Start here if you're new to poiidx. A hands-on introduction that guides you through setting up poiidx and making your first queries.

How-to Guides

Problem-oriented - Practical guides for accomplishing specific tasks. Find solutions for common use cases and advanced scenarios.

Reference

Information-oriented - Complete API documentation. Look up function signatures, parameters, and return values.

Explanation

Understanding-oriented - Deep dives into how poiidx works. Learn about the architecture, design decisions, and underlying concepts.

Getting Help

• GitHub Issues: Report bugs or request features
• Source Code: View on GitHub

License

poiidx is distributed under the MIT License.

Data Sources & Attribution

OpenStreetMap

This project uses data from OpenStreetMap, distributed via Geofabrik. OpenStreetMap data is © OpenStreetMap contributors and available under the Open Database License (ODbL).

Wikidata

When country information is not available in OpenStreetMap data, it is supplemented using Wikidata. Wikidata content is © Wikidata contributors and available under CC0 1.0 Universal (CC0 1.0) Public Domain Dedication.