国家与城市

helodata 住宅代理覆盖 195+ 国家，主要市场支持州 / 城市级定位。三个地理字段——region、state、city——均编码在代理用户名中。

国家（region）

必填。使用小写 ISO-3166 alpha-2 国家代码作为 region。

helo_s1a2b3c4d5e-type-res-region-{country}

示例：

国家	代码	用户名示例
美国	us	helo_s1a2b3c4d5e-type-res-region-us
英国	gb	helo_s1a2b3c4d5e-type-res-region-gb
德国	de	helo_s1a2b3c4d5e-type-res-region-de
日本	jp	helo_s1a2b3c4d5e-type-res-region-jp
巴西	br	helo_s1a2b3c4d5e-type-res-region-br
印度	in	helo_s1a2b3c4d5e-type-res-region-in

完整的实时清单可通过 API 获取：

curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/residential/locations

州 / 省

可选。在支持行政区划的国家进一步细化定位，使用小写 ISO-3166-2 后缀（短横后部分）。

国家	州代码格式	示例
美国	2 字母	state-ca、state-ny、state-tx
加拿大	2 字母	state-on、state-bc
澳大利亚	2–3 字母	state-nsw、state-vic
巴西	2 字母	state-sp、state-rj
德国	2 字母	state-by（巴伐利亚）、state-be（柏林）

helo_s1a2b3c4d5e-type-res-region-us-state-ca

城市

可选，必须同时指定 state。城市 slug 全小写、无空格、无变音符号。

城市	slug
洛杉矶	la
纽约	newyork
旧金山	sf
多伦多	toronto
伦敦	london
东京	tokyo
圣保罗	saopaulo

helo_s1a2b3c4d5e-type-res-region-us-state-ca-city-la

并非所有国家所有城市都有足够多的在线 IP——某城市在线出口少于 50 时，网关回落到州级，并通过响应头 X-Helodata-Fallback: city 提示。

大洲 / 区域分组

不在意具体国家但希望限定在某区域时，使用以下元代码：

元代码	包含范围
region-eu	欧盟成员国
region-eea	欧洲经济区（欧盟 + 挪威、冰岛、列支敦士登）
region-latam	墨西哥、中美及南美
region-mena	中东与北非
region-apac	亚太

不可与 state 或 city 组合使用。

地理判定流程

1. helodata 维护每 IP 的地理库，按日从 MaxMind 与运营商数据刷新。
2. 请求到达时，网关筛选符合你地理参数的在线 IP。
3. 在筛选集合中按负载均衡（轮换）或会话键（粘性）选定 IP。
4. 出口 IP 通过响应头返回，如 X-Helodata-Exit-IP: 198.51.100.42 与 X-Helodata-Exit-Geo: us/ca/la。

若实际出口 IP 的实时地理与请求不符（例如用户搬家），会计入 IP 地理位置不匹配 容忍度。

覆盖概览

覆盖类型	数量
国家级	195+
支持州级	60+ 国家
支持城市级	800+ 城市

T1 市场（美、英、德、法、日、韩、巴、澳、加）IP 池最深，城市覆盖最广。