Catproxy Developer Documentation

See the Swagger UI for live request/response schemas and to try endpoints directly in your browser.

The geo endpoints return the IDs and codes you need to set geo-targeting on your proxies. The typical lookup flow is:

Countries - get a country id (integer) and code (string)
States - use code to get states for that country
Cities - filter by country and optionally state
ZIP codes - filter by country and city

Pass country id values in the countries array when creating or updating a proxy. Use code and extract_parameter values in proxy username parameters for connection-level geo-targeting.

Get countries

Returns all available countries with their numeric IDs and ISO codes.

GET /v1/geo/countries

Query parameters

Parameter	Type	Required	Description
`search`	string	No	Filter by country name (partial match)

Scope: geo:read

curl https://api.catproxy.io/v1/geo/countries \
  -H "X-API-Key: cat_YOUR_API_KEY"

curl "https://api.catproxy.io/v1/geo/countries?search=United" \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/geo/countries",
    headers={"X-API-Key": "cat_YOUR_API_KEY"}
)
print(r.json())

Example response

{
  "result": true,
  "data": [
    { "id": 84,  "code": "US", "name": "United States" },
    { "id": 225, "code": "RU", "name": "Russia" },
    { "id": 82,  "code": "GB", "name": "United Kingdom" }
  ]
}

Get states

Returns states or regions for a given country.

GET /v1/geo/states

Query parameters

Parameter	Type	Required	Description
`country_code`	string	Yes	ISO country code, e.g. `US`
`search`	string	No	Filter by region name

Scope: geo:read

curl "https://api.catproxy.io/v1/geo/states?country_code=US" \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/geo/states",
    headers={"X-API-Key": "cat_YOUR_API_KEY"},
    params={"country_code": "US"}
)
print(r.json())

Example response

{
  "result": true,
  "data": [
    {
      "id": 1,
      "code": 77,
      "name": "California",
      "extract_parameter": "california"
    }
  ]
}

Get cities

Returns cities for a given country, optionally filtered by state.

GET /v1/geo/cities

Query parameters

Parameter	Type	Required	Description
`country_code`	string	Yes	ISO country code, e.g. `US`
`region`	string	No	Region name to filter by, e.g. `California`
`search`	string	No	Filter by city name

Scope: geo:read

curl "https://api.catproxy.io/v1/geo/cities?country_code=US&region=California" \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/geo/cities",
    headers={"X-API-Key": "cat_YOUR_API_KEY"},
    params={"country_code": "US", "region": "California"}
)
print(r.json())

Example response

{
  "result": true,
  "data": [
    {
      "id": 32706,
      "name": "Los Angeles",
      "extract_parameter": "losangeles",
      "country_id": 84,
      "region_code": 443
    }
  ]
}

Get ZIP codes

Returns ZIP codes for a city within a country.

GET /v1/geo/zip

Query parameters

Parameter	Type	Required	Description
`country_code`	string	Yes	ISO country code, e.g. `US`
`city`	string	Yes	City name, e.g. `Los Angeles`

Scope: geo:read

curl "https://api.catproxy.io/v1/geo/zip?country_code=US&city=Los+Angeles" \
  -H "X-API-Key: cat_YOUR_API_KEY"

import requests

r = requests.get(
    "https://api.catproxy.io/v1/geo/zip",
    headers={"X-API-Key": "cat_YOUR_API_KEY"},
    params={"country_code": "US", "city": "Los Angeles"}
)
print(r.json())

Example response

{
  "result": true,
  "data": [
    { "zip": "90001" },
    { "zip": "90002" },
    { "zip": "90003" }
  ]
}

​Get countries

​Get states

​Get cities

​Get ZIP codes

Get countries

Get states

Get cities

Get ZIP codes