query-overpass-osm

name	query-overpass-osm
description	Query and analyze OpenStreetMap data through Overpass QL and the Python overpass package. Use when Codex needs to find OSM nodes, ways, relations, areas, nearby features, historical map state, tags, geometry, or OSM element IDs; build reproducible OSINT or geospatial searches; compare distance interpretations; or run Overpass without relying on a project virtual environment.

Query Overpass OSM

Use Overpass for targeted OpenStreetMap retrieval. Keep the query bounded, identify the client, and make spatial assumptions explicit before ranking results.

Define the Search

Write down these choices before querying:

1. Geographic scope: bounding box, administrative area, or explicit element.
2. OSM types: node, way, relation, or nwr.
3. Tags and values, including whether missing names are allowed.
4. Time: current OSM state or [date:"..."].
5. Distance semantics: representative point, geometry-to-geometry, or Overpass around.

For distance or "nearest/southernmost" tasks, read references/distance-semantics.md before deciding the answer.

Build the Query

Prefer a full Overpass QL document:

[out:json][timeout:60];
area
  ["boundary"="administrative"]
  ["admin_level"="4"]
  ["name"="青森県"]->.search_area;
nwr(area.search_area)["shop"="supermarket"];
out tags center geom;

Use nwr when the same real-world feature may be mapped as a point, building way, or relation. Restrict to way only when the requested answer explicitly requires a Way ID.

Read references/overpass-patterns.md for area selection, nearby queries, output modes, history, and performance.

Run Without a Project venv

Use the bundled PEP 723 command:

export OVERPASS_USER_AGENT='project-name/1.0 ([e-mail])'
scripts/overpass-query query.ql --output result.json

The script runs through uv, installs its pinned overpass dependency in a managed environment, and does not depend on the caller's .venv.

Pipe a query through stdin when no file is needed:

printf '%s\n' '[out:json];node(1);out;' |
  scripts/overpass-query - --output -

Use --validate-only to check the local input contract without making a network request.

Use the Python Package Directly

For repository code using overpass 0.8.x:

import overpass

api = overpass.API(
    user_agent="project-name/1.0 ([e-mail])",
    timeout=(10, 180),
)
result = api.get(full_query, build=False)

Always provide a meaningful User-Agent. In overpass 0.8.x, API and the build argument emit deprecation warnings because a 1.0 client API is planned, but 1.0 is not yet released. Pin 0.8.x code and re-check the package's official documentation before migrating to 1.0.

Validate Results

• Preserve type and id; IDs are only unique within an OSM element type.
• Link evidence as https://www.openstreetmap.org/{type}/{id}.
• Inspect tags and geometry, not only name.
• Report the exact distance definition used.
• Compare borderline candidates and retain enough output to reproduce ranking.
• Treat current OSM data as mutable; record the query time or use [date:] when the challenge has a known reference date.
• Run one deliberate query rather than repeatedly polling public instances.