# Geoloods API — agent reference

> Gazetteer of named places (cities, towns, villages, parks, landmarks). JSON over HTTPS.

This file is the long-form companion to https://geoloods.io/llms.txt. Human HTML docs: https://geoloods.io/docs. OpenAPI: https://geoloods.io/openapi.json.

## Scope

Named places only. Search and reverse return gazetteer places (cities, towns, villages, parks, landmarks, admin areas). This is not street-level geocoding and not a venue index. Do not send street names, postal addresses, or café/hotel queries as first-class search — they may return nothing or an unrelated named place.

Hotels, hostels, cafés, and other venues are not first-class search. Use `GET /v2/nearby` for “what’s around”. Default reverse (`filter=smart`) prefers settlement and admin place labels and excludes HTL/RSRT/MALL. `filter=simple` is opt-in nearest gazetteer feature (may return a hotel).

## Base URL

https://api.geoloods.io/v2/

Health (no auth): `GET https://api.geoloods.io/health` → `{"alive":true}`

## Auth

Live forms (document these first):

1. Header: `X-API-Key: YOUR_API_KEY`
2. Query: `?api_key=YOUR_API_KEY`

Either form is enough. Both may be sent.

Humans: create a key at https://geoloods.io/auth (1,000 requests/month free on the published human plans — do not treat this file as a billing change).

Agents: `POST /v2/agent/signup` (no API key). Trial keys are `gl_agent_*`: 1,000 calls / 12 hours. Then create a human account at https://geoloods.io/auth for Free (1,000/mo), Pro, or Scale. Not free forever. Concrete mint flow: Agent signup.

Missing key (401):

```
{"error":"Missing API key. Provide via X-API-Key header or api_key query param."}
```

Invalid key (401):

```
{"error":"Invalid API key"}
```

## Rate-limit headers

Authenticated API responses include:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

Use those exact names. `X-RateLimit-Reset` is a unix timestamp (seconds).

## Search

`GET /v2/search?query=Oslo`

Required: `query` — named place (city, town, village, park, landmark). Best-effort name match. Partial names may help for well-known settlements; do not expect street names, addresses, or venue/café/hotel queries to resolve.

Optional: `lang` (e.g. `en`, `nl`) — name language.

Example:

```
curl "https://api.geoloods.io/v2/search?query=Oslo" \
  -H "X-API-Key: YOUR_API_KEY"
```

Live `/v2/search` returns a JSON array of location objects (not a wrapped `{results:[…]}` envelope). A location object includes fields such as:

```
{
  "Geonameid": 3143244,
  "Name": "Oslo",
  "Latitude": 59.91273,
  "Longitude": 10.74609,
  "_featureCode": "PPLC",
  "CountryCode": "NO",
  "CountryName": "Norway",
  "CountryFlag": "🇳🇴",
  "CurrencyCode": "NOK",
  "CurrencyName": "Norwegian Krone",
  "Admin1Name": "Oslo",
  "Admin2Name": "Oslo",
  "Population": 580000,
  "Elevation": 0,
  "Dem": 26,
  "Timezone": "Europe/Oslo",
  "ModificationDate": "2023-11-28"
}
```

Do not use `q=` against `api.geoloods.io`. The site playground proxy at `/api/playground/geocode?q=` is site-only.

## Reverse geocode

`GET /v2/geocode?lat=52.370216&lng=4.895168`

Required: `lat`, `lng`.

Default is `filter=smart`: settlement and admin place labels (city, town, village, admin area). HTL/RSRT/MALL are excluded.

Optional: `filter` (`smart` or `simple`), `results`, `lang`.

- `filter=smart` (default) — settlement-preferring; HTL/RSRT/MALL excluded.
- `filter=simple` — opt-in nearest gazetteer feature (may be a hotel).

Hotels and venues as a “what’s around” query belong on `GET /v2/nearby`.

```
curl "https://api.geoloods.io/v2/geocode?lat=52.370216&lng=4.895168" \
  -H "X-API-Key: YOUR_API_KEY"
```

Opt-in nearest feature:

```
curl "https://api.geoloods.io/v2/geocode?lat=52.370216&lng=4.895168&filter=simple" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Nearby

`GET /v2/nearby?lat=59.9139&lng=10.7522&radius_km=50`

Required: `lat`, `lng`. Optional: `radius_km` (default 10, range 0.1–100), `limit`, `lang`.

Named places within a radius, sorted by distance. Use this for “what’s around”, including hotels or other gazetteer venues when you want them.

## Bounding box

`GET /v2/bbox?min_lat=59.8&max_lat=60.0&min_lng=10.6&max_lng=10.9`

Required: `min_lat`, `max_lat`, `min_lng`, `max_lng`. Max 10° on a side. Optional: `limit`, `lang`.

## Countries

`GET /v2/countries`

Requires `X-API-Key` or `api_key`. Each country object includes `code` (ISO 3166-1 alpha-2), `name`, `iso3`, `iso_numeric`, `capital`, `area`, `population`, `continent`, `tld`, `currency_code`, `currency_name`.

## Agent signup

No browser. No email. No key required to mint.

`POST /v2/agent/signup`

POST https://api.geoloods.io/v2/agent/signup
Content-Type: application/json

Unauthenticated. Optional body fields `agent` (max 64) and `purpose` (max 200):

```
{"agent":"your-agent","purpose":"short intent"}
```

Empty body `{}` is fine.

201 example (`gl_agent_*` key plus expiry fields):

```
{
  "api_key": "gl_agent_…",
  "quota": 1000,
  "remaining": 1000,
  "expires_at": "2026-09-21T00:00:00.000Z",
  "ttl_seconds": 43200
}
```

Live 201 also includes those required fields. `docs` / `openapi` / `base_url` may be present as convenience links.

Then call search with the live auth forms: `X-API-Key: <api_key>` and/or `api_key` as a query parameter.

```
curl -sS -X POST https://api.geoloods.io/v2/agent/signup \
  -H 'Content-Type: application/json' -d '{}'

curl -sS 'https://api.geoloods.io/v2/search?query=Oslo' \
  -H "X-API-Key: gl_agent_…"
```

Errors:

- `400` — invalid JSON / field too long (`error`)
- `429` — signup rate limit, or an active agent key already exists for this client IP. Live body includes `error`, `retry_after_seconds`, and `expires_at` (secret is not re-revealed). Also sent as `Retry-After`.

429 example (no `api_key`):

```
{
  "error": "An active agent key already exists for this client",
  "expires_at": "2026-09-21T00:43:23.064Z",
  "retry_after_seconds": 42642
}
```

- `503` — capacity / temporarily unavailable (`error`)

One active agent key per client IP. Trial keys are `gl_agent_*`: 1,000 calls / 12 hours (`ttl_seconds` 43200). Not free forever — after expiry create a human account at https://geoloods.io/auth for Free (1,000/mo), Pro, or Scale.

## Coverage

Gazetteer of 6.5M+ named places, 195 countries. Cities, towns, villages, parks, landmarks — not a street, address, or venue index. Coordinates, timezone, population, and country metadata in the location object.

## Links

- Short index: https://geoloods.io/llms.txt
- OpenAPI: https://geoloods.io/openapi.json
- Human docs: https://geoloods.io/docs
- Playground: https://geoloods.io/playground
- Status: https://status.softwareloods.nl/798067685
- Support: support@geoloods.io