# Regions

## `GET /regions`

Lists the public TURN regions. Use a region's `slug` as `preferred_region` or `fixed_region` in [`POST /credentials/ice`](https://turnix.io/docs/api-reference/credentials), or to build a TURN hostname (`<slug>.turnix.io`) for [shared-secret integrations](https://turnix.io/docs/integrations/shared-secret).

```text
GET https://turnix.io/api/v1/regions
```

## Query parameters

| Parameter | Description |
|-----------|-------------|
| `for_org` | Set to any value (for example `for_org=1`) to list only the regions your organization's plan can use. On the free plan, these are the regions with `is_trial: true`. |

## Request

**cURL**

```bash
curl https://turnix.io/api/v1/regions \
  -H "Authorization: Bearer $TURNIX_API_TOKEN"
```

**Node.js**

```javascript
const res = await fetch("https://turnix.io/api/v1/regions", {
  headers: { Authorization: `Bearer ${process.env.TURNIX_API_TOKEN}` },
});
const regions = await res.json();
const usable = regions.filter((r) => r.is_online && r.is_operational);
```

**Python**

```python
regions = requests.get(
    "https://turnix.io/api/v1/regions",
    headers={"Authorization": f"Bearer {os.environ['TURNIX_API_TOKEN']}"},
    timeout=10,
).json()
usable = [r for r in regions if r["is_online"] and r["is_operational"]]
```

## Response

`200 OK`: a JSON array.

```json
[
  {
    "slug": "us-west",
    "nat2": "us",
    "city": "Portland",
    "name": "US West",
    "lat": 45.5152,
    "lon": -122.6784,
    "is_online": true,
    "is_operational": true,
    "is_trial": false
  },
  {
    "slug": "singapore",
    "nat2": "sg",
    "city": "Singapore",
    "name": "Singapore",
    "lat": 1.28455,
    "lon": 103.84429,
    "is_online": false,
    "is_operational": false,
    "is_trial": false
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `slug` | string | Region identifier. TURN host: `<slug>.turnix.io` |
| `nat2` | string | ISO 3166-1 alpha-2 country code, lowercase |
| `city` | string | City where the region is located |
| `name` | string | Display name |
| `lat`, `lon` | number | Coordinates, used for geo-routing |
| `is_online` | boolean | The region's servers are reachable |
| `is_operational` | boolean | The region accepts new credentials. Use regions where both flags are `true`. |
| `is_trial` | boolean | The region is available on the free plan |

The list of regions changes as we add capacity. Read it at runtime instead of hard-coding slugs, or check the [Server page](https://turnix.io/app/turn/server) in the dashboard.