Look up location filter values
Search the location vocabulary for the exact values a location filter will match.
Location filters are matched against a fixed vocabulary of place names, spelled the way the underlying data spells them. A value outside that vocabulary matches no contacts, and because search returns 200 with an empty data array either way, a misspelling is indistinguishable from a genuinely empty market. This endpoint is how you tell the two apart: look a place up, then send the returned location string verbatim.
The vocabulary is too large to enumerate — roughly 170,000 cities and 727,000 postal codes — so there is no full list to download. Query it instead. Results are ordered by contact volume, so the first result is usually the place you meant.
US state names and abbreviations, and the country aliases US, USA and United States of America, are resolved by the location filters directly and need no lookup.
This endpoint consumes no search credits.
curl --request GET \
--url https://api.seamless.ai/api/client/v1/search/locations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.seamless.ai/api/client/v1/search/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.seamless.ai/api/client/v1/search/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.seamless.ai/api/client/v1/search/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.seamless.ai/api/client/v1/search/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.seamless.ai/api/client/v1/search/locations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.seamless.ai/api/client/v1/search/locations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"location": "Austin, Texas, United States",
"type": "city-state-country",
"count": 166378
}
]
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
- Authorization URL
- https://login.seamless.ai/oauth/authorize
- Token URL
- https://api.seamless.ai/api/client/v1/oauth/accessToken
Query Parameters
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.
"austin"
Maximum results to return, 1-100.
1 <= x <= 100Restrict 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.
city-state-country, state-country, city-country, country, postcode Response
Matching locations, most common first
Matching locations, ordered by contact volume. An empty array means the vocabulary holds nothing resembling the query.
Show child attributes
Show child attributes
Was this page helpful?
curl --request GET \
--url https://api.seamless.ai/api/client/v1/search/locations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.seamless.ai/api/client/v1/search/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.seamless.ai/api/client/v1/search/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.seamless.ai/api/client/v1/search/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.seamless.ai/api/client/v1/search/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.seamless.ai/api/client/v1/search/locations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.seamless.ai/api/client/v1/search/locations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"location": "Austin, Texas, United States",
"type": "city-state-country",
"count": 166378
}
]
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}