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.md

GitHub

OSM 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

  1. Use nearby <lat> <lon> to find all POIs around a location with walking/driving times
  2. Filter by category with --category for targeted results
  3. Use --json for agent chaining, comparisons, or structured reports
  4. 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 coordinate
  • categories [--json] — list available category filters
  • query --bbox minLon,minLat,maxLon,maxLat --tag key=value [--tag key=value] [--limit N] [--format geojson] [--json] — raw tags, including unnamed objects
  • query --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