List dynamic proxy regions

List available dynamic proxy regions by country, province/state, and city. Use the region codes returned by this API when generating region-specific connection credentials.

API information

Item	Value
Method	GET
Path	/open-api/v1/dynamic/regions
Authentication	X-API-Key
Processing	Synchronous

Query parameters

Parameter	Type	Required	Description
level	string	Yes	COUNTRY, PROVINCE, or CITY
parent_code	string	Conditional	Code of the immediate parent region

Hierarchy rules:

level	parent_code rule
COUNTRY	Must be omitted
PROVINCE	A country code is required
CITY	A province/state code is required

parent_code must contain 1–64 Unicode characters. It cannot contain leading or trailing whitespace, control characters, or line breaks. Whitespace and Unicode representations are not normalized automatically. Each query parameter may appear only once.

Request examples

List countries:

curl --request GET \
  --url 'https://api-test.puraroute.com/gin/open-api/v1/dynamic/regions?level=COUNTRY' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <YOUR_API_KEY>' \
  --header 'X-LANG: en_US'

List provinces/states in a country:

curl --request GET \
  --url 'https://api-test.puraroute.com/gin/open-api/v1/dynamic/regions?level=PROVINCE&parent_code=US' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <YOUR_API_KEY>'

Response fields

data is an array of regions.

Field	Type	Nullable	Description
region_code	string	No	Region code
name	string	No	Region name in the language selected by X-LANG
level	string	No	COUNTRY, PROVINCE, or CITY
parent_code	string	Yes	Immediate parent region code; null for countries
has_children	boolean	No	Whether an available child region exists

Successful response example

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "region_code": "US",
      "name": "United States",
      "level": "COUNTRY",
      "parent_code": null,
      "has_children": true
    }
  ],
  "next": null
}

Possible error codes

code	Description
300001	The specified parent region does not exist or is currently unavailable
400001	Authentication failed
400009	The level, parent code, or another parameter is invalid
500000	System processing failed; the request did not complete