Dynamic Proxy API: Countries, States, and Cities
Look up supported locations and use the correct values for countries, states, and cities.
Look up the location values accepted by dynamic residential, datacenter, and mobile proxy generation. Use the returned values rather than building location identifiers from display names.
Request
GET /api/user_get_location_list
Send Api-Token: YOUR_API_KEY. An optional Accept-Language header accepts en, zh-CN, or zh-HK. Use the API host shown in the web console.
| Parameter | Required | Description |
|---|---|---|
type | Yes | wifi: residential; dat: datacenter (dc is an alias); 5g: mobile |
level | No | country, state, or city; defaults to country |
country | Conditional | Required for states and cities; use a country result's value |
state | Conditional | Required for cities; use a state result's value |
keyword | No | Filter by English, Simplified Chinese, Traditional Chinese name, or code |
Only wifi supports country → state → city lookups. Datacenter and mobile types support countries only. A location being listed does not guarantee that every connection to that location will succeed immediately.
Query each level
The Bash/curl examples assume DFIP_API_BASE contains your actual API origin and DFIP_API_KEY has been supplied securely.
# 1. Read countries.
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user_get_location_list" \
-H "Api-Token: $DFIP_API_KEY" -H 'Accept-Language: en' \
--data-urlencode 'type=wifi' --data-urlencode 'level=country'
# 2. Use a returned country value.
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user_get_location_list" \
-H "Api-Token: $DFIP_API_KEY" -H 'Accept-Language: en' \
--data-urlencode 'type=wifi' --data-urlencode 'level=state' \
--data-urlencode 'country=COUNTRY_VALUE'
# 3. Use a returned state value.
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user_get_location_list" \
-H "Api-Token: $DFIP_API_KEY" -H 'Accept-Language: en' \
--data-urlencode 'type=wifi' --data-urlencode 'level=city' \
--data-urlencode 'country=COUNTRY_VALUE' \
--data-urlencode 'state=STATE_VALUE'
Preserve the returned values and URL-encode them when sending requests. For a city, send list[].value, not list[].code.
Response
Success uses the envelope {"code":0,"msg":"ok","data":{...}}.
Field inside data | Meaning |
|---|---|
type | Normalized type; the dc alias returns dat |
ip_type | wifi=1, 5g=2, dat=3 |
level | Requested lookup level |
supported_levels | Levels supported by this proxy type |
parent | Supplied country and state values |
count | Number of matching results |
list | Results; an empty array means no matches |
list[].value | Value to use for the next lookup or generation request; a code for countries/states and an English name for cities |
list[].code | Identifier; it can differ from the accepted city value |
list[].name_cn, name_en, name_hk | Localized display names |
The endpoint returns the full filtered list. It does not implement server-side page or page_size parameters. Filter with keyword or paginate results in your application.
Error codes
| Code | Action |
|---|---|
1002 | Correct the proxy type |
1007 | Check for an invalid, disabled, or expired key |
1008 | Check that the account exists and is enabled |
1012 | Use country, state, or city |
1013 | Supply the required parent country or state |
1014 | Switch to country lookup for a type without state/city support |
1015 | Retry later after a temporary location service failure |
Next: Generate dynamic proxy connections. Getting started · 中文版