API Reference

Locations API

The countries, states and cities you can target with residential proxies, the countries, regions, cities and carriers for mobile proxies, and the countries for datacenter proxies. It is the same list the dashboard generator shows, with the values to send to POST /api/v1/proxies/generate.

What the Catalog Contains

Residential: every country offered on the Light, Basic and Advanced plans. Light and Basic can also target a state or a city; Advanced targets the country only.
Each state has a value (what you send as state) and a targeting field. state means the generated line targets that state (its ISO 3166-2 code is in iso). country-fallback means the state is offered, but its lines target the whole country because the network has no state-level routing for it.
Each city has a value to send as city, for example los+angeles (spaces are written as +). A few values differ from the display name, for example Frankfurt is frankfurt+am+main.
Mobile: the countries, regions, cities and carriers the mobile network currently routes. This list comes live from the network, so it can change from day to day.
Datacenter: the countries the datacenter network offers, the same list as the datacenter page of the dashboard. Datacenter lines target a country only.

Authentication and Caching

The residential endpoints are public and need no key. Responses carry Cache-Control: public, max-age=3600, so you can cache them for an hour. The mobile and datacenter lookups need your API key in the X-API-Key header (or as Authorization: Bearer YOUR_API_KEY), the same as the rest of the API (Authentication). Base URL: https://api.zentislabs.com/api/v1.

List Residential Locations

GET/api/v1/locations

Every residential country with its plans, states and cities. cities on each country is a flat list of display names, kept for older integrations; use the states[].cities[].value entries for new code.

Parameters

plan query · string · optional: light, basic or advanced. Only countries on that plan. With advanced, states and cities are empty because Advanced targets the country only.

bash

curl "https://api.zentislabs.com/api/v1/locations"

# Only what the Basic plan can target
curl "https://api.zentislabs.com/api/v1/locations?plan=basic"

json

// Abridged: one country and one state shown
{
  "success": true,
  "product": "residential",
  "plan": null,
  "plans": {
    "light": { "name": "Residential Light", "product": "residential", "targeting": ["country", "state", "city"],
               "supports_state": true, "supports_city": true, "auth": "public", "types": ["countries", "states", "cities"] },
    "basic": { "name": "Residential Basic", "product": "residential", "targeting": ["country", "state", "city"],
               "supports_state": true, "supports_city": true, "auth": "public", "types": ["countries", "states", "cities"] },
    "advanced": { "name": "Residential Advanced", "product": "residential", "targeting": ["country"],
                  "supports_state": false, "supports_city": false, "auth": "public", "types": ["countries"] },
    "mobile": { "name": "Mobile", "product": "mobile", "targeting": ["country", "region", "city", "carrier"],
                "supports_state": true, "supports_city": true, "auth": "api_key", "types": ["countries", "regions", "cities", "isps"] },
    "datacenter": { "name": "Datacenter", "product": "datacenter", "targeting": ["country"],
                    "supports_state": false, "supports_city": false, "auth": "api_key", "types": ["countries"] }
  },
  "count": 222,
  "countries": [
    {
      "code": "US",
      "name": "United States",
      "cities": ["Los Angeles", "San Francisco", "San Diego"],
      "plans": ["light", "basic", "advanced"],
      "states": [
        {
          "name": "California",
          "value": "california",
          "targeting": "state",
          "iso": "ca",
          "cities": [
            { "name": "Los Angeles", "value": "los+angeles" },
            { "name": "San Francisco", "value": "san+francisco" }
          ]
        }
      ]
    }
  ]
}

plans lists what each plan can target: supports_state and supports_city, the types you can ask for below, and whether its lookups need an API key (auth).

Errors

400: plan is not light, basic, advanced, mobile or datacenter.
429: More than 3,000 requests in a minute from your IP address. Wait for Retry-After seconds.

Lists by Plan and Type

GET/api/v1/locations?plan=…&type=…

One flat list per call, for filling pickers step by step. The answer is {"success": true, "plan": ..., "type": ..., "data": [{"code": ..., "name": ...}]}; send code to POST /api/v1/proxies/generate. Residential lists are public; plan=mobile and plan=datacenter need your API key because they read the live catalog of that network.

