Skip to main content

​
Overview

Control the geographic location of your proxy IPs by adding targeting parameters to your connection string. Target by country, state (US only), or city for precise location control.

​
Targeting Levels

Country

Access IPs from any country worldwide

State

Target US states (US only)

City

Target specific cities

​
Country Targeting

Target a specific country by adding the country code to your connection string.

​
Format

account-{accountName}-pipeline-{pipelineName}-country-{countryCode}

​
Country Codes

Use ISO 3166 alpha-2 country codes:
  • US - United States
  • GB - United Kingdom
  • DE - Germany
  • FR - France
  • JP - Japan
  • ALL - Randomly select any country

​
Example

curl -x http://account-accountName-pipeline-pipelineName-country-US:[email protected]:7000 \
  https://ipinfo.io

​
State Targeting (US Only)

For more precise targeting within the United States, specify a state code.

​
Format

account-{accountName}-pipeline-{pipelineName}-country-US-state-{stateCode}

​
Example

curl -x http://account-accountName-pipeline-pipelineName-country-US-state-CA:[email protected]:7000 \
  https://ipinfo.io
State targeting is only available when the country is set to US. Use standard two-letter US state codes (e.g., CA, NY, TX).

​
City Targeting

Target a specific city for the most precise geolocation control.

​
Format

account-{accountName}-pipeline-{pipelineName}-country-{countryCode}-state-{stateCode}-city-{cityName}

​
Example

curl -x http://account-accountName-pipeline-pipelineName-country-US-state-CA-city-losangeles:[email protected]:7000 \
  https://ipinfo.io
City targeting requires both country and state to be specified. If no IPs are available in the specified city, the request will return a 525 response code.

​
Combining with Other Parameters

You can combine geotargeting with session control for powerful targeting: 
curl -x http://account-accountName-pipeline-pipelineName-country-US-state-NY-session-mysession:[email protected]:7000 \
  https://ipinfo.io
This request targets New York state and maintains a sticky session.

​
Getting Available Locations

To retrieve a list of all supported countries, states, and cities:

​
Using Admin API

GET /location/cities
This endpoint returns a comprehensive list of available geolocation options.

​
Geo-Sessions (Advanced)

For applications requiring consistent geographic proximity across rotations, use geo-sessions.

​
Key Features

  • Proximity guarantee: New IPs stay within 15km of original location
  • ASN consistency: Rotations use the same ISP
  • High durability: Uses most stable residential IPs

​
Format

account-{accountName}-pipeline-{pipelineName}-geosession-{sessionId}

​
Requirements

  • Session ID must be 16-32 alphanumeric characters (minimum 16)
  • Request timeout of at least 40 seconds recommended
  • Currently available in the US only

​
Example

curl -x http://account-accountName-pipeline-pipelineName-country-US-city-chicago-geosession-mysession12345678:[email protected]:7000 \
  https://ipinfo.io
Geo-sessions vs Regular Sessions: Geo-sessions provide stricter location consistency (15km radius) and ASN matching, while regular sessions simply maintain the same IP. Use geo-sessions when precise location consistency is critical.

​
Configuration via Dashboard

For IP allowlist authentication, configure default geotargeting through:
  • Nimble dashboard pipeline settings
  • Admin API /account/pipelines endpoint

​
Response Codes

CodeMeaning
200Success - IP found for target location
525No IP available for specified location

View All Response Codes

See complete response code reference

​
Next Steps

Session Control

Learn how to control IP rotation

Response Codes

Understand error codes and troubleshooting