AlterLabAPI Reference
POST
Geocode Endpoint
Turn an informal address or landmark description into coordinate candidates. Every candidate carries its source and source URL, and confidence rises when independent sources agree.
Priced like one search query
A lookup is charged like one search query and refunded in full when no candidate is found. The MCP tool is
alterlab_geocode.Request
POST
/api/v1/geocodeResolve an informal address or landmark description to coordinates.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Informal address or landmark description, up to 300 characters. Distance hints such as 'a school 67 m away' are used for ranking. |
| near | object | Optional | Bias point {lat, lng}: closer candidates rank higher. |
| city | string | Optional | City or area name used to bias the search. |
| country | string | Optional | ISO 3166-1 alpha-2 country code. |
| max_results | integer | Optional | Maximum candidates, 1-10. Default 5. |
Response
JSON
{
"query": "Cafe Coffee Day, Indiranagar",
"candidates": [
{
"name": "Cafe Coffee Day",
"address": "100 Feet Road, Indiranagar, Bengaluru",
"lat": 12.9784,
"lng": 77.6408,
"confidence": 0.9,
"source": "openstreetmap",
"source_url": "https://www.openstreetmap.org/node/1"
}
],
"sources_tried": ["openstreetmap"],
"billing": { "charged_microcents": 1000, "refunded_microcents": 0, "billed_microcents": 1000 }
}Credits & Billing
The charge equals one search query. It is refunded when no candidate is found or every provider fails (503). Geocoding must be enabled on the deployment; otherwise the endpoint returns 503 geocode_not_enabled.
cURL Example
Bash
curl -X POST https://api.alterlab.io/api/v1/geocode \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "a school 67 m away, a university 272 m away", "city": "Bengaluru", "country": "in"}'