Parameters

plan query · string · required: light, basic, advanced, mobile or datacenter.
type query · string · optional: Residential: countries, states, cities (Advanced: countries only). Mobile: countries (default), regions, cities, isps (carriers). Datacenter: countries (default).
country query · string · optional: Required for every type except countries. Residential: 2-letter code or English name. Mobile: 2-letter code.
state / region query · string · optional: Narrows cities to one state (residential: value, name or ISO code) or region (mobile), and isps to one region.
city query · string · optional: Mobile isps only: carriers in one city. Write + in a code as %2B in the URL.

bash

# Residential: states of the US, then the cities of one state
curl "https://api.zentislabs.com/api/v1/locations?plan=basic&type=states&country=us"
curl "https://api.zentislabs.com/api/v1/locations?plan=basic&type=cities&country=us&state=california"

# Mobile: carriers in Germany
curl "https://api.zentislabs.com/api/v1/locations?plan=mobile&type=isps&country=de" \
  -H "X-API-Key: YOUR_API_KEY"

# Datacenter: countries
curl "https://api.zentislabs.com/api/v1/locations?plan=datacenter&type=countries" \
  -H "X-API-Key: YOUR_API_KEY"

json

// type=states (abridged). targeting and iso as in the full catalog
{
  "success": true,
  "plan": "basic",
  "type": "states",
  "data": [
    { "code": "california", "name": "California", "targeting": "state", "iso": "ca" },
    { "code": "texas", "name": "Texas", "targeting": "state", "iso": "tx" }
  ]
}

// type=cities (abridged). state is the state the city belongs to
{
  "success": true,
  "plan": "basic",
  "type": "cities",
  "data": [
    { "code": "los+angeles", "name": "Los Angeles", "state": "california" },
    { "code": "san+francisco", "name": "San Francisco", "state": "california" }
  ]
}

// plan=datacenter&type=countries (abridged; the live list changes)
{
  "success": true,
  "plan": "datacenter",
  "type": "countries",
  "data": [
    { "code": "US", "name": "United States" },
    { "code": "DE", "name": "Germany" }
  ]
}

Errors

400: Invalid plan or type (the message lists the options), "country param required for states", "Unknown country 'xx'", "Unknown state 'x' for country 'us'", or states / cities asked for on Advanced or Datacenter (country only).
401: plan=mobile or plan=datacenter without a valid API key.
503: plan=mobile or plan=datacenter: that catalog could not be loaded right now. Retry in a minute.
429: More than 3,000 requests in a minute from your IP address. Wait for Retry-After seconds.

Error bodies carry the text in both error and message.

Get One Residential Country

GET/api/v1/locations/:country

The same entry as in the list, for one country. Useful to fill a state and city picker without loading the whole catalog.

Parameters

country path · string · required: 2-letter code (US, de) or English country name (United Kingdom).
plan query · string · optional: light, basic or advanced, as above.

bash

curl "https://api.zentislabs.com/api/v1/locations/DE"

json

// Abridged
{
  "success": true,
  "product": "residential",
  "plan": null,
  "country": {
    "code": "DE",
    "name": "Germany",
    "cities": ["Munich", "Nuremberg", "Frankfurt"],
    "plans": ["light", "basic", "advanced"],
    "states": [
      { "name": "Bayern", "value": "bayern", "targeting": "state", "iso": "by",
        "cities": [{ "name": "Munich", "value": "munich" }] },
      { "name": "Hessen", "value": "hessen", "targeting": "state", "iso": "he",
        "cities": [{ "name": "Frankfurt", "value": "frankfurt+am+main" }] }
    ]
  }
}

Errors

400: plan is not light, basic or advanced.
404: The country is not offered (on that plan).
429: More than 3,000 requests in a minute from your IP address. Wait for Retry-After seconds.

List Mobile Countries

GET/api/v1/locations/mobile

