# Describe regions

> Public, unauthenticated discovery of how geo targeting works — the region object shape, examples, and popular countries.

`GET /v1/regions` describes how **geo targeting** works: the shape of a region object, worked examples, and the popular countries the exit network covers. Like [`GET /v1/surfaces`](/api-reference/list-surfaces), it's public discovery — read it to learn the targeting model without needing a key.

<Info>
  **Deliberately unauthenticated**, like `GET /v1/surfaces`. Every other `/v1`
  route requires `Authorization: Bearer <key>`; these two discovery routes do
  not, so a client can learn the capability and targeting model up front.
</Info>

## Request

<CodeGroup>

```bash cURL
curl https://api.aisearchapi.dev/v1/regions
```

```javascript Node
const res = await fetch('https://api.aisearchapi.dev/v1/regions');
const regions = await res.json();
```

```python Python
import requests

regions = requests.get("https://api.aisearchapi.dev/v1/regions").json()
```

</CodeGroup>

## Response

```json 200 OK
{
  "targeting": {
    "country": "ISO 3166-1 alpha-2 country code (required)",
    "state": "Optional sub-national code or name",
    "city": "Optional city name",
    "language": "Optional BCP-47 language hint"
  },
  "examples": [
    { "country": "US" },
    { "country": "GB", "city": "London", "language": "en" },
    { "country": "DE", "language": "de" }
  ],
  "popularCountries": ["US", "GB", "DE", "FR", "CA", "AU", "IN", "JP", "BR"]
}
```

<ResponseField name="targeting" type="object">
  The fields a region object accepts. `country` is required; `state`, `city`,
  and `language` narrow the capture further.
</ResponseField>

<ResponseField name="examples" type="object[]">
  Ready-to-use region objects covering common targeting patterns.
</ResponseField>

<ResponseField name="popularCountries" type="string[]">
  Commonly targeted countries where the v1 exit network has the strongest
  coverage. `country` accepts any valid ISO 3166-1 alpha-2 code — this list is a
  convenience, not an allowlist, so a country outside it is **not** rejected.
</ResponseField>

<Note>
  A region multiplies fan-out: one search across N surfaces and M regions
  creates N × M billed children. See [Regional availability](/guides/regions)
  for the full targeting model, including `requested` vs. `effective` region.
</Note>

<CardGroup cols={2}>
  <Card title="Regions guide" icon="globe" href="/guides/regions">
    Targeting, fan-out math, and requested vs. effective region.
  </Card>
  <Card
    title="List surfaces"
    icon="layer-group"
    href="/api-reference/list-surfaces"
  >
    The other public discovery endpoint: the live surface matrix.
  </Card>
</CardGroup>