osm-nz
Query OpenStreetMap Overpass API for nearby points of interest, attractions, amenities, shops, and services around any NZ location. Use when the task involves finding what's nearby — restaurants, cafe
SKILL.mdskills/osm-nz/SKILL.md
GitHubOSM NZ — OpenStreetMap Nearby Search
Goal
Query OpenStreetMap data for points of interest around a location using the public Overpass API, with a lightweight deterministic CLI.
Use this when
- A user asks "what's near me" or "what's around this area"
- A user wants to find nearby restaurants, cafes, parks, or shops
- A user needs a list of supermarkets, convenience stores, or food options in an area
- A user asks about attractions, museums, viewpoints, or historic sites nearby
- A user wants to know what transport options (bus stops, train stations, ferry terminals) are close
- A workflow needs structured, geocoded POI data
Do not use this for
- Real-time business hours, ratings, or reviews — OSM data is static and crowdsourced
- Driving directions or route planning — this only returns locations
- Guaranteed completeness — OSM coverage varies by area
- High-precision address geocoding — OSM tags are community-maintained
- Live public transport schedules — this only returns stop locations
Preferred workflow
- Use
nearby <lat> <lon>to find all POIs around a location with walking/driving times - Filter by category with
--categoryfor targeted results - Use
--jsonfor agent chaining, comparisons, or structured reports - Sort by distance (default) and scan the closest options first
CLI
Run with:
python3 skills/osm-nz/scripts/cli.py <command> [flags]
Commands
nearby <lat> <lon> [--radius N] [--category CAT] [--limit N] [--json]— POIs around a coordinatecategories [--json]— list available category filtersquery --bbox minLon,minLat,maxLon,maxLat --tag key=value [--tag key=value] [--limit N] [--format geojson] [--json]— raw tags, including unnamed objectsquery --area OVERPASS_AREA_ID --tag key=value [--json]— raw tags in a numeric Overpass area, restricted to NZ bounds
Raw tag queries combine repeated filters with AND. repair=* means the
key exists; other values are literal strings, not regular expressions. Results
retain all tags and OSM IDs for nodes, ways and relations. Bboxes are WGS84 and
limited to 1 degree wide/high; results are capped at 100 with a truncated flag.
GeoJSON uses points: ways and relations use bounding-box centres, which can lie
outside the requested bbox. It does not return fence lines or building outlines.
JSON includes source URL, publisher, ODbL licence, UTC retrieval time and the
Overpass base timestamp as latest_data. Calls time out after 10 seconds;
Overpass queries allow 8 seconds and responses are capped at 8 MiB.
Category filters
| Filter | What it covers |
|---|---|
food |
Restaurants, cafes, bars, pubs, fast food |
grocery |
Supermarkets, convenience stores, bakeries, butchers |
outdoors |
Parks, gardens, beaches, nature reserves |
culture |
Museums, galleries, theatres, libraries |
attractions |
Viewpoints, monuments, historic sites, zoos |
sports |
Sports centres, swimming pools, stadiums |
shopping |
Markets, malls, general retail |
transport |
Bus stops, train stations, ferry terminals |
worship |
Churches, mosques, temples, all places of worship |
If no --category is given, all categories are returned.
Examples:
python3 skills/osm-nz/scripts/cli.py nearby -36.8485 174.7633 --radius 2000
python3 skills/osm-nz/scripts/cli.py nearby -36.8485 174.7633 --category food --limit 10 --json
python3 skills/osm-nz/scripts/cli.py nearby -41.2865 174.7762 --category culture --radius 5000
python3 skills/osm-nz/scripts/cli.py categories
python3 skills/osm-nz/scripts/cli.py query --bbox 174.735,-36.905,174.745,-36.875 --tag barrier=fence --limit 5 --format geojson
python3 skills/osm-nz/scripts/cli.py query --bbox 174.72,-36.93,174.80,-36.84 --tag amenity=recycling --json
python3 skills/osm-nz/scripts/cli.py query --bbox 174.72,-36.93,174.80,-36.84 --tag 'repair=*' --json
python3 skills/osm-nz/scripts/cli.py query --bbox 174.72,-36.93,174.80,-36.84 --tag shop=second_hand --json
Resources
- CLI entrypoint:
scripts/cli.py - Smoke test:
scripts/smoke_test.py - API notes:
references/api-notes.md
Notes
- No API key, login, or account required — Overpass API is public and free
- Results are sorted by distance from the query point (closest first)
- Walking time estimated at 5 km/h; driving at 30 km/h (urban average)
- Travel mode is "walk" for places under 1.5 km, "drive" otherwise
- The Overpass API has a fair-use policy — avoid rapid repeated queries
- Coordinates are limited to New Zealand bounds and radius is capped at 10 km to protect the shared public API
- OSM data coverage varies: urban areas are well-mapped, rural areas less so
- Nearby POIs without names are filtered out; raw tag queries retain unnamed objects