# Galon Geo

> Geocoding, address autocomplete, reverse geocoding, places, routes, distance matrices, reachable areas and vector maps, with one API key.

## Before you start

- A Galon account, a project, a prepaid balance and a key with `geo:geocode`, `geo:route` and `geo:maps`. From a web page, use a browser key (`gln_pk_…`) instead of the secret key.

## Quickstart

Every example reads `GALON_API_BASE` (`https://api.galon.ai/v1`) and `GALON_API_KEY` from the environment and prints the HTTP status and the JSON body.

**1. Set your key.** Export the base URL and your key.

**curl**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."
```

**2. Find a place.** `q` (up to 200 characters, an address or GPS text such as `51.5074, -0.1278`), optional `limit` (1 to 20), `language`, `country`. The answer is a GeoJSON FeatureCollection with `attribution` and a `receipt`.

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/geo/geocode?q=Westminster%20London&limit=1" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/geocode?q=Westminster%20London&limit=1",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/geocode?q=Westminster%20London&limit=1`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "geocode_address", "arguments": {"q": "Westminster London", "limit": 1}}}' \
  -w '\n%{http_code}\n'
```

**3. Suggest addresses while the user types.** `GET /v1/geo/autocomplete?q=` after 3 characters and 300 ms without a keystroke; `limit` 1 to 10.

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/geo/autocomplete?q=Westminster%20Lon&limit=5" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/autocomplete?q=Westminster%20Lon&limit=5",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/autocomplete?q=Westminster%20Lon&limit=5`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "autocomplete_address", "arguments": {"q": "Westminster Lon", "limit": 5}}}' \
  -w '\n%{http_code}\n'
