Skip to main content
GET
/
api
/
v1
/
operations
/
autocomplete
/
locations
Autocomplete Locations
curl --request GET \
  --url https://api.example.com/api/v1/operations/autocomplete/locations \
  --header 'Authorization: Bearer <token>'
{
  "content": [
    {
      "id": "loc_sf_001",
      "name": "San Francisco",
      "countryName": "United States",
      "countryCode": "US",
      "stateName": "California",
      "stateCode": "CA",
      "rawAddress": "San Francisco, California, United States",
      "position": {
        "lng": -122.4194,
        "lat": 37.7749
      }
    },
    {
      "id": "loc_sj_001",
      "name": "San Jose",
      "countryName": "United States",
      "countryCode": "US",
      "stateName": "California",
      "stateCode": "CA",
      "rawAddress": "San Jose, California, United States",
      "position": {
        "lng": -121.8863,
        "lat": 37.3382
      }
    }
  ],
  "totalElements": 156,
  "totalPages": 7,
  "size": 25,
  "number": 0,
  "first": true,
  "last": false,
  "empty": false,
  "numberOfElements": 25
}
Provides autocomplete suggestions for location-based filters used in lead and company search. This endpoint powers the autocomplete functionality in location filter dropdowns, helping users discover valid geographic locations including cities, states, and countries.

​
Authentication

This endpoint requires authentication. The user must be signed in to access autocomplete data.
This endpoint proxies requests to the locations search API. Results are cached for 7 days to improve performance.

​
Request

​
search
string
Search query to filter locations. Returns locations that match this text (city name, country name, or raw address).
​
size
integer
default:"25"
Number of results to return per page.
​
page
integer
default:"0"
Zero-based page number for pagination.

​
Response

Returns a paginated list of location items matching the search criteria.
​
content
LocationItem[]
Array of location items matching the query.
​
totalElements
integer
Total number of matching locations across all pages.
​
totalPages
integer
Total number of pages available.
​
size
integer
Number of items per page.
​
number
integer
Current page number (zero-based).
​
first
boolean
Whether this is the first page.
​
last
boolean
Whether this is the last page.
​
empty
boolean
Whether the result set is empty.
​
numberOfElements
integer
Number of elements in the current page.

​
Response Examples

{
  "content": [
    {
      "id": "loc_sf_001",
      "name": "San Francisco",
      "countryName": "United States",
      "countryCode": "US",
      "stateName": "California",
      "stateCode": "CA",
      "rawAddress": "San Francisco, California, United States",
      "position": {
        "lng": -122.4194,
        "lat": 37.7749
      }
    },
    {
      "id": "loc_sj_001",
      "name": "San Jose",
      "countryName": "United States",
      "countryCode": "US",
      "stateName": "California",
      "stateCode": "CA",
      "rawAddress": "San Jose, California, United States",
      "position": {
        "lng": -121.8863,
        "lat": 37.3382
      }
    }
  ],
  "totalElements": 156,
  "totalPages": 7,
  "size": 25,
  "number": 0,
  "first": true,
  "last": false,
  "empty": false,
  "numberOfElements": 25
}

​
Usage Examples

​
Search for cities starting with “San”

curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/locations?search=San&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Search for locations in Germany

curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/locations?search=Germany" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Paginate through results

curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/locations?search=New&page=1&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get default locations (no search filter)

curl -X GET "https://api.lance.work/api/v1/operations/autocomplete/locations" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Notes

  • Results are cached for 7 days to improve performance. The cache is shared across all users.
  • Use the search parameter for type-ahead/autocomplete functionality - it filters results that match the search text against city names, country names, and raw addresses.
  • The position field contains geographic coordinates that can be used for map displays or distance calculations.
  • All parameters are optional. If no search is provided, the endpoint returns a default set of popular locations.