Geotargeting and session control

Adding targeting parameters

Connecting to Nimble IP with user:password authentication allows you to control session targeting and behavior by modifying the user portion of the request.

Selecting your target geolocation

To request an IP from a specific country, add country-<country_code> to the user portion:

curl -x http://account-accountName-pipeline-pipelineName-country-countryCode:[email protected]:7000 https://targetpage.com

We use ISO 3166 alpha-2 Country Codes (use ALL to randomly select a country).

If you’d like to get even more specific, you can also add state-<state_code> to target a US state. The list of state codes can be found here.

If no peers are available in a supported country/state/city, Nimble IP will return a 525 response. For more information, see Nimble IP's Response Codes.

Using sticky IPs

A sticky IP allows you to make multiple requests through the same IP address. This is done by initiating a session, which associates your request with the sticky IP address.

To create a session, add session-<random_string> to the user portion.

Session IDs are limited to 32 alphanumeric characters (no minimum). Session IDs cannot include hyphens "-" as this will act as a separator and end the "username" portion of the connection string.

For example:

curl -x http://account-accountName-pipeline-pipelineName-session-randomString:[email protected]:7000 https://targetpage.com

Geo-sessions: longer, more stable, more accurate sessions

Nimble Geo-sessions are a next-gen session solution that provides a variety of upgrades, including:

Geo-sessions are incredibly easy to use; simply pass the parameter geosession along with a random string of your choosing that will serve as the Geo-session ID.

Geosession IDs are limited to between 16 to 32 alphanumeric characters (16 characters minimum).

For example:

curl -x http://account-accountName-pipeline-pipelineName-geosession-randomGeoSessionString:[email protected]:7000 https://targetpage.com

Be sure to use the same parameters across requests that share the same Geo-session. If the location targeting is changed, but the Geo-session ID remains the same, a new session will still be initiated.

Geo-sessions are currently only supported within the US. Support for additional countries is coming soon.

Learn more about how Geo-sessions work and how to use them.

Combining parameters

All of the parameters we’ve covered before can be used together in a single request. This is done by chaining them together, like in this example:

curl -x http://account-MyCompany-pipeline-residential-country-US-state-NY-session-sess1:[email protected]:7000 https://ipinfo.io