API Documentation
Geo Service provides self-hosted forward and reverse geocoding, typeahead suggestions, turn-by-turn routing, travelling-salesperson stop optimization, distance/duration matrices, and background bulk lookups.
The service maintains strict drop-in compatibility with the Nominatim, Photon, and OSRM specifications. To migrate an existing application, simply point your client to this server's HTTPS base URL and provide a valid key.
Authentication & Keys
Every request to a protected endpoint requires an active key issued to your account. Keys are generated with cryptographically secure random bytes, displayed only once upon creation, and hashed using HMAC-SHA256 with a server secret.
Used by backend services, daemons, and microservices. Must be supplied exclusively in the Authorization: Bearer <key> header.
?key=sk_...) is explicitly forbidden and rejected with 401 Unauthorized to prevent keys from leaking into browser histories or proxy logs.
Used by client-side browser applications (e.g. search bars, autocomplete dropdowns). Can be sent in headers or as the ?key= query parameter.
/search, /reverse, /api, /status), exclusively from origins registered to your account, and operate under lower per-minute rate limits to protect your quota.
Endpoints Reference
All requests use HTTPS with allow-listed query parameters.
Service health and key verification check. Returns 200 OK with engine status. If a key is passed, validates its state.
Forward geocoding: resolves an address, street, or landmark into coordinates and administrative details.
| Parameter | Type | Description |
|---|---|---|
| q | string | Free-form address search query (e.g. 111 Wellesley St W, Toronto). Mutually exclusive with structured parameters. |
| street, city, state, postalcode | string | Structured query fields for targeted searches. |
| format | string | Must be jsonv2. |
| addressdetails | integer | 1 to include address breakdown (city, postal code, province, etc.), 0 otherwise. |
| limit | integer | Maximum results to return (1–40, default: 10). |
Reverse geocoding: identifies the closest civic address, street, or landmark corresponding to GPS coordinates.
| Parameter | Type | Description |
|---|---|---|
| lat, lon | float | Latitude and longitude in decimal degrees (e.g. lat=43.6629&lon=-79.3871). |
| format | string | Must be jsonv2. |
| zoom | integer | Level of detail (0–18). 18 targets building numbers, 16 streets, 10 cities. |
Fast autocomplete suggestions formatted as a GeoJSON FeatureCollection. Optimized for search input fields.
| Parameter | Type | Description |
|---|---|---|
| q | string | Search query prefix (e.g. Queen's P). |
| limit | integer | Number of suggestions (1–50, default: 15). |
| lat, lon | float | Coordinates to bias search results closer to the user. |
| lang | string | Language preference code (en or fr). |
Driving directions and routing geometry between coordinates. Format: {lon1},{lat1};{lon2},{lat2}[;{lonN},{latN}].
| Parameter | Type | Description |
|---|---|---|
| overview | string | full, simplified, or false. Controls route geometry resolution. |
| geometries | string | Must be geojson. |
| steps | boolean | Must be false. |
Solves the Traveling Salesperson Problem to compute the most efficient visit order for multiple stops.
| Parameter | Type | Description |
|---|---|---|
| source | string | Must be first (keeps start location fixed). |
| roundtrip | boolean | true to return to origin stop, false for one-way itinerary. |
| overview | string | full, simplified, or false. |
Computes distance and duration matrices between all provided coordinate pairs.
| Parameter | Type | Description |
|---|---|---|
| sources, destinations | string | all or semicolon-separated coordinate indices (e.g. 0;1;2). |
| annotations | string | duration, distance, or duration,distance. |
Submit up to your plan's maximum batch rows (e.g. 5,000) as a JSON array or single-column CSV. Files are encrypted with AES-256-GCM, processed in background workers, and permanently destroyed within 72 hours.
Limits, Rate Limiting & Errors
API responses adhere strictly to each engine's native error shapes to maintain 100% compatibility with standard client libraries:
{ "error": { "code": 401, "message": "..." } }
{ "message": "..." }
{ "code": "TooBig", "message": "..." }
Rate limit violations return 429 Too Many Requests with a Retry-After: <seconds> header. Exceeding route or table waypoint limits returns 400 Bad Request with OSRM code TooBig.
Required Open Data Attribution
In accordance with the Open Database Licence (ODbL) and Canadian open government licences, customers must credit OpenStreetMap and Statistics Canada wherever geocoding or routing results are displayed:
© OpenStreetMap contributors with a link to https://www.openstreetmap.org/copyright as required by the OSMF Geocoding Guideline.
Contains data from Statistics Canada's Open Database of Addresses (ODA), licensed under the Open Government Licence – Canada.