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

# Location Lookup API

> Resolve a city, state, country, or postal code to the exact value the search location filters accept, with contact counts. Free.

Location filters match a fixed vocabulary of about 170,000 cities and 727,000 postal codes. A misspelled place returns an empty result that looks like a market with no contacts. The Location Lookup API returns the exact spelling to send, and how many contacts sit behind each match.

> **Endpoint**
>
> `GET /search/locations`

> **Credits**
>
> Free

> **Results**
>
> Up to 100 per request, most contacts first

## Parameters

| Parameter | Description |
| - | - |
| `q` | Part of a place name, matched at the start of any word. `york` finds `New York`. Look up one place at a time. |
| `limit` | 1-100 results. |
| `types` | Restrict to `country`, `state-country`, `city-state-country`, or `postcode`. |

Which `type` goes with which filter:

| `type` | Send it in |
| - | - |
| `city-state-country` | `locations` |
| `state-country` | `contactState` / `companyState` |
| `country` | `contactCountry` / `companyCountry` |
| `postcode` | `contactZipCode` / `companyZipCode` |

## Example

```bash theme={null}
curl "https://api.seamless.ai/api/client/v1/search/locations?q=ontario&limit=5" \
  -H "Token: $SEAMLESS_API_KEY"
```

```json Response theme={null}
{
  "data": [
    { "location": "Ontario, Canada", "type": "state-country", "count": 3715492 },
    { "location": "Toronto, Ontario, Canada", "type": "city-state-country", "count": 1022929 },
    { "location": "Mississauga, Ontario, Canada", "type": "city-state-country", "count": 359140 },
    { "location": "Ottawa, Ontario, Canada", "type": "city-state-country", "count": 293005 },
    { "location": "Ontario, California, United States", "type": "city-state-country", "count": 153698 }
  ]
}
```

Use `count` to tell apart places that share a name: the Canadian province has about 3.7M contacts, and the California city about 154K. Send the `location` string exactly as returned, for example `"Austin, Texas, United States"`.

> [!TIP]
>
> You don't need a lookup for US state names and abbreviations, or for the country aliases `US`, `USA`, and `United States of America`.

## Related

* [Contact Search API](/api-catalog/contact-search)
* [API reference: Look up location filter values](/api-reference/v1/contact-search/look-up-location-filter-values)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.