> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lance.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete Locations

> Search and retrieve location suggestions for geographic filtering of leads and companies

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.

<Note>
  This endpoint proxies requests to the locations search API. Results are cached
  for 7 days to improve performance.
</Note>

## Request

<ParamField query="search" type="string">
  Search query to filter locations. Returns locations that match this text (city
  name, country name, or raw address).
</ParamField>

<ParamField query="size" type="integer" default="25">
  Number of results to return per page.
</ParamField>

<ParamField query="page" type="integer" default="0">
  Zero-based page number for pagination.
</ParamField>

## Response

Returns a paginated list of location items matching the search criteria.

<ResponseField name="content" type="LocationItem[]">
  Array of location items matching the query.

  <Expandable title="LocationItem properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the location.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the location (typically the city name).
    </ResponseField>

    <ResponseField name="countryName" type="string" required>
      Full name of the country (e.g., "United States", "Germany").
    </ResponseField>

    <ResponseField name="countryCode" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., "US", "DE").
    </ResponseField>

    <ResponseField name="stateName" type="string">
      Name of the state or region. Can be null for locations without state-level data.
    </ResponseField>

    <ResponseField name="stateCode" type="string">
      Abbreviated state or region code (e.g., "CA", "NY"). Can be null.
    </ResponseField>

    <ResponseField name="rawAddress" type="string" required>
      Full formatted address string for the location.
    </ResponseField>

    <ResponseField name="position" type="object">
      Geographic coordinates of the location. Can be null.

      <Expandable title="Position properties">
        <ResponseField name="lng" type="number" required>
          Longitude coordinate.
        </ResponseField>

        <ResponseField name="lat" type="number" required>
          Latitude coordinate.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalElements" type="integer">
  Total number of matching locations across all pages.
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items per page.
</ResponseField>

<ResponseField name="number" type="integer">
  Current page number (zero-based).
</ResponseField>

<ResponseField name="first" type="boolean">
  Whether this is the first page.
</ResponseField>

<ResponseField name="last" type="boolean">
  Whether this is the last page.
</ResponseField>

<ResponseField name="empty" type="boolean">
  Whether the result set is empty.
</ResponseField>

<ResponseField name="numberOfElements" type="integer">
  Number of elements in the current page.
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 - City search theme={null}
  {
    "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
  }
  ```

  ```json 200 - Country search theme={null}
  {
    "content": [
      {
        "id": "loc_berlin_001",
        "name": "Berlin",
        "countryName": "Germany",
        "countryCode": "DE",
        "stateName": "Berlin",
        "stateCode": "BE",
        "rawAddress": "Berlin, Germany",
        "position": {
          "lng": 13.405,
          "lat": 52.52
        }
      },
      {
        "id": "loc_munich_001",
        "name": "Munich",
        "countryName": "Germany",
        "countryCode": "DE",
        "stateName": "Bavaria",
        "stateCode": "BY",
        "rawAddress": "Munich, Bavaria, Germany",
        "position": {
          "lng": 11.582,
          "lat": 48.1351
        }
      }
    ],
    "totalElements": 89,
    "totalPages": 4,
    "size": 25,
    "number": 0,
    "first": true,
    "last": false,
    "empty": false,
    "numberOfElements": 25
  }
  ```

  ```json 200 - Empty results theme={null}
  {
    "content": [],
    "totalElements": 0,
    "totalPages": 0,
    "size": 25,
    "number": 0,
    "first": true,
    "last": true,
    "empty": true,
    "numberOfElements": 0
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Search for cities starting with "San"

```bash theme={null}
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

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

### Paginate through results

```bash theme={null}
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)

```bash theme={null}
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.