PlaceRoot

Ground AI agents in open map data.

PlaceRoot is an MCP server that answers spatial questions from Overture Maps — queried live with DuckDB, no API key, no signup, no vendor platform.

  • Answers, not data dumps. Every tool returns compact, ranked results that fit in an agent's context window (~2K tokens), never raw GeoJSON.
  • Fresh, rich place data. Operating status, confidence scores, and brands from Overture (contributed by Meta, Uber, TomTom, and others).
  • Zero setup. Queries run directly against Overture's public GeoParquet on S3 — no ETL, no database, no key.

Quick start

Add to Claude Desktop / Claude Code:

{
  "mcpServers": {
    "placeroot": {
      "command": "uvx",
      "args": ["placeroot"]
    }
  }
}

Or run it directly:

uv run placeroot          # stdio MCP server
uv run placeroot --http   # streamable-HTTP endpoint at http://127.0.0.1:8321/mcp

--http serves plain HTTP with no TLS or auth — put a reverse proxy in front for anything beyond local use.

Tools

Tool Answers
find_places Named places near a point, nearest first, with category, confidence, and operating status
summarize_area What's in an area: total places and top categories
place_details One place in full: addresses, contacts, brand, sources, confidence
admin_lookup The admin hierarchy containing a point: neighborhood up to country
compare_areas 2–5 areas side by side: category mix, density, and what differs most
within_distance Is the nearest matching place within N meters of a point?
geocode Free-text place name → ranked candidates with coordinates and admin context
resolve_place Free-text place reference → ranked, typed GERS ids an agent can hold onto
reverse_geocode Point → nearest address plus its containing division chain
summarize_buildings Building stock in an area: count, footprint area, height and use mix
buildings_at Nearest building footprints to a point
isochrone The area reachable within N minutes on foot, bike, or car — on PlaceRoot's own routing graph
render_map Any result → a self-contained interactive HTML map
simplify_geometry Any GeoJSON geometry → simplified to a token budget

More on the way — see ROADMAP.md.

Why

Agents are bad at maps. Existing map tools either require vendor API keys or return raw GeoJSON far too large for a context window. PlaceRoot's design rule: every answer fits in ~2K tokens, and anything bigger returns a summary plus a link.

A few things that make it work:

  • GERS ids everywhere. Every place carries its stable Overture GERS id, so an agent can hold onto a place across turns and look it up again with place_details(id=...) instead of re-searching.
  • Keyless geocoding. geocode/reverse_geocode are built entirely on Overture's divisions and addresses themes — deterministic matching, no third-party geocoding API. 100% hit@1 on a ~113-query real-world benchmark (scripts/geocode_benchmark.py).
  • Local caching. Hot data is cached on first use, so repeat queries answer in milliseconds and keep working offline. Set PLACEROOT_CACHE=off to always query upstream.
  • Self-hostable end to end. Optionally mirror the data to your own S3-compatible storage and point PlaceRoot at it — see docs/MIRROR.md.

Development

uv sync                    # installs pytest + ruff (dev dependency group)
uv run pytest              # offline tests against committed fixtures
uv run pytest -m live      # also run opt-in tests against real Overture S3
uv run ruff check .

License

MIT

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for chuofringer from gravatar.com chuofringer

Credits

Author: Vibe Mapper

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

ai-agents duckdb geospatial mcp openstreetmap overture-maps

Classifiers

Report project as malware

Download files

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

Source Distribution

placeroot-0.3.0.tar.gz (286.6 kB view details)

Uploaded Source

Built Distribution

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

placeroot-0.3.0-py3-none-any.whl (92.4 kB view details)

Uploaded Python 3

File details

Details for the file placeroot-0.3.0.tar.gz.

File metadata

  • Download URL: placeroot-0.3.0.tar.gz
  • Upload date:
  • Size: 286.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for placeroot-0.3.0.tar.gz
Algorithm Hash digest
SHA256 ff724d21b42c4cd1f3daaa355fcdebaa5383d69f2fbc73bfc8ae56ba8a6d6b40
MD5 1cc446affe25d5229f5f8e65221261c3
BLAKE2b-256 322ba389ef65eba2398b6cfd5dc91e446fb6e53e36004bd87d8805e282f5ca6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for placeroot-0.3.0.tar.gz:

Publisher: release.yml on chuofringer/placeroot

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

File details

Details for the file placeroot-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: placeroot-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 92.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for placeroot-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d64f0a86c0a4f43799da2e14f948bb9093b3f8ea7d818a277174c7be9ff2a447
MD5 ad0a5210edefaf6a6f978c4cd5470d35
BLAKE2b-256 f6c39a78eb097b61ec1267db9b65ba610641a554a6d1d2d066612f4277203966

See more details on using hashes here.

Provenance

The following attestation bundles were made for placeroot-0.3.0-py3-none-any.whl:

Publisher: release.yml on chuofringer/placeroot

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

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page