# 国家与城市

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 获取：

```bash
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 地理位置不匹配](/helodata-zh/gu-zhang-pai-cha/ip-location-mismatch.md) 容忍度。

## 覆盖概览

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/chan-pin/overview/locations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.