Skip to content
TPPTPPTPP Docs

Targeting

Targeting options are appended to your proxy username as -key-value pairs:

USER-cc-de-city-berlin-session-abc123
Key Value Example
cc ISO 3166-1 alpha-2 country code, case-insensitive (country is accepted as the old spelling) USER-cc-de
cont Continent: af, as, eu, na, oc, sa, an (or the full name; continent is accepted as the old spelling) USER-cont-eu
region State or region name, spaces as _, + or dropped (st is accepted as the old spelling) USER-cc-us-region-california
city City name, spaces as _, + or dropped USER-cc-us-city-new_york
asn Autonomous system number, with or without AS prefix USER-cc-de-asn-3320
zip Postal code, up to ten letters and digits; - separates keys, so leave out dashes and spaces USER-cc-us-zip-90210
os Exit device OS: windows, android (see Depth) USER-os-windows
strict true (default) or false - see Strict matching USER-cc-us-city-houston-strict-false
speed 1-10 parallel exits raced per session, fastest kept - see Speed. Needs session USER-cc-us-session-abc-speed-5

Options combine freely and each may appear once. With no options, every connection gets a random exit from the whole pool.

Rules

Section titled “Rules”
  • Invalid options fail authentication. An unknown key, a repeated key, or a malformed value (nation-de, cc-deu, asn-abc) is rejected with an auth error rather than silently ignored - otherwise you’d be billed for untargeted traffic you didn’t ask for.
  • cc and cont are the same field asked two ways, so a username carrying both is rejected. Pick the one you mean; a country is always the narrower.
  • No matching exit fails the connection, not authentication: you’ll get HTTP 502/404 (or a SOCKS reply code). Pool composition shifts continuously; narrow targets - a specific postal code, an uncommon OS - may briefly have no live exits. Loosen the target or retry.
  • Place names take _ or + for spaces, or none at all (new_york, new+york, newyork) and are matched against the English name - rome, not roma. Type them in any casing you like and we case them for you; supply your own only for names title-casing gets wrong, as in city-Frankfurt_am_Main. Punctuation is ignored when matching, so st_louis, st._louis and stlouis are the same request. Pair region, city and asn with cc wherever you can - see Depth; a place on its own is both ambiguous and thinner.
  • region takes the name or the ISO code within a cc: region-california and region-ca are the same request.
  • Targeting is resolved per connection, so there is no list to consult first - ask for what you want and read the answer.

Depth

Section titled “Depth”

Targets are not all equally deep. These draw from the whole provider pool and are as fast as an untargeted request:

  • cc, on its own or with asn
  • asn on its own
  • cont on its own, which draws one of its countries per request weighted by how many live exits each has

Everything below is served from exits we have already placed ourselves against DB-IP, so the answer is exact but the inventory is what we hold live right now, and a narrow target can come back with no match:

  • region, city, zip and os, alone or combined with anything above
  • region or city without a cc - USER-region-bayern works, but USER-cc-de-region-bayern is far deeper

os is the exit device’s own TCP fingerprint - the machine that terminates the connection - and not a browser user-agent, which a proxy cannot see:

value share of the pool
windows ~55%
android ~39%

These shift with whatever else you target - os combined with a country draws from that country’s inventory, which can look very different. Treat the table as the untargeted baseline, not a guarantee.

Strict matching

Section titled “Strict matching”

By default a target is exact: if no exit matches the region, city, zip or asn you asked for, the connection fails rather than handing you an exit somewhere else.

Add strict-false to fall back instead. The target is loosened one step at a time - asn first, then zip, then city, then region - until an exit serves. The country is never dropped, so you always stay inside the cc you asked for.

USER-cc-us-region-texas-city-houston-strict-false

Speed

Section titled “Speed”

speed races that many exits in parallel for a new session and keeps whichever connects first. The session then stays on the winner for its ttl, so only the first connection of a session pays for the race.

USER-cc-us-session-abc123-speed-5
  • Needs session; a username with speed and no session is rejected.
  • 1 is no race, 10 is the maximum. Higher values find a faster exit more often, at the cost of more upstream connections opened at the start of each session.
  • Losing exits are closed before any of your data is sent, so the target only ever sees the winner.

Sticky sessions

Section titled “Sticky sessions”

Add session to hold one exit across connections, and ttl to say for how long, in minutes (capped at 120):

USER-cc-de-session-abc123-ttl-30

The token is yours alone: two customers using the same string never share an exit.

Examples

Section titled “Examples”
Terminal window
# Any German exit
curl -x http://USER-cc-de:PASS@eu.tpp.io:8888 https://api.ipify.org


# Anywhere in Europe
curl -x http://USER-cont-eu:PASS@eu.tpp.io:8888 https://api.ipify.org


# Deutsche Telekom (AS3320) exits only.
curl -x http://USER-cc-de-asn-3320:PASS@eu.tpp.io:8888 https://api.ipify.org


# California
curl -x http://USER-cc-us-region-california:PASS@us.tpp.io:8888 https://api.ipify.org


# Beverly Hills 90210
curl -x http://USER-cc-us-zip-90210:PASS@us.tpp.io:8888 https://api.ipify.org


# Windows devices in the United States
curl -x http://USER-cc-us-os-windows:PASS@us.tpp.io:8888 https://api.ipify.org


# Houston if there is one, otherwise Texas, otherwise anywhere in the US
curl -x http://USER-cc-us-region-texas-city-houston-strict-false:PASS@us.tpp.io:8888 https://api.ipify.org


# Fastest of five German exits, held for 30 minutes
curl -x http://USER-cc-de-session-abc123-ttl-30-speed-5:PASS@eu.tpp.io:8888 https://api.ipify.org