Dashboard

Locations API

Look up the geo-targeting options available for your proxies — countries, regions, cities, ISPs, and ZIP codes. These are the same dropdown feeds the dashboard uses when you build a proxy: query them to discover the code values you then pass to the location tokens of a proxy descriptor.

Every list returns a resource collection: { "data": [ ... ], "meta": { "has_more": bool } }. This is not the standard {success, payload, ...} envelope used by the resource controllers elsewhere in the API — read data directly and page with meta.has_more.
A "Random" option with code: "any" is always prepended as the first item of every list. Passing any to a proxy location token tells the network to pick that level automatically. The country ru is omitted from all responses unless your account is explicitly permitted to use it.

Common Query Parameters

All five endpoints accept the same query parameters (validated by a single shared request). Codes are matched exactly; name is a case-insensitive partial match. Filters that don't apply to a given endpoint are simply ignored, so you can reuse one parameter builder across all of them.

Shared Query Parameters
Name Type Required Description
connection_typestringOptionalProxy network type, max 64 chars. Defaults to residential. Scoping filters (country/region/city) are resolved within this connection type.
country__codestringOptionalScope results to this country code, max 64 chars. Applies to regions, cities, isps, and zipcodes. If the country is unknown, only the "Random" row is returned.
region__codestringOptionalScope results to this region code, max 64 chars. Applies to cities, isps, and zipcodes.
city__codestringOptionalScope results to this city code, max 64 chars. Applies to isps and zipcodes.
codestringOptionalExact-match filter on the item's own code, max 64 chars.
zipstringOptionalExact-match alias for code, max 64 chars. Only meaningful on the zipcodes endpoint.
namestringOptionalCase-insensitive partial (ILIKE) match on the item's name, max 255 chars.
availabilitystringOptionalExact-match filter on the availability field, max 64 chars.
limitintegerOptionalPage size, 1–500. Defaults to 100.
offsetintegerOptionalNumber of items to skip for pagination, ≥ 0. Defaults to 0.
Each item has the shape { code, name, availability, connection_type }. Items from the cities endpoint additionally carry a region_code field. The "Random" row always reports availability and connection_type as null.

List Countries

GET /v1/locations/countries Requires Auth

List Countries

List Countries

Retrieve the countries available for the given connection type. The "Random" row (code "any") is always first; the country "ru" is excluded unless your account is permitted to use it.

We filled these in for you: connection_type limit

Tweak any value if you like — or just press Try.

Query Parameters
Name Type Required Description
connection_type string Optional Proxy network type, max 64. Defaults to "residential".
code string Optional Exact-match filter on country code (max 64).
name string Optional Case-insensitive partial match on name (max 255).
availability string Optional Exact-match filter on availability (max 64).
limit integer Optional Page size, 1-500. Default 100.
offset integer Optional Items to skip, >= 0. Default 0. 
curl "https://api.proxyhat.com/v1/locations/countries?connection_type=residential&limit=100" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
import requests

response = requests.get(
    "https://api.proxyhat.com/v1/locations/countries",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    params={
        "connection_type": "residential",
        "limit": 100,
    },
)

body = response.json()
for loc in body["data"]:
    print(f"{loc[\"code\"]}: {loc[\"name\"]}")
print("has_more:", body["meta"]["has_more"])
const params = new URLSearchParams({
  connection_type: "residential",
  limit: "100",
});

