API reference
Authentication, requests, responses, and limits for the geocoding API.
Use the REST API to geocode addresses, search for places, reverse geocode coordinates, and suggest addresses while a user types. Every operation is a GET request with query parameters, so you can try it from a browser address bar, curl, or any HTTP client.
| Setting | Value |
|---|---|
| Base URL | Your deployment's URL; for local development, http://localhost:8000 |
| Protocol | HTTPS in production |
| Authentication | API key in the apikey header |
| Requests | GET with URL query parameters |
| Responses | GeoJSON FeatureCollection |
| Specification | OpenAPI 3.1 |
New to the API? Start with the quickstart.
Client libraries
Server SDKs add typed results, country routing, and optional Google/HERE fallbacks.
Authentication
Include your key on every request:
apikey: YOUR_API_KEY
Get a Server API key from your deployment's account portal for backend access to all operations. For frontend autocomplete, create a Browser token with allowed origins. See authentication for key management and SDK setup. Keys are accepted only in the header, never in the URL.
Endpoints
| Method | Path | Use |
|---|---|---|
GET | /v1/geocode | Find coordinates for a structured street address |
GET | /v1/search | Free-text search for addresses and places |
GET | /v1/reverse | Find addresses and places near coordinates |
GET | /v1/autocomplete | Suggest results while a user types |
GET | /v1/place | Look up one or more results by id |
curl "$GEOCODING_BASE_URL/v1/geocode?street=11%20Wall%20Street&city=New%20York&state=NY" \
--header "apikey: $GEOCODING_API_KEY"
Common parameters
| Parameter | Endpoints | Format |
|---|---|---|
limit | All except place | Whole number from 1 to 40; default 10 |
country | search, autocomplete, geocode | 2- or 3-letter country code, e.g. US |
near | search, autocomplete | lat,lon to prefer nearby results, e.g. near=34.05,-118.24 |
bbox | search, autocomplete | minLon,minLat,maxLon,maxLat to restrict results to a box |
types | search, autocomplete, reverse | Comma-separated result types, e.g. types=address,venue |
exclude_sources | All except place | Comma-separated data sources to omit |
Parameter names are case-sensitive. Unknown or repeated parameters return 400 with a message that names the allowed parameters, so typos fail loudly instead of being ignored. Values are trimmed and limited to 256 bytes.
Response format
Successful requests return HTTP 200 and a GeoJSON FeatureCollection. Each feature's properties use familiar US address names that match the request parameters:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [-74.0113, 40.7074]},
"properties": {
"id": "openaddresses:address:us/ny:1",
"label": "11 Wall Street, New York, NY, USA",
"type": "address",
"name": "11 Wall Street",
"house_number": "11",
"street": "Wall Street",
"unit": null,
"neighborhood": "Financial District",
"city": "New York",
"county": "New York County",
"state": "NY",
"state_name": "New York",
"zip": "10005",
"country": "US",
"lat": 40.7074,
"lon": -74.0113,
"confidence": 0.99,
"match_type": "exact",
"distance_m": null,
"categories": [],
"source": "openaddresses"
}
}
],
"bbox": [-74.0113, 40.7074, -74.0113, 40.7074]
}
No matches returns HTTP 200 with an empty features array. GeoJSON coordinates are [lon, lat]; properties.lat and properties.lon repeat them for convenience. See response fields and confidence scores before choosing an acceptance threshold.
Limits
| Limit | Value |
|---|---|
| Parameter value | 256 bytes after trimming |
limit | 1–40; default 10 |
place ids per request | 20 |
exclude_sources | 32 names; 1–64 bytes each |
reverse radius | 1–100,000 meters; default 1,000 |
Account rate limits apply to every request. See errors and limits.
Errors
Errors return an HTTP error status and a JSON message:
{"error":"Unknown parameter 'text'; use 'q'."}
Some errors, such as authentication and rate-limit failures, use message instead of error. Check the HTTP status before parsing the body. SDKs expose provider errors and attempt histories through GeocodingError.
Usage
Successful responses include X-Geocoding-Outcome: matched or no_match. These drive separate usage meters. Invalid requests and service failures are not billed.
See usage and billing for primary and backup calls.
Public browser tokens
Use the browser autocomplete client in any frontend library. Workspace admins create pub_ tokens with 1–20 exact allowed origins in the account portal. They work only on GET /v1/autocomplete and GET /v1/place, and require an allowed Origin plus the token in the apikey header. Missing or unlisted origins and other operations return HTTP 403. CORS preflight requests do not need credentials. Bare domains mean HTTPS; list each subdomain and development port separately. No wildcard domains are accepted.
Tokens are public and requests still count toward your rate limits and billing. Non-browser callers can forge Origin headers, so domain restrictions do not make tokens secret. Keep backend and third-party credentials on the server.