Sonic API endpoint
Completes a partial address, place, city, state or ZIP into ranked matches, each already carrying the latitude and longitude that GET /sonic/nearby takes -- so a caller can run a Sonic restaurant search from free text instead of coordinates. Each suggestion's layer describes its granularity and is one of `address`, `locality`, `state`, `postalCode` or `place`, and confidence is one of `exact`, `interpolated` or `fallback`. Results are restricted to one country (default US). A query that matches nothing returns an empty suggestions array with count 0, not an error.
/sonic/location-suggestQuery parameters:
query (required) — the partial address, place, city, state or ZIP to complete, e.g. cheyenne wy.limit (optional) — maximum suggestions, 1 to 25. Defaults to 5. Upstream may return fewer than requested.country (optional) — ISO 3166-1 alpha-2 country code to restrict results to, e.g. US. Defaults to US.A blank query, a limit outside 1-25, or a country that is not two letters returns 400.
Response includes query, country, limit, count, suggestions[], source_url, and fetched_at.
Each entry in suggestions[] has layer, formatted_address, label, number, street, city, county, state, state_code, postal_code, country, country_code, latitude, longitude, and confidence. Fields that do not apply to a match's granularity are omitted — a locality match has no number or street.
Matches without coordinates are omitted, since they cannot be used for a restaurant search.
| Field | Filled in, of 4 checked | Values in the sample |
|---|---|---|
| layer | 4 | place (3), locality (1) |
| formatted_address | 4 | |
| label | 1 | “Cheyenne” |
| city | 4 | Cheyenne in all 4 |
| county | 1 | “Laramie County” |
| state | 4 | Wyoming in all 4 |
| state_code | 4 | |
| country | 4 | United States in all 4 |
| country_code | 4 | |
| latitude | 4 | |
| longitude | 4 | |
| number | 3 | 1,851 to 8,422, median 3,715 |
| street | 3 | |
| postal_code | 3 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| query | string | Yes | Partial address, place, city, state or ZIP to complete | cheyenne wy | |
| limit | integer | No | 5 | Maximum suggestions, 1-25. Defaults to 5. Upstream may return fewer. | 5 |
| country | string | No | US | ISO 3166-1 alpha-2 country code to restrict results to. Defaults to US. | US |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/sonic/location-suggest?query=cheyenne+wy&limit=10&country=us" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "2540 dell range",
"country": "US",
"limit": 5,
"count": 1,
"suggestions": [
{
"layer": "address",
"formatted_address": "2540 Dell Range Blvd, Cheyenne, WY 82009 US",
"label": "2540 Dell Range Blvd",
"number": "2540",
"street": "Dell Range Blvd",
"city": "Cheyenne",
"county": "Laramie",
"state": "Wyoming",
"state_code": "WY",
"postal_code": "82009",
"country": "United States",
"country_code": "US",
"latitude": 41.160549,
"longitude": -104.777671,
"confidence": "exact"
}
],
"source_url": "https://api.radar.io/v1/search/autocomplete?...",
"fetched_at": "2026-09-05T12:00:00Z"
}
}Request schema
No body schema
Response schema
#/definitions/sonic.locationSuggestResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | Code is the HTTP status code or a custom code used to indicate the result of the request @example 200 | |||
| data | sonic.LocationSuggestResponse | No | ||||
| data.count | integer | No | 5 | |||
| data.country | string | No | US | |||
| data.fetched_at | string | No | ||||
| data.limit | integer | No | 5 | |||
| data.query | string | No | cheyenne wy | |||
| data.source_url | string | No | ||||
| data.suggestions | array | No | ||||
| data.suggestions[].city | string | No | Cheyenne | |||
| data.suggestions[].confidence | string | No | exact | Confidence is the geocoder's own match confidence: "exact", "interpolated", or "fallback". | ||
| data.suggestions[].country | string | No | United States | |||
| data.suggestions[].country_code | string | No | US | |||
| data.suggestions[].county | string | No | Laramie | |||
| data.suggestions[].formatted_address | string | No | 2540 Dell Range Blvd, Cheyenne, WY 82009 US | |||
| data.suggestions[].label | string | No | 2540 Dell Range Blvd | |||
| data.suggestions[].latitude | number | No | 41.160549 | |||
| data.suggestions[].layer | string | No | address | Layer is the match's granularity: "address", "locality", "state", "postalCode", or "place". | ||
| data.suggestions[].longitude | number | No | -104.777671 | |||
| data.suggestions[].number | string | No | 2540 | |||
| data.suggestions[].postal_code | string | No | 82009 | |||
| data.suggestions[].state | string | No | Wyoming | |||
| data.suggestions[].state_code | string | No | WY | |||
| data.suggestions[].street | string | No | Dell Range Blvd | |||
| msg | unknown | No | Msg is the message that describes the result of the request @example "Request successful" |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/sonic/location-suggest?query=cheyenne+wy&limit=10&country=us" \
-H "x-api-key: $CRAWLORA_API_KEY"