查询动态代理地区

按国家、省州和城市层级查询动态代理可用地区。生成地区化连接凭据时，应使用本接口返回的地区编码。

接口信息

项目	内容
Method	GET
Path	/open-api/v1/dynamic/regions
认证	X-API-Key
处理方式	同步

Query 参数

参数	类型	必填	说明
level	string	是	COUNTRY、PROVINCE 或 CITY
parent_code	string	条件必填	直接上级地区编码

层级规则：

level	parent_code 规则
COUNTRY	必须省略
PROVINCE	必须传国家编码
CITY	必须传省州编码

parent_code 长度为 1～64 个 Unicode 字符。不能包含首尾空白、控制字符或换行；不会自动去除空白或转换字符形式。每个 Query 参数只能出现一次。

请求示例

查询国家：

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: zh_CN'

查询某个国家的省州：

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>'

响应参数

data 为地区数组。

字段	类型	可为空	说明
region_code	string	否	地区编码
name	string	否	与 X-LANG 对应的地区名称
level	string	否	COUNTRY、PROVINCE 或 CITY
parent_code	string	是	直接上级地区编码；国家为空
has_children	boolean	否	是否还有可用的下级地区

成功响应示例

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

可能的错误码

code	说明
300001	指定的上级地区不存在或当前不可用
400001	认证失败
400009	层级、上级编码或其他参数不符合要求
500000	系统处理失败，请求未完成