pp-pdok-location

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/developer-tools/pdok-location/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# PDOK Location — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `pdok-location-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install pdok-location --cli-only
   ```
2. Verify: `pdok-location-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/developer-tools/pdok-location/cmd/pdok-location-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

PDOK Location is the right CLI when an agent needs to work with Dutch addresses, parcels, roads, or administrative boundaries — including batch geocoding CSVs, looking up the gemeente containing a point, converting between RD and WGS84 coordinates, or pulling full GeoJSON features inside a bounding box. It is Netherlands-only (do not use for non-Dutch addresses) and free (no auth, no key).

### Why this CLI bundles two PDOK services

This binary wraps two upstreams — **Locatieserver** (`/bzk/locatieserver/search/v3_1`) and **Kadaster Location API** (`/kadaster/location-api/v1`) — because they are complementary, not redundant.

- **Locatieserver** (Solr-based) is the primary text-geocoding surface: free-text matches, suggest→lookup chains, reverse geocoding by lat/lon or RD, ranked Solr scores. Returns records with centroid coordinates only.
- **Kadaster Location API** (OGC API Features) is the secondary geometry surface: full GeoJSON, bbox filters, multi-CRS output (WGS84, RD/EPSG:28992, Web Mercator, ETRS89), 14 collections.

A common Dutch geo workflow uses both: geocode text on Locatieserver, then pull full geometry on the Location API. Each is incomplete without the other (Locatieserver lacks bbox and full geometries; Location API lacks Solr ranking and reverse geocoding), so bundling them under one binary, one config, and one local cache turns that workflow into a single tool. Run `pdok-location-pp-cli doctor --json` to see which of the two upstreams is reachable right now — the `sources.locatieserver` and `sources.kadaster_location_api` keys each report status + which commands are affected if the source is down.

## When Not to Use This CLI

- **Do not use for non-Dutch addresses.** PDOK only covers the Netherlands; passing a US, UK, German, Belgian, or other non-Dutch address returns either an empty result or a low-score false positive. Pick a different geocoder for those.
- **Do not use for mutating remote state.** This printed CLI exposes read-only commands only — no creating, updating, deleting, publishing, commenting, ordering, booking, or other state-changing operations.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Batch and bulk workflows
- **`batch geocode`** — Geocode an entire CSV of Dutch addresses in one command — outputs lat/lon, RD X/Y, match score, and an error column for failed rows.

  _When an agent needs to enrich a list of Dutch addresses, this is the one-shot command — no per-row scripting, with cached re-runs and a clear error column._

  ```bash
  pdok-location-pp-cli batch geocode incidents.csv --address-col street --out incidents-geocoded.csv
  ```
- **`features search`** — Search across multiple Location API OGC collections (adres, perceel, gebouw, ...) with an optional bounding-box filter, flattened to JSON or CSV.

  _When an agent needs a flat CSV of address+parcel matches inside a study area, this is the lightest path from a query to a multi-collection result set._

  ```bash
  pdok-location-pp-cli features search --query damrak --collections adres,perceel --bbox 4.85,52.36,4.92,52.40 --csv
  ```

### Geocoding workflows
- **`resolve`** — Type a partial address, get the canonical match with full GeoJSON geometry — the suggest→lookup chain collapsed into a single command.

  _When an agent needs to turn imprecise user text into a canonical address with geometry, this is the cheapest path._

  ```bash
  pdok-location-pp-cli resolve 'Damrak Amsterdam' --geojson
  ```
- **`nearest`** — From any lat/lon or RD coordinate, return the nearest address, nearest parcel, nearest hectometer marker, and the gemeente/provincie containing the point — all in one call.

  _Reverse-geocoding usually needs four separate API calls; this one returns the full picture in one shot, ideal for field-data enrichment pipelines._

  ```bash
  pdok-location-pp-cli nearest --lat 52.3731 --lon 4.8922 --json
  ```
- **`top`** — Return the single best match for a query if (and only if) the Solr score clears a threshold — exits non-zero when no match clears the bar.

  _When an agent needs a yes/no on whether an address is well-known, this is the predicate._

  ```bash
  pdok-location-pp-cli top 'Hertog Aalbrechtweg 5 1823DL Alkmaar' --min-score 5.0 --require-type adres --json
  ```

### Offline conversions
- **`convert rd-to-ll`** — Convert Dutch RD (EPSG:28992) coordinates to WGS84 lat/lon and back, with pure-math precision — no API call needed.

  _When an agent must reconcile Dutch RD coords with global WGS84, this is the local, deterministic path — no rate limit, no auth._

  ```bash
  pdok-location-pp-cli convert rd-to-ll 121200 488000 --json
  ```
- **`convert wkt-to-geojson`** — Take any WKT geometry (POINT, POLYGON, MULTIPOLYGON, MULTILINESTRING) and emit GeoJSON — or convert GeoJSON back to WKT.

  _When an agent needs to feed a PDOK response into mapping or analysis tooling expecting GeoJSON, this saves a parser._

  ```bash
  pdok-location-pp-cli convert wkt-to-geojson 'POINT(4.76 52.64)'
  ```

### Local state that compounds
- **`gemeente get`** — After a one-time sync, look up any of the 342 Dutch gemeenten or 12 provincies fully offline — name, centroid, codes, parent provincie.

  _For any agent workflow that asks 'which gemeente?' or 'list all gemeenten in this provincie', the answer is local and instant._

  ```bash
  pdok-location-pp-cli gemeente get amsterdam --json
  ```
- **`search`** — Full-text search across every address, gemeente, and lookup you've previously fetched — finds matches locally before falling back to the API.

  _When an agent repeats lookups on the same dataset, this short-circuits the API entirely once the cache is warm._

  ```bash
  pdok-location-pp-cli search 'amsterdam centraal' --json
  ```
- **`gemeente of-point`** — Given any lat/lon or RD coordinate, return which gemeente and provincie contain it — using the offline gazetteer with an API fallback.

  _For 'which municipality is this incident in' questions an agent asks repeatedly, this is the cached, offline-first answer._

  ```bash
  pdok-location-pp-cli gemeente of-point --lat 52.3731 --lon 4.8922 --json
  ```

### Service-specific identity
- **`perceel lookup`** — Look up a Dutch cadastral parcel by its full kadastrale aanduiding (e.g. 'AMR03 N 1234') and get back the GeoJSON parcel feature.

  _For cadastral investigations, this is the only command-line path from aanduiding text to a GeoJSON parcel._

  ```bash
  pdok-location-pp