Geo-targeting

You choose where a proxy exits when you generate lines from a plan. How precisely you can choose depends on the product. Every product targets by country; Premium Residential adds state, city, ASN, device type and exclusions. Some pools list only a few countries (ISP Rotating and the per-GB IPv4 and IPv6 pools currently target the US only), and per-GB Mobile does not currently list the US. Use /v1/geo/countries to see what a product offers.

A plan's own limits are always in generate.targeting on GET /v1/plans. If you send a field the plan doesn't offer, the API now answers with a clear 400 telling you which field and which product to use instead. It never quietly drops it.

Rules and formats

• country: a two-letter code such as US or DE, from /v1/geo/countries.
• state: send the value from /v1/geo/states, for example california. The display name also works.
• city: send the city name from /v1/geo/cities, for example Los Angeles.
• Send a state or a city, not both. A city already implies its state, and the network targets one level at a time. Sending both returns a 400.
• asn: a whole AS number such as 7922 (a number, not text), from /v1/geo/asns. Needs a country.
• state and city need a country. Names are matched ignoring case, spaces and punctuation, so Los Angeles and losangeles are the same city.
• A state or city we can't find in the list for that country is rejected with a 400 that names it, instead of returning a line that won't connect.

Location lists (JSON or CSV)

These lists come straight from the network's own catalog, so they always match what it will accept. They work with a personal or a reseller API key, and add ?format=csv for a spreadsheet-friendly file.

GET /v1/geo/countries                           # all countries (codes + names)
GET /v1/geo/states?country=US                   # Premium Residential
GET /v1/geo/asns?country=US                     # networks (ASNs) you can target
GET /v1/geo/cities?country=US                   # every city in the country
GET /v1/geo/cities?country=US&state=california  # cities of one state
# add &format=csv to download as a file

curl "https://www.buyproxy.org/v1/geo/states?country=US" -H "X-API-Key: YOUR_KEY"
# { "kind": "states", "count": 51, "items": [ { "name": "California", "value": "california" }, ... ] }

Working examples

Generate one US line on a Premium Residential plan, targeted to a state, and then to a city:

curl -X POST https://www.buyproxy.org/v1/plans/PLAN_ID/generate   -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json"   -d '{ "count": 1, "country": "US", "state": "california" }'

curl -X POST https://www.buyproxy.org/v1/plans/PLAN_ID/generate   -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json"   -d '{ "count": 1, "country": "US", "city": "Los Angeles" }'

For reseller customers, the same fields go to POST /v1/customers/{username}/generatetogether with the customer's planId.

The targeting is encoded in the username of each returned line, so you never send it separately to the proxy. Use the line exactly as returned.

Premium Residential options

• os: windows, mac, android or ios, to look like that device type.
• strict: false lets the network hand out another IP in the same country when none is free at your state, city or ASN, instead of failing.
• excludeCountries, excludeStates, excludeCities, excludeAsn: keep out of up to 20 places or networks. Use one kind per call. excludeCountries is for calls without a country, and states and cities need a country.
• udp: true with protocol: "socks5" lets the line open UDP relays.
• Sticky length: stickyMinutes from 3 to 1440, each line with its own session.

{ "country": "US", "asn": 7922, "os": "android", "strict": false, "count": 5 }
{ "excludeCountries": ["CN", "RU"], "count": 5 }

Not supported

• ZIP / postal code targeting. No product targets by ZIP code, so there is no ZIP list to download. Use city targeting on Premium Residential for the closest match.
• State or city on Core Residential. Core Residential targets by country only. Use Premium Residential for state and city.
• ISP by name. The isp field isn't available on any plan. Use asn on Premium Residential to target a network.
• A guaranteed IP in every city. A city or state on the list can still have few IPs at a given moment. If lines for a small city fail to connect, widen the target to its state or the country.