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.

1. Get an API key

Sign up at 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:

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}'

{
  "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":

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 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:

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.

What you can do with the results

topoloop data is OpenStreetMap data, licensed under ODbL. 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.