Residential Proxies API

The Residential Proxies product is configured per-request via the gateway username — there is no per-account “management” API for it. What this API gives you is a way to enumerate the geo selectors you can drop into the username (country, region, city, asn) so your tooling stays in sync with what’s actually available.

Note

For protocol-level usage, sticky sessions, strict matching, and the full flag list, see Products → Residential Proxies and Gateway & auth.

Authentication

All endpoints authenticate with an api_key query parameter. Generate a key in the panel under Account → API Keys.

?api_key=YOUR_API_KEY

List countries

GET https://shifter.io/api/v1/residential/geo/countries

Returns every country available for country-<iso2> targeting on the Residential Proxies gateway.

Parameter	In	Required	Description
api_key	query	yes	Your API key

Example:

curl "https://shifter.io/api/v1/residential/geo/countries?api_key=YOUR_API_KEY"

Response:

[
  { "code": "us", "name": "United States" },
  { "code": "de", "name": "Germany" },
  { "code": "gb", "name": "United Kingdom" },
  { "code": "fr", "name": "France" }
]

List regions

GET https://shifter.io/api/v1/residential/geo/regions

Returns the regions (states / provinces) available for region-<slug> targeting within a given country.

Parameter	In	Required	Description
api_key	query	yes	Your API key
country	query	yes	ISO 3166-1 alpha-2 country code, e.g. us

Example:

curl "https://shifter.io/api/v1/residential/geo/regions?country=us&api_key=YOUR_API_KEY"

Response:

[
  { "slug": "california", "name": "California" },
  { "slug": "new_york",   "name": "New York" },
  { "slug": "texas",      "name": "Texas" }
]

List cities

GET https://shifter.io/api/v1/residential/geo/cities

Returns the cities available for city-<slug> targeting within a country (and optionally a region).

Parameter	In	Required	Description
api_key	query	yes	Your API key
country	query	yes	ISO 3166-1 alpha-2 country code
region	query	no	Region slug to narrow results

Example:

curl "https://shifter.io/api/v1/residential/geo/cities?country=us&region=california&api_key=YOUR_API_KEY"

Response:

[
  { "slug": "los_angeles",    "name": "Los Angeles" },
  { "slug": "san_francisco",  "name": "San Francisco" },
  { "slug": "san_diego",      "name": "San Diego" }
]

List ASNs

GET https://shifter.io/api/v1/residential/geo/asns

Returns the ASNs available for asn-<num> targeting within a country.

Parameter	In	Required	Description
api_key	query	yes	Your API key
country	query	yes	ISO 3166-1 alpha-2 country code

Example:

curl "https://shifter.io/api/v1/residential/geo/asns?country=us&api_key=YOUR_API_KEY"

Response:

[
  { "asn": 7922, "name": "Comcast" },
  { "asn": 701,  "name": "Verizon" },
  { "asn": 22773, "name": "Cox Communications" }
]

See also

• Residential Proxies overview
• Geo-targeting — how to drop these selectors into the username
• Authentication — proxy auth vs. management API auth