The countries offered for mobile proxies, the same list as the mobile page of the dashboard. Countries, cities, regions and carriers that did not route in our checks are left out.

No parameters. Needs an API key.

bash

curl "https://api.zentislabs.com/api/v1/locations/mobile" \
  -H "X-API-Key: YOUR_API_KEY"

json

// Abridged; codes are examples, the live list changes
{
  "success": true,
  "product": "mobile",
  "count": 2,
  "countries": [
    { "code": "US", "name": "United States" },
    { "code": "DE", "name": "Germany" }
  ]
}

Errors

503: The mobile catalog could not be loaded right now. Retry in a minute.
401: Missing or invalid API key, or the account is suspended.
429: More than 3,000 requests in a minute from this API key. Wait for Retry-After seconds.

Mobile Regions, Cities and Carriers

GET/api/v1/locations/mobile/:country

The regions, cities and carriers of one mobile country. Pass region to list only that region's cities and carriers, and city to list only that city's carriers.

Parameters

country path · string · required: 2-letter code from GET /locations/mobile.
region query · string · optional: A region code from this endpoint.
city query · string · optional: A city code from this endpoint. Write + as %2B in the URL.

bash

curl "https://api.zentislabs.com/api/v1/locations/mobile/US" \
  -H "X-API-Key: YOUR_API_KEY"

# Carriers in one city
curl "https://api.zentislabs.com/api/v1/locations/mobile/US?city=los%2Bangeles" \
  -H "X-API-Key: YOUR_API_KEY"

json

// Abridged; codes are examples, the live list changes
{
  "success": true,
  "product": "mobile",
  "country": { "code": "US", "name": "United States" },
  "filters": { "region": null, "city": null },
  "regions": [{ "code": "california", "name": "California" }],
  "cities": [{ "code": "los+angeles", "name": "Los Angeles" }],
  "carriers": [{ "code": "at&t+wireless", "name": "AT&T Wireless" }]
}

Errors

400: country is not a 2-letter code, or region / city is longer than 64 characters.
404: The country is not offered for mobile proxies.
503: The mobile catalog could not be loaded right now. Retry in a minute.
401: Missing or invalid API key, or the account is suspended.
429: More than 3,000 requests in a minute from this API key. Wait for Retry-After seconds.

Using the Values

Send the values unchanged to POST /api/v1/proxies/generate. For residential lines, state takes a state value (the state name or its iso code also work) and city a city value; a city takes precedence over a state. For mobile lines, send the codes as country, region, city and carrier; for datacenter lines, send the country code as country. The plan needs purchased bandwidth (Country & Geo-Targeting explains the line format).

bash

# Residential Basic, California
curl -X POST "https://api.zentislabs.com/api/v1/proxies/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "basic", "country": "US", "state": "california", "count": 5}'

# Residential Light, Frankfurt
curl -X POST "https://api.zentislabs.com/api/v1/proxies/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "light", "country": "DE", "city": "frankfurt+am+main", "count": 5}'

# Mobile, one carrier in one city
curl -X POST "https://api.zentislabs.com/api/v1/proxies/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "mobile", "country": "US", "city": "los+angeles", "carrier": "at&t+wireless", "count": 1}'

python

import requests

API = "https://api.zentislabs.com/api/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

# Every state of a country that the Basic plan can target at state level
country = requests.get(f"{API}/locations/US", params={"plan": "basic"}, timeout=30).json()["country"]
states = [s for s in country["states"] if s["targeting"] == "state"]
print(len(states), "states with state-level targeting")

# Five Basic lines for the first one
body = {"provider": "basic", "country": country["code"], "state": states[0]["value"], "count": 5}
r = requests.post(f"{API}/proxies/generate", json=body, headers=HEADERS, timeout=30)
r.raise_for_status()
for line in r.json()["proxies"]:
    host, port, user, password = line.split(":", 3)
    print(f"http://{user}:{password}@{host}:{port}")

Country & Geo-Targeting

How targeting is written into the proxy credentials.

Mobile Proxies

Gateway, sessions and carrier targeting for mobile lines.