Galon Cloud
Galon Cloud

Galon Geo

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

Markdown · API reference · OpenAPI

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

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.

MethodPathSummary
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.

StatusCodeWhennext_action
401api_key_missingNo key: Authorization: Bearer, or ?key= for a browser key.use_valid_api_key
403scope_missingThe key lacks the scope of this route.add_missing_scope
403secret_key_in_browserA secret key was sent from a web page: use a browser key.check_project_access
403secret_key_in_urlA secret key was put in a URL.check_project_access
403browser_key_origin_not_allowedThe page's site is not declared on the browser key.check_project_access
403browser_key_origin_requiredA browser key was used without an Origin header (not from a page).check_project_access
403browser_key_geo_onlyA browser key was used outside Geo.check_project_access
422geo_query_invalidA parameter out of range (field names it).fix_request
422geo_route_not_foundNo route between these points, or a point outside the routing coverage (field names it, routing_coverage lists the countries served).check_resource_id
422geo_coordinates_out_of_rangeLatitude outside -90..90 or longitude outside -180..180 (field names it); never geocoded.fix_request
422geo_coordinates_invalidCoordinates that cannot be read: write latitude, longitude; never geocoded.fix_request
422geo_address_not_foundThe address could not be found: make it more precise or give coordinates.check_resource_id
422geo_matrix_too_largeA matrix of more than 25 sources or 25 destinations.fix_request
422geo_matrix_too_farPoints too far apart for a matrix with this travel mode.fix_request
503geo_operation_unavailableThis operation is not available on the engine yet: nothing is counted.retry_later
429geo_rate_limitedToo many requests (retry after Retry-After).retry_after_delay
429browser_key_daily_cap_reachedThe browser key's daily cap is reached, or this request would exceed it (resets at 00:00 UTC).raise_limit_or_plan
429geo_monthly_cap_reachedThe monthly spending cap is reached.raise_limit_or_plan
402geo_balance_exhaustedThe prepaid balance is used up.top_up_balance
504geo_upstream_timeoutThe answer took too long: retry.retry_later
next_actionWhat to do
use_valid_api_keySend 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_scopeThis 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_accessThis project or key is not allowed to do this. Its owner must review the project, its key and its account in the console.
fix_requestThe 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_idNothing 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_laterTemporary 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_delayToo many requests. Wait the Retry-After delay (seconds), then retry with exponential backoff and the same Idempotency-Key.
raise_limit_or_planA 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_balanceThe 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.

LimitValue
Requests per minute and per key600
Map tiles, fonts and style per minute and per key3,000
Waypoints in a route25
Pairs in a distance matrix625
Pairs in a matrix before confirm: true is required (MCP)100
Minimum characters for autocomplete3

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.

ItemPriceUnit
geocode2.2 USDper 1,000 requests
route2.75 USDper 1,000 requests
tile0.33 USDper 1,000 requests
places3.3 USDper 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