```

**4. Compute a route.** `profile`: `driving`, `walking`, `cycling` or `two_wheeler`; 2 to 25 `waypoints`, each a place: `[lon, lat]`, `{"lat", "lon"}`, GPS text or an address. The answer has `distance_m`, `duration_s`, the steps and the resolved places.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/geo/route" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "driving", "waypoints": [[-0.1278, 51.5074], "Camden, London"]}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/route",
    data=json.dumps({"profile": "driving", "waypoints": [[-0.1278, 51.5074], "Camden, London"]}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/route`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({profile: "driving", waypoints: [[-0.1278, 51.5074], "Camden, London"]}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_route", "arguments": {"profile": "driving", "waypoints": [[-0.1278, 51.5074], "Camden, London"]}}}' \
  -w '\n%{http_code}\n'
```

**5. Compare many places.** `POST /v1/geo/matrix`: 1 to 25 `sources`, 1 to 25 `destinations` (625 pairs at most), billed per pair. `null` in `durations_s` means no path.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/geo/matrix" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "two_wheeler", "sources": [[-0.1278, 51.5074]], "destinations": ["Camden, London", [-0.0754, 51.5055]]}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/matrix",
    data=json.dumps({"profile": "two_wheeler", "sources": [[-0.1278, 51.5074]], "destinations": ["Camden, London", [-0.0754, 51.5055]]}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/matrix`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({profile: "two_wheeler", sources: [[-0.1278, 51.5074]], destinations: ["Camden, London", [-0.0754, 51.5055]]}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_distance_matrix", "arguments": {"profile": "two_wheeler", "sources": [[-0.1278, 51.5074]], "destinations": ["Camden, London", [-0.0754, 51.5055]]}}}' \
  -w '\n%{http_code}\n'
```

**6. Show what is within reach.** `POST /v1/geo/isochrone`: a `center` and 1 to 4 `minutes` (1 to 60) or `meters` (100 to 50,000); polygons, smallest first.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/geo/isochrone" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "walking", "center": "51.5074, -0.1278", "minutes": [10, 20]}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/isochrone",
    data=json.dumps({"profile": "walking", "center": "51.5074, -0.1278", "minutes": [10, 20]}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/isochrone`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({profile: "walking", center: "51.5074, -0.1278", minutes: [10, 20]}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_isochrone", "arguments": {"profile": "walking", "center": "51.5074, -0.1278", "minutes": [10, 20]}}}' \
  -w '\n%{http_code}\n'
```

**7. Show a map.** `GET /v1/geo/styles/basemap` (`theme=light|dark`) returns a complete map style whose tile, font and icon URLs you load in your map. In a web page, call it with your browser key: `?key=gln_pk_…`, which the style carries into every URL.

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/geo/styles/basemap" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/geo/styles/basemap",
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/geo/styles/basemap`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

## Concepts

**Places.** Every place field (`waypoints`, `sources`, `destinations`, `center`) takes `[lon, lat]`, `{"lat", "lon"}`, GPS text (`51.5074, -0.1278`, `51.5074 N, 0.1278 W`, degrees-minutes-seconds) or an address. An address is geocoded first and billed as one geocode. Coordinates out of range are refused, never guessed.

**Browser keys.** A secret key stays on your server. In a web page, create a browser key in the console (Keys > New browser key): the sites allowed to use it (`example.com`, `*.example.com`, `localhost:3000`), its Geo scopes and a daily cap in billed units (10,000 by default; a matrix counts each pair, an address each geocode). It is public by nature: it works only from those sites, only for Geo, within its cap; a request that would exceed it is refused whole. A secret key sent from a page (with an `Origin` header) or in a URL is refused with `secret_key_in_browser` or `secret_key_in_url`.

**Receipts.** Each billed answer carries a `receipt` (`amount_micro_usd`, and `lines` when several classes are billed; `included_units` when part of the request is in the account's monthly included quantity, which is billed 0) and the `Galon-Receipt` header.

**Attribution.** Map data is © OpenStreetMap contributors (ODbL): show the `attribution` returned, linked to its `url`. It can be discreet, never absent. On a map, a compact ⓘ control is enough: shown when the map loads, it folds into the ⓘ once the map is moved, and a tap opens it again. With MapLibre: `map = new maplibregl.Map({container: 'map', style: styleUrl, attributionControl: false}); map.addControl(new maplibregl.AttributionControl({compact: true}), 'bottom-right');` (the basemap style already carries the attribution). Without a map (geocoding or routing results), a small line under the results, or a Credits or Providers page of your app that links to https://www.openstreetmap.org/copyright, is enough.

**Tiles.** Vector tiles (`application/vnd.mapbox-vector-tile`), zoom 0 to 15; an empty tile answers `204`.

## API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Geo you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, `$GALON_API_BASE`.

| Method | Path | Summary |
|---|---|---|
| GET | [`/v1/geo/geocode`](/cloud/docs/api/geo-geocode) | Geocode an address or GPS text |
| GET | [`/v1/geo/autocomplete`](/cloud/docs/api/geo-autocomplete) | Suggest addresses as the user types |
| GET | [`/v1/geo/reverse`](/cloud/docs/api/geo-reverse) | Find the address of a point |
| GET | [`/v1/geo/places/search`](/cloud/docs/api/geo-places-search) | Search places around a point |
| POST | [`/v1/geo/route`](/cloud/docs/api/geo-route) | Compute a route |
| POST | [`/v1/geo/matrix`](/cloud/docs/api/geo-matrix) | Compute a distance matrix |
| POST | [`/v1/geo/isochrone`](/cloud/docs/api/geo-isochrone) | Compute a reachable area |
| GET | [`/v1/geo/styles/basemap`](/cloud/docs/api/geo-styles-basemap) | Get the map style |
| GET | [`/v1/geo/tiles/{z}/{x}/{y}.mvt`](/cloud/docs/api/geo-tiles-z-x-y-mvt) | Get a vector tile |
| GET | [`/v1/geo/fonts/{fontstack}/{range}.pbf`](/cloud/docs/api/geo-fonts-fontstack-range-pbf) | Get map label glyphs |
| GET | [`/v1/geo/sprites/{file}`](/cloud/docs/api/geo-sprites-file) | Get map icons |
| GET | [`/v1/projects/{project_id}/keys/browser`](/cloud/docs/api/projects-project_id-keys-browser) | List the browser keys of a project |
| POST | [`/v1/projects/{project_id}/keys/browser`](/cloud/docs/api/projects-project_id-keys-browser) | Create a browser key |
| PATCH | [`/v1/projects/{project_id}/keys/browser/{key_id}`](/cloud/docs/api/projects-project_id-keys-browser-key_id) | Change a browser key |
| POST | [`/v1/projects/{project_id}/keys/browser/{key_id}/revoke`](/cloud/docs/api/projects-project_id-keys-browser-key_id-revoke) | Revoke a browser key |
| POST | [`/v1/projects/{project_id}/keys/browser/{key_id}/copy`](/cloud/docs/api/projects-project_id-keys-browser-key_id-copy) | Copy a browser key |

## Errors

Every error is JSON: `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is stable, `next_action.hint` says what to do next, and `console_url` is added when a person must act. The codes below are those this service returns.

| Status | Code | When | next_action |
|---|---|---|---|
| 401 | `api_key_missing` | No key: `Authorization: Bearer`, or `?key=` for a browser key. | `use_valid_api_key` |
| 403 | `scope_missing` | The key lacks the scope of this route. | `add_missing_scope` |
| 403 | `secret_key_in_browser` | A secret key was sent from a web page: use a browser key. | `check_project_access` |
| 403 | `secret_key_in_url` | A secret key was put in a URL. | `check_project_access` |
| 403 | `browser_key_origin_not_allowed` | The page's site is not declared on the browser key. | `check_project_access` |
| 403 | `browser_key_origin_required` | A browser key was used without an `Origin` header (not from a page). | `check_project_access` |
| 403 | `browser_key_geo_only` | A browser key was used outside Geo. | `check_project_access` |
| 422 | `geo_query_invalid` | A parameter out of range (`field` names it). | `fix_request` |
| 422 | `geo_route_not_found` | No route between these points, or a point outside the routing coverage (`field` names it, `routing_coverage` lists the countries served). | `check_resource_id` |
| 422 | `geo_coordinates_out_of_range` | Latitude outside -90..90 or longitude outside -180..180 (`field` names it); never geocoded. | `fix_request` |
| 422 | `geo_coordinates_invalid` | Coordinates that cannot be read: write `latitude, longitude`; never geocoded. | `fix_request` |
| 422 | `geo_address_not_found` | The address could not be found: make it more precise or give coordinates. | `check_resource_id` |
| 422 | `geo_matrix_too_large` | A matrix of more than 25 sources or 25 destinations. | `fix_request` |
| 422 | `geo_matrix_too_far` | Points too far apart for a matrix with this travel mode. | `fix_request` |
| 503 | `geo_operation_unavailable` | This operation is not available on the engine yet: nothing is counted. | `retry_later` |
| 429 | `geo_rate_limited` | Too many requests (retry after `Retry-After`). | `retry_after_delay` |
| 429 | `browser_key_daily_cap_reached` | The browser key's daily cap is reached, or this request would exceed it (resets at 00:00 UTC). | `raise_limit_or_plan` |
| 429 | `geo_monthly_cap_reached` | The monthly spending cap is reached. | `raise_limit_or_plan` |
| 402 | `geo_balance_exhausted` | The prepaid balance is used up. | `top_up_balance` |
| 504 | `geo_upstream_timeout` | The answer took too long: retry. | `retry_later` |

| next_action | What to do |
|---|---|
| `use_valid_api_key` | Send a valid Galon API key as 'Authorization: Bearer <key>'. If the key was revoked or has expired, create a new one in the console and retry with it. |
| `add_missing_scope` | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
| `check_project_access` | This project or key is not allowed to do this. Its owner must review the project, its key and its account in the console. |
| `fix_request` | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
| `check_resource_id` | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
| `retry_later` | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |
| `retry_after_delay` | Too many requests. Wait the Retry-After delay (seconds), then retry with exponential backoff and the same Idempotency-Key. |
| `raise_limit_or_plan` | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
| `top_up_balance` | The project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key. |

## Limits, free tier and pricing

Read from the platform code each time this page is served.

| Limit | Value |
|---|---|
| Requests per minute and per key | **600** |
| Map tiles, fonts and style per minute and per key | **3,000** |
| Waypoints in a route | **25** |
| Pairs in a distance matrix | **625** |
| Pairs in a matrix before confirm: true is required (MCP) | **100** |
| Minimum characters for autocomplete | **3** |

Usage prices, in US dollars, read from the price grid served by the platform each time this page is served. Paid from the prepaid balance.

| Item | Price | Unit |
|---|---|---|
| `geocode` | 2.2 USD | per 1,000 requests |
| `route` | 2.75 USD | per 1,000 requests |
| `tile` | 0.33 USD | per 1,000 requests |
| `places` | 3.3 USD | per 1,000 requests |

Included every month, per account: 10,000 geocodes, 10,000 routes and 50,000 map tiles, with a verified card on the Free plan and in every paid plan; beyond that, each request is billed at the public price from the prepaid balance.

Geo is paid per request from the prepaid balance; each answer's `receipt` gives the amount in US dollars. A matrix is billed per pair; an address given as a place is billed as one geocode.

Requests are measured, then settled to the prepaid balance at least daily, and as soon as 1 USD is due; each settlement is a line of your statement. Each project has a monthly cap, shown and adjustable on the console's Geo page, with an alert at 80 %; beyond it, requests answer 429 `geo_monthly_cap_reached` until the next month. An exhausted balance answers 402 `geo_balance_exhausted`: top up to continue.

## FAQ

**Which data?**

OpenStreetMap data, worldwide coverage depends on the data loaded on the server.

**Can I cache answers?**

Answers carry their own cache headers; respect them.

**Can I call Geo from a web page?**

Yes, with a browser key restricted to your sites; never with the secret key.

**Where are routes, matrices and reachable areas served?**

Geocoding and maps cover the world. Routes, matrices and reachable areas are served in the countries listed by `routing_coverage` (console overview and errors); a point outside gets 422 geo_route_not_found, and nothing is billed.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
