When to use this skill
When the user asks "where is X?" or wants to turn a place name, address, or landmark into coordinates and structured address data. Nominatim's /search endpoint disambiguates through country filters and viewport biasing — it solves the "which Springfield?" problem in a single call. For reverse geocoding (coordinates to place name), this is the wrong skill — use reverse-geocode-coordinates instead. For routing, elevation, or tile rendering, this is also the wrong API.
Your best first call
curl "https://nominatim.openstreetmap.org/search?q=Svalbard&format=jsonv2&addressdetails=1&limit=1"
No auth. No key. Returns a JSON array of matching places. The q parameter accepts free-form text — place names, addresses, landmarks. Use limit=1 for the best match; increase for disambiguation. Always pass format=jsonv2 — the older json format lacks category, type, addresstype, and name fields. Include addressdetails=1 to get the structured address object.
Key response fields:
lat, lon — coordinates as strings, not numbers — parse before arithmeticname — short place namedisplay_name — full address in the local language by defaultaddresstype — human-facing role (city, town, archipelago) — trust this over category/type, which describe OSM geometry, not what the place isaddress — structured object; keys vary by place (cities have city/state/postcode; territories like Svalbard collapse to just country/country_code)boundingbox — [south, north, west, east] as stringsimportance — 0–1 relevance score
Fallbacks (when the best call isn't enough)
- Disambiguation across countries → add
countrycodes=us or viewbox=left,top,right,bottom&bounded=1 to narrow to a region or viewport.
- Structured query when free-form text is ambiguous → replace
q= with street=...&city=...&state=...&country=... for precise address-level searches.
- Reverse geocoding →
/reverse?lat=...&lon=...&format=jsonv2&addressdetails=1 when the user has coordinates, not a name.
Pitfalls
lat and lon are strings ("77.5536042"), not floats. Parse explicitly before distance or bearing calculations./search with no q and no structured parameters returns the Nominatim HTML demo page, not an error. Always include a query.- Rate limit is 1 request per second unauthenticated. Pass
email=you@example.com for higher throughput; 429 responses are enforced.
- The
address object structure varies by place type — Svalbard has only country/country_code, while a town like Selfoss has town/county/state/postcode. Check which keys exist before accessing them.
One-line summary for the user
I can search for any place by name and return coordinates, address details, and bounding box from OpenStreetMap's Nominatim — unauthenticated, one call per second, local-language names by default.
SKILL.md source (frontmatter + body)
---
name: search-search
description: When the user asks "where is X?" or wants to geocode a place name, address, or landmark to coordinates and structured address data — reach for Nominatim's /search endpoint. Unauthenticated, one call per second.
---
## When to use this skill
When the user asks "where is X?" or wants to turn a place name, address, or landmark into coordinates and structured address data. Nominatim's `/search` endpoint disambiguates through country filters and viewport biasing — it solves the "which Springfield?" problem in a single call. For reverse geocoding (coordinates to place name), this is the wrong skill — use `reverse-geocode-coordinates` instead. For routing, elevation, or tile rendering, this is also the wrong API.
## Your best first call
```bash
curl "https://nominatim.openstreetmap.org/search?q=Svalbard&format=jsonv2&addressdetails=1&limit=1"
```
No auth. No key. Returns a JSON array of matching places. The `q` parameter accepts free-form text — place names, addresses, landmarks. Use `limit=1` for the best match; increase for disambiguation. Always pass `format=jsonv2` — the older `json` format lacks `category`, `type`, `addresstype`, and `name` fields. Include `addressdetails=1` to get the structured `address` object.
Key response fields:
- `lat`, `lon` — coordinates as **strings**, not numbers — parse before arithmetic
- `name` — short place name
- `display_name` — full address in the local language by default
- `addresstype` — human-facing role (`city`, `town`, `archipelago`) — trust this over `category`/`type`, which describe OSM geometry, not what the place *is*
- `address` — structured object; keys vary by place (cities have `city`/`state`/`postcode`; territories like Svalbard collapse to just `country`/`country_code`)
- `boundingbox` — `[south, north, west, east]` as strings
- `importance` — 0–1 relevance score
## Fallbacks (when the best call isn't enough)
- **Disambiguation across countries** → add `countrycodes=us` or `viewbox=left,top,right,bottom&bounded=1` to narrow to a region or viewport.
- **Structured query when free-form text is ambiguous** → replace `q=` with `street=...&city=...&state=...&country=...` for precise address-level searches.
- **Reverse geocoding** → `/reverse?lat=...&lon=...&format=jsonv2&addressdetails=1` when the user has coordinates, not a name.
## Pitfalls
- `lat` and `lon` are strings (`"77.5536042"`), not floats. Parse explicitly before distance or bearing calculations.
- `/search` with no `q` and no structured parameters returns the Nominatim HTML demo page, not an error. Always include a query.
- Rate limit is 1 request per second unauthenticated. Pass `email=you@example.com` for higher throughput; 429 responses are enforced.
- The `address` object structure varies by place type — Svalbard has only `country`/`country_code`, while a town like Selfoss has `town`/`county`/`state`/`postcode`. Check which keys exist before accessing them.
## One-line summary for the user
I can search for any place by name and return coordinates, address details, and bounding box from OpenStreetMap's Nominatim — unauthenticated, one call per second, local-language names by default.