git:20260719.1748a98 to git:20261008.73da74c

21 added, 4 removed. Audit A to A.

---

name: osm-nz

- description: "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, cafes, parks, shops, transport stops, museums, beaches — given coordinates or an address. No login or API key required. Read-only."

+ 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-07-19"

+ 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` — list available category filters

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

- - Some results may lack names or have incomplete tags — these are filtered out

+ - Nearby POIs without names are filtered out; raw tag queries retain unnamed objects