Before you start
- A Galon account, a project, a prepaid balance and a key with
geo:geocode,geo:routeandgeo: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
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
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)
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)
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)
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
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)
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)
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)
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
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)
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)
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)
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
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)
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)
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)
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
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)
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)
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)
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
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)
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)
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.