Skip to main content

INFO

Geo-Targeting

Route requests through proxies in specific geographic locations.

The geo-targeting API allows you to route requests through proxies in specific geographic locations. You can target by country, state, and city with full hierarchy support.

Country

Specify a country using ISO 3166-1 alpha-2 codes (e.g., US, GB, DE, FR).

State

Specify a state/province using ISO 3166-2 subdivision codes (e.g., CA, TX, ON).

Requires: Country must be specified.

City

Specify a city name. City names are case-insensitive. For multi-word cities, use underscores to represent spaces (e.g., san_francisco, new_york_city).

Requires: Country must be specified. State is optional but recommended.

Full Geographic Hierarchy

Our API supports the full geographic hierarchy. You can specify:

  • Country only
  • Country + State
  • Country + City
  • Country + State + City (most precise)

When specifying a city without a state, the city must be unambiguous within the country. If the city exists in multiple states, you'll receive a 409 Conflict error listing the possible states.

Examples

# Using HTTP headers
curl -x http://USERNAME:PASSWORD@res.beta.globalbyte.io:10000 \
  -H "country: US" \
  https://httpbin.org/ip

# Using username suffix
curl -x http://USERNAME-country-US:PASSWORD@res.beta.globalbyte.io:10000 \
  https://httpbin.org/ip

Responses

Code: 200

Description: Successfully routed through the targeted location.

Code: 400

Description: Invalid targeting parameters (unknown country, state, or city).

Code: 409

Description: Ambiguous city - exists in multiple states. Specify the state to disambiguate.

{
  "origin": "172.59.208.148"
}