const response = await fetch(`https://api.proxyhat.com/v1/locations/countries?${params}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const body = await response.json();
body.data.forEach(loc => console.log(`${loc.code}: ${loc.name}`));
console.log("has_more:", body.meta.has_more);
req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/locations/countries?connection_type=residential&limit=100", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var body struct {
    Data []map[string]interface{} `json:"data"`
    Meta struct {
        HasMore bool `json:"has_more"`
    } `json:"meta"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, loc := range body.Data {
    fmt.Printf("%v: %v\n", loc["code"], loc["name"])
}
fmt.Println("has_more:", body.Meta.HasMore)

List Regions

GET /v1/locations/regions Requires Auth

List Regions

List Regions

Retrieve the regions (states/provinces) within a country. Pass country__code to scope the list; if the country is excluded or unknown, only the "Random" row is returned.

We filled these in for you: country__code connection_type limit

Tweak any value if you like — or just press Try.

Query Parameters
Name Type Required Description
country__code string Optional Scope to this country code (max 64). Recommended.
connection_type string Optional Proxy network type, max 64. Defaults to "residential".
code string Optional Exact-match filter on region code (max 64).
name string Optional Case-insensitive partial match on name (max 255).
availability string Optional Exact-match filter on availability (max 64).
limit integer Optional Page size, 1-500. Default 100.
offset integer Optional Items to skip, >= 0. Default 0. 
curl "https://api.proxyhat.com/v1/locations/regions?country__code=us" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
import requests

response = requests.get(
    "https://api.proxyhat.com/v1/locations/regions",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    params={
        "country__code": "us",
    },
)

body = response.json()
for loc in body["data"]:
    print(f"{loc[\"code\"]}: {loc[\"name\"]}")
const params = new URLSearchParams({ country__code: "us" });

const response = await fetch(`https://api.proxyhat.com/v1/locations/regions?${params}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const body = await response.json();
body.data.forEach(loc => console.log(`${loc.code}: ${loc.name}`));
req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/locations/regions?country__code=us", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var body struct {
    Data []map[string]interface{} `json:"data"`
    Meta struct {
        HasMore bool `json:"has_more"`
    } `json:"meta"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, loc := range body.Data {
    fmt.Printf("%v: %v\n", loc["code"], loc["name"])
}

List Cities

GET /v1/locations/cities Requires Auth

List Cities

List Cities

Retrieve the cities within a country and/or region. City items additionally include a region_code field. Scope with country__code and/or region__code.

We filled these in for you: country__code connection_type limit

Tweak any value if you like — or just press Try.

Query Parameters
Name Type Required Description
country__code string Optional Scope to this country code (max 64).
region__code string Optional Scope to this region code (max 64).
connection_type string Optional Proxy network type, max 64. Defaults to "residential".
code string Optional Exact-match filter on city code (max 64).
name string Optional Case-insensitive partial match on name (max 255).
availability string Optional Exact-match filter on availability (max 64).
limit integer Optional Page size, 1-500. Default 100.
offset integer Optional Items to skip, >= 0. Default 0. 
curl "https://api.proxyhat.com/v1/locations/cities?country__code=us&region__code=california" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
import requests

response = requests.get(
    "https://api.proxyhat.com/v1/locations/cities",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    params={
        "country__code": "us",
        "region__code": "california",
    },
)

body = response.json()
for loc in body["data"]:
    print(f"{loc[\"code\"]}: {loc[\"name\"]} (region {loc.get(\"region_code\")})")
const params = new URLSearchParams({
  country__code: "us",
  region__code: "california",
});

const response = await fetch(`https://api.proxyhat.com/v1/locations/cities?${params}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const body = await response.json();
body.data.forEach(loc => console.log(`${loc.code}: ${loc.name} (region ${loc.region_code})`));
req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/locations/cities?country__code=us&region__code=california", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var body struct {
    Data []map[string]interface{} `json:"data"`
    Meta struct {
        HasMore bool `json:"has_more"`
    } `json:"meta"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, loc := range body.Data {
    fmt.Printf("%v: %v (region %v)\n", loc["code"], loc["name"], loc["region_code"])
}

List ISPs

GET /v1/locations/isps Requires Auth

List ISPs

List ISPs

Retrieve the ISPs (carriers) available within a country, region, and/or city. Scope with country__code, region__code, and/or city__code.

We filled these in for you: country__code connection_type limit

Tweak any value if you like — or just press Try.

Query Parameters
Name Type Required Description
country__code string Optional Scope to this country code (max 64).
region__code string Optional Scope to this region code (max 64).
city__code string Optional Scope to this city code (max 64).
connection_type string Optional Proxy network type, max 64. Defaults to "residential".
code string Optional Exact-match filter on ISP code (max 64).
name string Optional Case-insensitive partial match on name (max 255).
availability string Optional Exact-match filter on availability (max 64).
limit integer Optional Page size, 1-500. Default 100.
offset integer Optional Items to skip, >= 0. Default 0. 
curl "https://api.proxyhat.com/v1/locations/isps?country__code=us" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
import requests

response = requests.get(
    "https://api.proxyhat.com/v1/locations/isps",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    params={
        "country__code": "us",
    },
)

body = response.json()
for loc in body["data"]:
    print(f"{loc[\"code\"]}: {loc[\"name\"]}")
const params = new URLSearchParams({ country__code: "us" });

const response = await fetch(`https://api.proxyhat.com/v1/locations/isps?${params}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const body = await response.json();
body.data.forEach(loc => console.log(`${loc.code}: ${loc.name}`));
req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/locations/isps?country__code=us", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var body struct {
    Data []map[string]interface{} `json:"data"`
    Meta struct {
        HasMore bool `json:"has_more"`
    } `json:"meta"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, loc := range body.Data {
    fmt.Printf("%v: %v\n", loc["code"], loc["name"])
}

List ZIP Codes

GET /v1/locations/zipcodes Requires Auth

List ZIP Codes

List ZIP Codes

Retrieve the ZIP/postal codes available within a country, region, and/or city. The zip parameter is a convenient exact-match alias for code. ZIP items may reuse the code as their name.

We filled these in for you: country__code limit

Tweak any value if you like — or just press Try.

Query Parameters
Name Type Required Description
country__code string Optional Scope to this country code (max 64).
region__code string Optional Scope to this region code (max 64).
city__code string Optional Scope to this city code (max 64).
zip string Optional Exact-match filter on the ZIP code - alias for "code" (max 64).
connection_type string Optional Proxy network type, max 64. Defaults to "residential".
name string Optional Case-insensitive partial match on name (max 255).
availability string Optional Exact-match filter on availability (max 64).
limit integer Optional Page size, 1-500. Default 100.
offset integer Optional Items to skip, >= 0. Default 0. 
curl "https://api.proxyhat.com/v1/locations/zipcodes?country__code=us&city__code=losangeles" \
  -H "Authorization: Bearer __API_KEY__" \
  -H "Accept: application/json"
import requests

response = requests.get(
    "https://api.proxyhat.com/v1/locations/zipcodes",
    headers={
        "Authorization": "Bearer __API_KEY__",
        "Accept": "application/json",
    },
    params={
        "country__code": "us",
        "city__code": "losangeles",
    },
)

body = response.json()
for loc in body["data"]:
    print(f"{loc[\"code\"]}: {loc[\"name\"]}")
const params = new URLSearchParams({
  country__code: "us",
  city__code: "losangeles",
});

const response = await fetch(`https://api.proxyhat.com/v1/locations/zipcodes?${params}`, {
  headers: {
    "Authorization": "Bearer __API_KEY__",
    "Accept": "application/json",
  },
});

const body = await response.json();
body.data.forEach(loc => console.log(`${loc.code}: ${loc.name}`));
req, _ := http.NewRequest("GET", "https://api.proxyhat.com/v1/locations/zipcodes?country__code=us&city__code=losangeles", nil)
req.Header.Set("Authorization", "Bearer __API_KEY__")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var body struct {
    Data []map[string]interface{} `json:"data"`
    Meta struct {
        HasMore bool `json:"has_more"`
    } `json:"meta"`
}
json.NewDecoder(resp.Body).Decode(&body)
for _, loc := range body.Data {
    fmt.Printf("%v: %v\n", loc["code"], loc["name"])
}