Geo autocomplete
The Geo autocomplete API looks up the countries, cities and regions a project location can track. Use it to find the geo_location_id you need to track a city or region rather than a whole country. These endpoints are not tied to a project.
Using the SE Visible API, you can:
- list the countries a project location can track
- search cities and regions inside a country by name
To track a city or region:
- Call List countries and find the entry whose
country_codematches the location you want to track. - Pass that entry’s
idascountry_idto Search cities and regions. - Send the
idof the suggestion you pick asgeo_location_id, together with the samecountry_code, when you add a location or update a location.
All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.
List countries
GET https://api.seranking.com/v1/se-visible/autocomplete/geo/countries
Returns the countries a project location can track, with English names. Find the entry whose country_code matches the project location and pass its id as country_id to Search cities and regions.
Note:
- If the upstream Geo Autocomplete service is unavailable, the request returns
502with the message “Geo Autocomplete service is unavailable.”
Request parameters
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| engine | String | No | N/A | AI engine type to return the country list for. One of chatgpt, google_gemini, google_ai_mode, google_ai_overview. Omit to return the unified Google country list. |
Request example
curl -X GET 'https://api.seranking.com/v1/se-visible/autocomplete/geo/countries' \
-H 'Authorization: Token YOUR_API_KEY'Response parameters
If successful, the server returns a JSON array of countries.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Country ID. Pass it as country_id to Search cities and regions. |
| name | String | Country name in English. |
| country_code | String | Country code in the same vocabulary as a project location’s country_code, for example UK. |
Response example
[
{
"id": 2826,
"name": "United Kingdom",
"country_code": "UK"
}
]Search cities and regions
GET https://api.seranking.com/v1/se-visible/autocomplete/geo/locations
Returns city and region suggestions inside a country that match a search query. Send the id of the suggestion you pick as geo_location_id when you add a location or update a location.
Note:
- Location names come back in English for any
langother thanen,de,es,fr,it,ja,nl,pt,ru,svanduk. - If
country_idis not a known country, the request returns400witherror_codeinvalid_country_id. - If the upstream Geo Autocomplete service is unavailable, the request returns
502with the message “Geo Autocomplete service is unavailable.”
Request parameters
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| query | String | Yes | N/A | Search text matched against city and region names. Maximum 255 characters. |
| country_id | Integer | Yes | N/A | Country id returned by List countries. Minimum 1. |
| lang | String | Yes | N/A | Language of the location names. Case-insensitive. One of en, fr, es, de, nl, it, ja, ko, hi, ar, pt, da, sv, nb, fi, ga, is, lb, zh, th, ms, id, tl, he, af, cs, el, tr, pl, ro, uk, ru, kk, uz, hu, et, lv, lt. |
| engine | String | No | N/A | AI engine type to search the location list for. One of chatgpt, google_gemini, google_ai_mode, google_ai_overview. Omit to search the Google location list. |
| limit | Integer | No | 10 | Maximum number of suggestions to return. Minimum 1, maximum 10. |
Request example
curl -X GET 'https://api.seranking.com/v1/se-visible/autocomplete/geo/locations?query=man&country_id=2826&lang=en&limit=10' \
-H 'Authorization: Token YOUR_API_KEY'Response parameters
If successful, the server returns a JSON array of city and region suggestions.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Geo location ID. Send it as geo_location_id when adding or updating a project location. |
| display_name | String | Name the project location reports as city. Can be the full name, equal to canonical_name. |
| canonical_name | String | Full name with the region and country, to tell apart places with the same name. |
Response example
[
{
"id": 42,
"display_name": "Manchester, England, United Kingdom",
"canonical_name": "Manchester, England, United Kingdom"
}
]
