> ## 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 hundreds of thousands of cities and 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.

> [card] Endpoint
>
> `GET /search/locations`

> [card] Credits
>
> Free

> [card] Results
>
> Up to 100 per request, most contacts first

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `q` | string | Yes | A partial place name, matched at the start of any word — `york` finds `New York`. Search one place name at a time rather than a whole comma-separated tag. |
| `limit` | integer | No | Maximum results to return, 1-100. Default `10`. |
| `types` | string\[] | No | Restrict results to these tiers of the vocabulary. Repeat the parameter or pass a comma-separated list. Omit for all tiers. Use `state-country` or `country` to find a value for `contactState` / `companyState` or `contactCountry` / `companyCountry`, `city-state-country` for a free-form `locations` tag, and `postcode` for `contactZipCode` / `companyZipCode`. |

**Allowed values for `types`:** `city-state-country`, `state-country`, `city-country`, `country`, `postcode`

Which `type` goes with which filter:

| `type` | Send it in |
| - | - |
| `city-state-country` | `locations` |
| `city-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 far more contacts behind it than the California city. 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`.

For Python, JavaScript, and other languages, see [Look up location filter values](https://docs.seamless.ai/api-reference/v1/contact-search/look-up-location-filter-values.md) in the API reference.

## Related

* [Contact Search API](https://docs.seamless.ai/api-catalog/contact-search.md)
* [API reference: Look up location filter values](https://docs.seamless.ai/api-reference/v1/contact-search/look-up-location-filter-values.md)


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