# topoloop Quickstart

topoloop is a places search API built for AI agents: semantic + lexical search over ~49M
OpenStreetMap places, tuned on real agent traces. Your agent sends an approximate,
contextual place reference — `"the old lantern street"`, `"mount roy viewpoint"`,
`"清水寺"` — plus a coordinate from its own context, and gets back real, resolvable
places with stable IDs.

- **Base URL:** `https://api.topoloop.com`
- **Auth:** send your API key as the `X-API-Key` header on every request
- **Free tier:** 10,000 requests/month, 2 requests/second (burst 10) — [get a key](https://dash.topoloop.com/signup)
- **These docs are agent-readable:** every page is also served as plain Markdown — see
  [llms.txt](https://topoloop.com/llms.txt). Point your agent at it.

## 1. Get an API key

Sign up at [dash.topoloop.com/signup](https://dash.topoloop.com/signup) and create a key.
Keys look like `tl_live_…` and are shown once — store yours safely.

## 2. First search

Try a query shape that trips up conventional geocoders — a vernacular name, no exact
string match:

```bash
curl https://api.topoloop.com/places/search \
  -H "X-API-Key: $TOPOLOOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "the old lantern street", "lat": 25.11, "lng": 121.81, "limit": 3}'
```

```json
{
  "results": [
    {
      "osm_id": "6960525765",
      "osm_type": "node",
      "name": "九份老街",
      "name_en": "Jiufen Old Street",
      "category": "attraction",
      "lat": 25.109,
      "lng": 121.845,
      "distance_meters": 2410.5,
      "wikipedia": null,
      "wikidata": null
    }
  ],
  "count": 3,
  "radius_km": 15.0
}
```

Two things to notice:

- **`lat`/`lng` are required.** They bias the search to where your agent is working —
  taken from the agent's own context (the trip it's planning, the user's location), not
  from a second geocoding call. Use 3–4 decimal places of precision.
- **You didn't pass a radius.** The server picked one from local landmark density
  (`radius_km` in the response tells you what it used) — tight in dense cities, wide in
  wilderness. Only pass `radius` to override.

More queries to try: `"mount yari"` near `(36.34, 137.65)`, `"haifoss waterfall"` near
`(64.5, -19.7)`, `"清水寺"` near `(34.99, 135.78)`. Misspellings, translations, and
partial names all work — matching is semantic + lexical, not string equality.

## 3. Get details

Search responses are deliberately lean (they land in your agent's context window). Rich
fields live behind `/places/details`. Build the place ID by joining the first letter of
`osm_type` (uppercased) with `osm_id` — `node` + `6960525765` → `"N6960525765"`:

```bash
curl https://api.topoloop.com/places/details \
  -H "X-API-Key: $TOPOLOOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"osm_ids": ["N6960525765"]}'
```

The response is keyed by ID and only includes fields that exist for that place —
`website`, `phone`, `opening_hours`, `wikipedia`, `wikidata`, `cuisine`, and more. See
the [API reference](/docs/api-reference) for the full list.

## 4. Add web evidence

Places tell the agent *where*; the same key also searches a curated corpus of travel
blogs and trip reports for the *why* and *how* — which hut to book, whether the pass is
open in May, what a day in Chamonix actually looks like:

```bash
curl https://api.topoloop.com/web/search \
  -H "X-API-Key: $TOPOLOOP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best day hikes in the Dolomites", "limit": 3}'
```

Each result is a passage with its `url`, source `blog`, and a one-line `context`.
`POST /web/page` with one of those URLs returns the full article. Web calls share the
same rate limit and quota as places calls.

## 5. Wire it into an agent

The whole point. A places tool (plus an optional web-evidence tool) for your agent is a tool definition plus ~20 lines of
dispatch — and the details of that harness (the tool description, which fields you keep,
what the model sees) matter as much as the API. We ship battle-tested versions of both:

→ **[Building a places harness](/docs/building-a-harness)** — copy-paste tool
definitions for the Anthropic and OpenAI APIs, a complete runnable agent loop, and the
operational lessons (coordinate precision, radius handling, context budgeting) learned
from running this search engine behind a production travel agent.

## What you can do with the results

topoloop data is OpenStreetMap data, licensed under
[ODbL](https://www.openstreetmap.org/copyright). Unlike proprietary places APIs, you can
**cache results, store them in your own database, and train models on them** — with
attribution ("© OpenStreetMap contributors"). No display restrictions, no 30-day
deletion clocks.