poiidx

poiidx is a Python library for efficient spatial indexing and querying of Points of Interest (POIs) using PostgreSQL and PostGIS. It enables you to quickly find nearby POIs, retrieve administrative boundaries, and explore geographic hierarchies based on OpenStreetMap data.

📚 Read the full documentation for detailed guides, tutorials, and API reference.

Installation
Database Setup
Usage
License

Installation

pip install poiidx

Database Setup

Install PostgreSQL and PostGIS

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgis

macOS:

brew install postgresql@16 postgis
brew services start postgresql@16

Arch Linux:

sudo pacman -S postgresql postgis
sudo -u postgres initdb -D /var/lib/postgres/data
sudo systemctl start postgresql

Create Database and User

# Create user
sudo -u postgres createuser -P poiidx_user
# Enter password when prompted

# Create database
sudo -u postgres createdb -O poiidx_user poiidx_db

# Enable PostGIS extension
sudo -u postgres psql -d poiidx_db -c "CREATE EXTENSION postgis;"

Usage

import poiidx
from shapely.geometry import Point

# Initialize the database connection
poiidx.init(
    host='localhost',
    database='poiidx_db',
    user='poiidx_user',
    password='your_secure_password',
    port=5432
)

# Find nearest POIs to a point (e.g., Berlin)
berlin_point = Point(13.4050, 52.5200)
nearest_pois = poiidx.get_nearest_pois(
    berlin_point,
    max_distance=1000,  # meters
    limit=5
)

for poi in nearest_pois:
    print(f"{poi['name']} - Region: {poi['region']}, Rank: {poi['rank']}")

# Get administrative hierarchy for a point
admin_hierarchy = poiidx.get_administrative_hierarchy(berlin_point)
for admin in admin_hierarchy:
    print(f"Level {admin['admin_level']}: {admin['name']}")

# Get administrative hierarchy as a formatted string
admin_str = poiidx.get_administrative_hierarchy_string(berlin_point)
print(admin_str)

# Get administrative hierarchy in a specific language (e.g., French)
admin_str_fr = poiidx.get_administrative_hierarchy_string(berlin_point, lang='fr')
print(admin_str_fr)

# Close the connection when done
poiidx.close()

License

poiidx is distributed under the terms of the MIT license.

Data Sources & Attribution

This project uses data from the following sources:

OpenStreetMap (via Geofabrik)

POI and administrative boundary data is sourced from OpenStreetMap, distributed via Geofabrik.

Wikidata

When country information is not available in OpenStreetMap data, it is supplemented using Wikidata.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

poiidx-0.0.9.tar.gz (40.7 kB view details)

Uploaded Aug 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

poiidx-0.0.9-py3-none-any.whl (25.4 kB view details)

Uploaded Aug 16, 2026 Python 3

File details

Details for the file poiidx-0.0.9.tar.gz.

File metadata

Download URL: poiidx-0.0.9.tar.gz
Upload date: Aug 16, 2026
Size: 40.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for poiidx-0.0.9.tar.gz
Algorithm	Hash digest
SHA256	`bc5e7fa9e3f0fe50f967f271998d542b784cdec940bc4563855f7e7593faf2fd`
MD5	`058505ad0b5cf32fbcc1cff0e6608ee0`
BLAKE2b-256	`7ff5e8b4d6497ee90cb02d92a6caaa613f7175e5cc5ec84ada67eabc7013ecf5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for poiidx-0.0.9.tar.gz:

Publisher: release.yml on bytehexe/poiidx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: poiidx-0.0.9.tar.gz
- Subject digest: bc5e7fa9e3f0fe50f967f271998d542b784cdec940bc4563855f7e7593faf2fd
- Sigstore transparency entry: 2486574227
- Sigstore integration time: Aug 16, 2026
Source repository:
- Permalink: bytehexe/poiidx@eb901714a008bbe57e2972a80e91f67c930c501b
- Branch / Tag: refs/tags/0.0.9
- Owner: https://github.com/bytehexe
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@eb901714a008bbe57e2972a80e91f67c930c501b
- Trigger Event: push