osm-nz git:20261008.73da74cA

Immutable. This exact content never changes and is served at /api/v1/blob/e28fa0b1aa461a81.

---
name: osm-nz
description: "Query OpenStreetMap Overpass API for nearby points of interest, attractions, amenities, shops, and services around any NZ location, or raw OSM tags within a bbox or NZ area. Use when the task involves finding what's nearby — restaurants, cafes, parks, shops, transport stops, museums, beaches — given coordinates or an address. No login or API key required. Read-only."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "public-data"
  thecolab.source_owner: "OpenStreetMap contributors"
  thecolab.source_type: "community"
  thecolab.auth: "none"
  thecolab.access_mode: "public-api"
  thecolab.data_class: "public"
  thecolab.writes: "false"
  thecolab.browser: "false"
  thecolab.risk: "low"
  thecolab.cache_ttl: "24h"
  thecolab.schema_version: "1"
  thecolab.skill_type: "public-api"
  thecolab.pack: "nz-public-data"
  thecolab.source_url: "https://overpass-api.de/api/interpreter"
  thecolab.allowed_domains: "overpass-api.de,www.openstreetmap.org"
  thecolab.last_verified: "2026-10-08"
  thecolab.health: "healthy"
  thecolab.maintainer: "@adam91holt"
---

# 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:

```bash
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:

```bash
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