# ETF Country List

> Returns the canonical set of values the `country` field of ETF geographic allocation (`/v2/etfs/countries`) can take.

`GET https://api.bavest.co/v2/etfs/countries/list`

Group: ETFs. Route id: `v2_etfs_countries_list`. Free in every plan, including the trial.

## Description

Returns the canonical set of values the `country` field of ETF geographic
allocation (`/v2/etfs/countries`) can take.

Every `country` value served by the API appears in this list. The list is
complete and authoritative. Each entry is tagged by `type`:

- `country`: ISO 3166 country or territory, including common aliases
- `region`: multi-country grouping such as "Europe" or "Emerging Markets"
- `supranational`: non-sovereign issuer bucket such as "Supranational" or
  "European Union", common in bond ETFs (World Bank, EIB, EU)
- `other`: non-geographic values such as "Cash", "Other", "Unknown", "N/A"

No ETF identifier is required.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

None.

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.count` | integer | no | Total number of country values in the catalog. Example: `293`. |
| `data.countries` | array of object | no |  |
| `data.countries[].name` | string | no | Country-allocation value. Example: `United States`. |
| `data.countries[].type` | string | no | Value category. One of `country`, `region`, `supranational`, `other`. Example: `country`. |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl 'https://api.bavest.co/v2/etfs/countries/list' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "count": 301,
    "countries": [
      {
        "name": "ASEAN",
        "type": "region"
      },
      {
        "name": "Afghanistan",
        "type": "country"
      }
    ]
  },
  "meta": {
    "time": 462
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_etfs_countries_list
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt