---
name: geosearch
description: Add UK place search (autocomplete, "near me", store finders, place text to coordinates) and a free UK vector map to an app using the geosearch API and maps.danhartropp.com tiles. Use when the user wants UK location search, a store or branch finder, a map, or to geocode UK place names.
---

# Adding geosearch to an app

Read the docs before writing code: https://geo.danhartropp.com/llms-full.txt

## What it does

- Searches UK places: settlements, streets, postcodes, rivers and canals, and points of interest. It tolerates typos and handles "thing in place" queries such as "pubs in n5".
- Returns postcodes, official areas and nearby places for any point.
- Comes with free vector maps of the UK.

## Setup

- Ask the user for their geosearch key. Keep it in config or an environment variable, never hard-coded in a public repo. For browser use, the key is visible to visitors; that's expected, and keys can be limited to the site's own origin (ask Dan).
- API base: `https://geosearch-tlm25zrwea-nw.a.run.app`. Send `X-API-Key` on every request.

## Patterns

- **Search box:** call `/suggest` as the user types (from 3 characters, debounced about 50 ms, cancelling the previous request). Call `/search` on Enter. Use the picked suggestion's `lat`/`lon` directly.
- **Choosing a result:** take the first `answer: true` result. If several `answer: true` results have the same name in different places, show "Did you mean…?" with them. Prefer place kinds (settlement, street) over a `poi` with the same name.
- **Near me:** pass `lat` and `lon` (browser geolocation or the map centre) with queries like "pubs" or "pharmacy". Queries that name a place ignore them. Show the response's `near` value so users know what was used.
- **Store finder:** geocode the user's text with `/search`, then sort the app's own branch list by straight-line distance in the client.
- **Pipelines:** batch with modest concurrency (about 4 at a time) and keep each row's `confidence`; send low-confidence or tied rows for review.
- **Map:** MapLibre GL JS with the Protomaps basemap; see https://geo.danhartropp.com/docs/maps.md. The site's origin must be on the tile allow-list.
- **Attribution:** show the response's `attribution` and "© OpenStreetMap contributors, Protomaps" with any map or results.

## Errors

Handle 401 (bad key), 403 (key not allowed from this origin), 429 (back off for `Retry-After` seconds) and 503 (retry once).