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

# Get Regions

> Get all available regions (countries & continents) for eSIM packages

## Endpoint

```
GET /api/esim/regions
```

## Description

This endpoint returns a list of all available regions where eSIM packages can be purchased. Regions can be individual countries or multi-country/continental packages.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  API Key for authentication

  ```
  YOUR_API_KEY
  ```
</ParamField>

## Query Parameters

<ParamField query="type" type="number" optional>
  Filter by region type:

  * `1` - Countries only (single country packages)
  * `2` - Continents/Multi-country packages only

  If omitted, returns all regions.
</ParamField>

## Response

<ResponseField name="regions" type="array">
  Array of region objects

  <Expandable title="Region Object">
    <ResponseField name="regionCode" type="string">
      Unique code for the region (e.g., "US", "EU", "ASIA")
    </ResponseField>

    <ResponseField name="regionName" type="string">
      Display name of the region
    </ResponseField>

    <ResponseField name="regionType" type="string">
      Type of region: `LC` (Local/Country), `RG` (Regional), `GL` (Global)
    </ResponseField>

    <ResponseField name="countryCode" type="string">
      ISO country code (for country-specific regions)
    </ResponseField>

    <ResponseField name="flagUrl" type="string">
      URL to the region's flag image
    </ResponseField>

    <ResponseField name="packageCount" type="number">
      Number of available packages for this region
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.vellosim.com/api/esim/regions?type=1' \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript / TypeScript theme={null}
  //Get all regions
  const response = await fetch('https://api.vellosim.com/api/esim/regions', {
    method: 'GET',
    headers: {
      'X-API-Key': ' YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log('Available regions:', data);

  // Get only countries
  const countriesResponse = await fetch(
    'https://api.vellosim.com/api/esim/regions?type=1',
    {
      method: 'GET',
      headers: {
        'X-API-Key': ' YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );

  const countries = await countriesResponse.json();
  console.log('Countries:', countries);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': ' YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  # Get all regions
  response = requests.get(
      'https://api.vellosim.com/api/esim/regions',
      headers=headers
  )

  data = response.json()
  print(f"Available regions: {len(data)}")

  # Get only multi-country packages
  params = {'type': 2}
  response = requests.get(
      'https://api.vellosim.com/api/esim/regions',
      headers=headers,
      params=params
  )

  multi_country = response.json()
  print(f"Multi-country packages: {len(multi_country)}")
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = 'YOUR_API_KEY';

  // Get all regions
  $ch = curl_init('https://api.vellosim.com/api/esim/regions');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . $apiKey,
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  $regions = json_decode($response, true);

  curl_close($ch);

  echo "Available regions: " . count($regions);

  // Get only countries
  $ch = curl_init('https://api.vellosim.com/api/esim/regions?type=1');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . $apiKey,
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  $countries = json_decode($response, true);

  curl_close($ch);

  echo "\nCountries: " . count($countries);
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "regionCode": "US",
      "regionName": "United States",
      "regionType": "LC",
      "countryCode": "US",
      "flagUrl": "https://flagcdn.com/w320/us.png",
      "packageCount": 15
    },
    {
      "regionCode": "GB",
      "regionName": "United Kingdom",
      "regionType": "LC",
      "countryCode": "GB",
      "flagUrl": "https://flagcdn.com/w320/gb.png",
      "packageCount": 12
    },
    {
      "regionCode": "EU",
      "regionName": "Europe",
      "regionType": "RG",
      "countryCode": null,
      "flagUrl": "https://example.com/flags/eu.png",
      "packageCount": 20
    },
    {
      "regionCode": "ASIA",
      "regionName": "Asia Pacific",
      "regionType": "RG",
      "countryCode": null,
      "flagUrl": "https://example.com/flags/asia.png",
      "packageCount": 18
    },
    {
      "regionCode": "GLOBAL",
      "regionName": "Global Coverage",
      "regionType": "GL",
      "countryCode": null,
      "flagUrl": "https://example.com/flags/global.png",
      "packageCount": 8
    }
  ]
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "message": "Unauthorized",
    "error": {
      "code": "INVALID_TOKEN",
      "details": "Invalid or expired authentication token"
    }
  }
  ```
</ResponseExample>

## Region Types

| Type     | Code | Description                    | Example                         |
| -------- | ---- | ------------------------------ | ------------------------------- |
| Local    | `LC` | Single country coverage        | United States, Japan, France    |
| Regional | `RG` | Multiple countries in a region | Europe, Asia Pacific, Caribbean |
| Global   | `GL` | Worldwide coverage             | Global eSIM packages            |

## Use Cases

<AccordionGroup>
  <Accordion title="Display Country Selector">
    Use this endpoint to populate a country/region selector in your UI:

    ```javascript theme={null}
    async function loadRegions() {
      const regions = await fetch('/api/esim/regions?type=1', {
        headers: { 'X-API-Key': ' YOUR_API_KEY' }
      }).then(r => r.json());
      
      const selector = document.getElementById('country-select');
      regions.forEach(region => {
        const option = document.createElement('option');
        option.value = region.regionCode;
        option.text = region.regionName;
        selector.appendChild(option);
      });
    }
    ```
  </Accordion>

  <Accordion title="Show Package Availability">
    Display which regions have available packages:

    ```javascript theme={null}
    const regions = await getRegions();
    const availableRegions = regions.filter(r => r.packageCount > 0);

    console.log(`${availableRegions.length} regions have available packages`);
    ```
  </Accordion>

  <Accordion title="Separate Countries and Regional Packages">
    Create different sections for single-country and multi-country packages:

    ```javascript theme={null}
    const countries = await fetch('/api/esim/regions?type=1', {
      headers: { 'X-API-Key': ' YOUR_API_KEY' }
    }).then(r => r.json());

    const multiCountry = await fetch('/api/esim/regions?type=2', {
      headers: { 'X-API-Key': ' YOUR_API_KEY' }
    }).then(r => r.json());

    displayCountries(countries);
    displayRegionalPackages(multiCountry);
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Packages" icon="box" href="/api-reference/esim/packages">
    View available eSIM packages for a region
  </Card>

  <Card title="Top Destinations" icon="star" href="/api-reference/esim/top-destinations">
    Get popular destinations with featured packages
  </Card>

  <Card title="Purchase eSIM" icon="shopping-cart" href="/api-reference/purchase/buy">
    Buy an eSIM package
  </Card>

  <Card title="Integration Guide" icon="code" href="/guides/region-selection">
    Learn how to build a region selector
  </Card>
</CardGroup>