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

```bash
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:

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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](/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.

## Next

[Quickstart](/docs/quickstart) · [Authentication](/docs/authentication) · [x402 wire format](/docs/x402) · [API reference](/api-reference)