Location & routing

Four geospatial primitives behind one API surface: turn a free-text address into coordinates, turn coordinates back into an address, search places and points of interest, and compute a route between two points. Backed by AWS Location Service; each call is priced flat and metered per lookup — no map-SDK contract, no monthly minimum.

curl -X POST https://api.relaystation.ai/v1/location/geocode \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: geocode-hq-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "1600 Amphitheatre Parkway, Mountain View, CA" }'

Or on the lodestone path — no account, a signed x402 payment instead of an API key:

curl -X POST https://api.relaystation.ai/v1/location/geocode \
  -H 'X-Payment: <base64 EIP-3009 authorization>' \
  -H 'Idempotency-Key: geocode-hq-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "1600 Amphitheatre Parkway, Mountain View, CA" }'

Every coordinate in this API is [longitude, latitude] (WGS-84) — longitude first, matching the GeoJSON / AWS Location convention.

geocode — address → coordinates

POST /v1/location/geocode resolves a free-text query (an address or place name) to candidate positions.

Field	Type	Notes
`query`	string, required	the address / place text (1–512 chars)
`maxResults`	integer	1–20 candidates
`language`	string	BCP-47 language tag for the returned labels
`biasPosition`	`[lon, lat]`	pull results toward this point
`countries`	string[]	restrict to ISO 3166 alpha-3 country codes (e.g. `["USA"]`)

Returns { results: [...] } — AWS Location result items, each with a Title, structured Address, and Position ([lon, lat]). An empty array means no match (not an error).

reverse-geocode — coordinates → address

POST /v1/location/reverse-geocode resolves a position ([lon, lat]) to the nearest address.

Field	Type	Notes
`position`	`[lon, lat]`, required	the point to resolve
`maxResults`	integer	1–20 candidates
`radiusMeters`	integer	search radius, 1–100000 m
`language`	string	label language

curl -X POST https://api.relaystation.ai/v1/location/reverse-geocode \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: rev-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "position": [-122.084, 37.4224] }'

Returns { results: [...] }; an empty array means nothing was nearby.

place-search — points of interest

POST /v1/location/place-search searches places and POIs by text.

Field	Type	Notes
`query`	string, required	the search text (1–512 chars)
`biasPosition`	`[lon, lat]`	bias toward this point
`maxResults`	integer	1–20 results
`language`	string	label language
`countries`	string[]	ISO 3166 alpha-3 restriction

curl -X POST https://api.relaystation.ai/v1/location/place-search \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: place-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "coffee near Union Square", "biasPosition": [-122.4074, 37.7881] }'

Returns { results: [...] }.

route — path between two points

POST /v1/location/route computes a route from an origin to a destination.

Field	Type	Notes
`origin`	`[lon, lat]`, required	start point
`destination`	`[lon, lat]`, required	end point
`travelMode`	enum	`Car` \| `Truck` \| `Pedestrian` \| `Scooter`
`departNow`	boolean	use live traffic for the departure

curl -X POST https://api.relaystation.ai/v1/location/route \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: route-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "origin": [-122.4074, 37.7881], "destination": [-122.084, 37.4224], "travelMode": "Car" }'

Returns the AWS Location route set — Routes[].Legs carrying distance, duration, and geometry.

Billing

Each op is a flat per-call charge: geocode and reverse-geocode bill per lookup; place-search bills per search; route bills per route. The charge stands whether the call returns matches or an empty result set — what you buy is the lookup. Reads have no free tier here (every op calls the upstream provider). Priced per call; see Pricing for the current rates, or send an unauthenticated POST to read the exact price from the 402 challenge. Every billable call needs an Idempotency-Key; a same-key retry returns the cached result without re-charging.

MCP tools

Callable over MCP at https://api.relaystation.ai/mcp: geocode, reverse_geocode, place_search, and route. Same auth, same prices as the HTTP routes.

Quickstart · Authentication · x402 wire format · API reference