REST API
Geocoding
All geocoding endpoints are served from https://maps.guru/api/v1/geocoding. See the Geocoding base URL for details.
Search (Forward Geocoding)
Convert addresses or place names to coordinates.
GET https://maps.guru/api/v1/geocoding/search?text={query}&key={api_key}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Search query (address, place name, POI) |
size | number | No | Max results (default: 10, max: 40) |
layers | string | No | Filter by place type (e.g., venue, address, locality) |
sources | string | No | Filter by data source: osm, oa, gn, wof |
boundary.country | string | No | ISO 3166-1 alpha-2/alpha-3 country code filter |
lang | string | No | Response language (BCP 47, default: en) |
focus.point.lat | number | No | Focus latitude for proximity boosting |
focus.point.lon | number | No | Focus longitude for proximity boosting |
Example:
curl "https://maps.guru/api/v1/geocoding/search?text=Eiffel+Tower&size=1&key=mapx_your_key"
Reverse Geocoding
Convert coordinates to addresses.
GET https://maps.guru/api/v1/geocoding/reverse?point.lat={latitude}&point.lon={longitude}&key={api_key}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
point.lat | number | Yes | Latitude (-90 to 90) |
point.lon | number | Yes | Longitude (-180 to 180) |
size | number | No | Max results (default: 10, max: 40) |
layers | string | No | Filter by place type |
lang | string | No | Response language (BCP 47, default: en) |
Example:
curl "https://maps.guru/api/v1/geocoding/reverse?point.lat=48.8584&point.lon=2.2945&key=mapx_your_key"
Autocomplete
Get real-time type-ahead suggestions as users type.
GET https://maps.guru/api/v1/geocoding/autocomplete?text={partial}&key={api_key}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Partial search text |
focus.point.lat | number | No | Focus latitude for proximity boosting |
focus.point.lon | number | No | Focus longitude for proximity boosting |
size | number | No | Max results (default: 10, max: 40) |
layers | string | No | Filter by place type |
lang | string | No | Response language (BCP 47, default: en) |
Example:
curl "https://maps.guru/api/v1/geocoding/autocomplete?text=eiff&key=mapx_your_key"
Place Lookup
Fetch full details for one or more places by GID.
GET https://maps.guru/api/v1/geocoding/place?ids={gid1,gid2}&key={api_key}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
ids | string | Yes | Comma-separated GIDs (e.g., openstreetmap:venue:way/5013364) |
Example:
curl "https://maps.guru/api/v1/geocoding/place?ids=openstreetmap:venue:way/5013364&key=mapx_your_key"
Routing
Directions
Calculate routes between two or more points.
GET /v1/directions?origin={lat,lng}&destination={lat,lng}&key={api_key}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
origin | string | Yes | Start point (lat,lng) |
destination | string | Yes | End point (lat,lng) |
waypoints | string | No | Intermediate points (lat,lng|lat,lng) |
mode | string | No | Travel mode: driving, walking, cycling |
Isochrones
Calculate reachable areas from a point within a given time.
GET /v1/isochrone?center={lat,lng}&time={minutes}&key={api_key}
Map Styles
Get Style JSON
Retrieve a MapLibre-compatible style document.
GET /v1/styles/{slug}/style.json?key={api_key}
Returns a complete MapLibre GL style JSON with tile sources, sprites, and glyphs URLs pre-configured with your API key.
Usage
Current Usage
Get current month's usage statistics for your organization.
GET /v1/usage/current
Requires session authentication (not API key).