Skip to main content
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:
  1. Countries - get a country id (integer) and code (string)
  2. States - use code to get states for that country
  3. Cities - filter by country and optionally state
  4. 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
ParameterTypeRequiredDescription
searchstringNoFilter by country name (partial match)
Scope: geo:read 
curl https://api.2extract.com/v1/geo/countries \
  -H "X-API-Key: 2xt_YOUR_API_KEY"
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
ParameterTypeRequiredDescription
country_codestringYesISO country code, e.g. US
searchstringNoFilter by region name
Scope: geo:read 
curl "https://api.2extract.com/v1/geo/states?country_code=US" \
  -H "X-API-Key: 2xt_YOUR_API_KEY"
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
ParameterTypeRequiredDescription
country_codestringYesISO country code, e.g. US
regionstringNoRegion name to filter by, e.g. California
searchstringNoFilter by city name
Scope: geo:read 
curl "https://api.2extract.com/v1/geo/cities?country_code=US&region=California" \
  -H "X-API-Key: 2xt_YOUR_API_KEY"
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
ParameterTypeRequiredDescription
country_codestringYesISO country code, e.g. US
citystringYesCity name, e.g. Los Angeles
Scope: geo:read 
curl "https://api.2extract.com/v1/geo/zip?country_code=US&city=Los+Angeles" \
  -H "X-API-Key: 2xt_YOUR_API_KEY"
Example response 
{
  "result": true,
  "data": [
    { "zip": "90001" },
    { "zip": "90002" },
    { "zip": "90003" }
  ]
}