> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Available Countries

> The ISO-2 country codes that have a hotel emission factor, so you only offer destinations that can be calculated

[← Hotel Stays API](/api-reference/hotel-stays/overview)

List the countries that have a hotel emission factor behind them. A stay in a country outside this list has no factor to calculate against, so this is what you call to build a destination picker that cannot produce an uncalculable record.

<Warning>
  **The response is ISO-2 country codes in upper case, not country names.** You get `["ES", "FR", "DE", "GB"]`, never `["Spain", "France", …]`. Comparing a user-facing country name against this list matches nothing — map your names to ISO-2 codes first.
</Warning>

<Note>
  **Reference data, not your data.** The list is the same for every organization and does not depend on where you have actually booked stays — fetch it once and cache it. It is drawn from the hotel factor tables as a whole, which today means DEFRA plus Greenview; a handful of countries are covered only by the latter, so do not assume every code has a DEFRA factor behind it.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  UUID of your organization.

  **Format:** UUID
</ParamField>

<Note>
  **The organization header is required even though the list is global.** The response is not scoped to an organization, but the router's authentication dependency resolves one from this header before the handler runs. Omitting it returns `422`, not `401`.
</Note>

## Response

Returns a **flat array of ISO-2 country codes**, upper case, not an object wrapping one. There is no `items`, no `total_count`, no pagination.

<ResponseField name="array" type="array[string]">
  Upper-case ISO-2 codes of the countries that have a hotel emission factor — `ES`, `FR`, `GB`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/hotel-stays/available-countries" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "x-organization-id: YOUR_ORGANIZATION_ID"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  countries = requests.get(
      "https://api.dcycle.io/v1/hotel-stays/available-countries",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
      timeout=30,
  ).json()

  # The response is the list itself — no unwrapping
  print(len(countries), "countries with factors")

  def can_calculate(iso2_code):
      # Compare ISO-2 codes, not names: "Spain" is never in this list
      return iso2_code.upper() in countries
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.dcycle.io/v1/hotel-stays/available-countries",
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
    },
  );
  const countries = await response.json();

  // Compare ISO-2 codes, not names
  const canCalculate = (iso2Code) => countries.includes(iso2Code.toUpperCase());
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
["AE", "AR", "AT", "AU", "BE", "BR", "CA", "CH", "CL", "DE", "ES", "FR", "GB"]
```

## Common Errors

### 422 Unprocessable Entity

**Cause:** `x-organization-id` is missing. This fires before any credential check, so it is what a request with no headers at all returns.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["header", "x-organization-id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 401 Unauthorized

**Cause:** The organization header is present but the credentials are not.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "CREDENTIALS_REQUIRED",
  "detail": "Credentials required (API key or JWT token)"
}
```

## Use Cases

### Offer only destinations that can be calculated

Build your country dropdown from this list instead of from a general country catalogue, keying the options by ISO-2 code. A stay recorded in a country with no factor still saves, but it will not produce emissions — and nothing in the record itself makes that obvious afterwards.

### Validate an import before you send it

When loading hotel stays in bulk, map each row's country to its ISO-2 code and check it against this list first. Rejecting the row up front, with a message naming the country, is far easier to act on than discovering later that part of the batch has no emissions.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Hotel Stay" icon="plus" href="/api-reference/hotel-stays/create">
    Record a stay in one of these countries
  </Card>

  <Card title="Upload Hotel Stays CSV" icon="file-csv" href="/api-reference/hotel-stays/csv-upload">
    Bulk load, where validating countries first pays off most
  </Card>

  <Card title="Impact Calculation" icon="calculator" href="/api-reference/hotel-stays/impact-calculation">
    How a stay turns into emissions
  </Card>

  <Card title="Hotel Stays API" icon="hotel" href="/api-reference/hotel-stays/overview">
    Everything the Hotel Stays API covers
  </Card>
</CardGroup>