Targeting Options

Residential sub-users target locations through their proxy username (see Proxy Access). These endpoints give you the list of values that are valid there, so you can build your own country, state and city pickers without asking support for a list. All three are authenticated like every other reseller endpoint (x-reseller-key or your dashboard token). They are served from a cache that is refreshed daily from our upstream provider, make no gateway calls, and are safe to call as often as you like.

Everything at once

GET /reseller/targeting

The full tree: every country, with its states, the cities in each state, and its ASNs.

cURL

curl https://api.roundproxies.com/reseller/targeting \
  -H "x-reseller-key: $KEY"

200 OK

{
  "countries": [
    {
      "code": "de",
      "name": "Germany",
      "asns": {
        "isps": [{ "code": "3320", "name": "AS3320 Deutsche Telekom AG" }],
        "datacenters": [{ "code": "24940", "name": "AS24940 Hetzner Online GmbH" }]
      },
      "states": [
        {
          "code": "landberlin",
          "name": "Land Berlin",
          "cities": [{ "code": "berlin", "name": "Berlin" }]
        }
      ]
    }
  ]
}

Field	Description
`countries[].code` / `name`	The country. Use the name with spaces removed in the username, e.g. `country-Germany`
`countries[].states[].code`	The value to use for `state-…` in the username
`countries[].states[].cities[].code`	The value to use for `city-…` in the username
`countries[].asns.isps`	Consumer / access ISPs in that country, for `isp-…` targeting
`countries[].asns.datacenters`	Hosting and cloud networks, split out so you can hide them from customers who want genuinely residential exits

The payload is large (every city in every country), so fetch it once and cache it on your side rather than per request.

Countries only

GET /reseller/targeting/countries

Just the country codes and names — a cheap call for a first-level picker.

cURL

curl https://api.roundproxies.com/reseller/targeting/countries \
  -H "x-reseller-key: $KEY"

[
  { "code": "de", "name": "Germany" },
  { "code": "il", "name": "Israel" }
]

One country

GET /reseller/targeting/countries/:code

The states, cities and ASNs for a single country. Use this to lazy-load the next level of a picker.

cURL

curl https://api.roundproxies.com/reseller/targeting/countries/de \
  -H "x-reseller-key: $KEY"

Returns one entry in the same shape as the items in countries[] above. The code is matched case-insensitively (de and DE are the same country); unknown codes return 404.

Exporting a CSV

If you’d rather have a flat file, one jq line turns the full tree into a row per city:

cURL

curl -s https://api.roundproxies.com/reseller/targeting -H "x-reseller-key: $KEY" \
  | jq -r '
      ["country_code","country_name","state_code","state_name","city_code","city_name"],
      (.countries[] as $c | $c.states[] as $s | $s.cities[]
        | [$c.code, $c.name, $s.code, $s.name, .code, .name])
      | @csv' > locations.csv

Availability is not guaranteed for every city in the list — a very narrow target can have no exit node at that moment. Your customers see that as PX1002 (see Error Handling); drop the city first, then the state.

Getting Started

Residential Proxies

ISP Proxies

Datacenter Proxies

Reseller

Reseller API

Everything at once

GET /reseller/targeting

Countries only

GET /reseller/targeting/countries

One country

GET /reseller/targeting/countries/:code

Exporting a CSV

​Everything at once

​GET /reseller/targeting

​Countries only

​GET /reseller/targeting/countries

​One country

​GET /reseller/targeting/countries/:code

​Exporting a CSV

Everything at once

GET /reseller/targeting

Countries only

GET /reseller/targeting/countries

One country

GET /reseller/targeting/countries/:code

Exporting a CSV