> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/products/overview/locations.md).

# Locations

helodata residential proxies cover **195+ countries** with state and city-level targeting in the larger markets. All three geo segments — `region`, `state`, `city` — go into the proxy username.

## Country (region)

Always required. Use the lowercase **ISO-3166 alpha-2** code as the `region` value.

```
helo_s1a2b3c4d5e-type-res-region-{country}
```

Examples:

| Country        | Code | Example                               |
| -------------- | ---- | ------------------------------------- |
| United States  | `us` | `helo_s1a2b3c4d5e-type-res-region-us` |
| United Kingdom | `gb` | `helo_s1a2b3c4d5e-type-res-region-gb` |
| Germany        | `de` | `helo_s1a2b3c4d5e-type-res-region-de` |
| Japan          | `jp` | `helo_s1a2b3c4d5e-type-res-region-jp` |
| Brazil         | `br` | `helo_s1a2b3c4d5e-type-res-region-br` |
| India          | `in` | `helo_s1a2b3c4d5e-type-res-region-in` |

The full live list is exposed at:

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

## State / province

Optional. Adds finer targeting in countries that expose subdivisions. Use the lowercase **ISO-3166-2** suffix (the part after the dash).

| Country   | State code style | Example                                  |
| --------- | ---------------- | ---------------------------------------- |
| US        | 2-letter         | `state-ca`, `state-ny`, `state-tx`       |
| Canada    | 2-letter         | `state-on`, `state-bc`                   |
| Australia | 2–3 letter       | `state-nsw`, `state-vic`                 |
| Brazil    | 2-letter         | `state-sp`, `state-rj`                   |
| Germany   | 2-letter         | `state-by` (Bayern), `state-be` (Berlin) |

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

## City

Optional, requires `state` to be specified. City slugs are lowercase, no spaces, no diacritics.

| City          | Slug       |
| ------------- | ---------- |
| Los Angeles   | `la`       |
| New York      | `newyork`  |
| San Francisco | `sf`       |
| Toronto       | `toronto`  |
| London        | `london`   |
| Tokyo         | `tokyo`    |
| São Paulo     | `saopaulo` |

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

Not every city in every country has enough live IPs to be targetable — if a city has fewer than 50 active exits, the gateway falls back to state-level and emits a warning header `X-Helodata-Fallback: city`.

## Continent / region groups

If you don't care about the specific country but want to stay in a region, use the meta codes:

| Meta code      | Includes                                  |
| -------------- | ----------------------------------------- |
| `region-eu`    | EU member states                          |
| `region-eea`   | EEA (EU + Norway, Iceland, Liechtenstein) |
| `region-latam` | Mexico, Central & South America           |
| `region-mena`  | Middle East and North Africa              |
| `region-apac`  | Asia-Pacific                              |

These cannot be combined with `state` or `city`.

## How geo is resolved

1. helodata holds a per-IP geo database refreshed daily from MaxMind + carrier feeds.
2. When a request arrives, the gateway filters live IPs matching your geo segments.
3. From that filtered set, an IP is chosen by load balancer (rotating) or by session key (sticky).
4. The exit IP appears in your response, e.g. `X-Helodata-Exit-IP: 198.51.100.42` and `X-Helodata-Exit-Geo: us/ca/la`.

If your request gets routed to an IP whose live geo turned out to mismatch (e.g. user moved), it counts against the [IP location mismatch](/troubleshooting/ip-location-mismatch.md) tolerance.

## Coverage at a glance

| Coverage | Countries | State-level | City-level |
| -------- | --------- | ----------- | ---------- |
| Live IPs | 195+      | 60+         | 800+       |

Tier-1 markets (US, UK, DE, FR, JP, KR, BR, AU, CA) have the deepest pools and the broadest city support.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.helodata.com/products/overview/locations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.