# 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: 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/products/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.