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

# List of countries

> Returns a list of all supported ISO 3166-1 alpha-2 country codes. Can be filtered by model to get countries available for specific AI providers.

## Overview

The Countries endpoint returns a list of supported ISO 3166-1 alpha-2 country codes that can be used with the monitoring API. The endpoint can be filtered by model to get countries available for specific AI providers.

## Request parameters

### Required parameters

None. This endpoint accepts a GET request.

### Optional parameters

| Parameter | Type   | Description                                                                                        | Example   |
| --------- | ------ | -------------------------------------------------------------------------------------------------- | --------- |
| `model`   | string | Filter countries available for a specific model. If not provided, returns all supported countries. | `chatgpt` |

**Available model values:**

* `aimode`
* `aioverview`
* `chatgpt`
* `copilot`
* `gemini`
* `google`
* `perplexity`

## Example usage

### Basic request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cloro.dev/v1/countries" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  ["AF", "AX", "AL", "DZ", "AS", "AD"]
  ```
</CodeGroup>

### Filter by model

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cloro.dev/v1/countries?model=chatgpt" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  ["US", "GB", "CA", "AU", "DE"]
  ```

  ```bash cURL Python theme={null}
  import requests

  response = requests.get(
      "https://api.cloro.dev/v1/countries",
      params={"model": "perplexity"},
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  countries = response.json()
  print(countries)
  ```

  ```bash cURL Node.js theme={null}
  const fetch = require('node-fetch');

  const response = await fetch('https://api.cloro.dev/v1/countries?model=google', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  const countries = await response.json();
  console.log(countries);
  ```
</CodeGroup>

## Response schema

| Field    | Type  | Description                                                   |
| -------- | ----- | ------------------------------------------------------------- |
| Response | array | Array of supported country codes in ISO 3166-1 alpha-2 format |

## Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Caching and performance

| Practice       | Recommendation                         | Reason                                             |
| -------------- | -------------------------------------- | -------------------------------------------------- |
| Cache duration | 24+ hours                              | Country list rarely changes                        |
| Implementation | Store locally after first call         | Reduces API calls and improves performance         |
| Validation     | Use for client-side country validation | Prevents invalid country codes in monitor requests |

### Integration guidelines

1. **Fetch once**: Retrieve the country list when your application initializes
2. **Model-specific validation**: Use the model parameter to get countries available for specific AI providers before sending monitor requests
3. **Handle updates**: Implement a refresh mechanism for occasional updates
4. **Error handling**: Have fallback behavior if the endpoint is temporarily unavailable
5. **Invalid models**: Handle 400 errors when an invalid model parameter is provided

### Model-specific use cases

* **Before monitoring**: Call `GET /v1/countries?model=chatgpt` to get valid countries for ChatGPT monitoring
* **UI country selection**: Populate dropdown menus with only countries available for the selected model
* **Validation**: Validate user input against model-specific country lists before making monitor requests
* **Feature discovery**: Use different model values to discover which AI providers are available in which regions

## Common questions

### Which countries are supported?

cloro supports country-level targeting for nearly all countries. See the [request examples](#example-usage) above for how to query all countries or filter by specific provider.

### Can I target specific cities or states?

US state-level targeting is available on ChatGPT, Copilot, Perplexity, Gemini, and Grok via the `state` parameter. Use the [States endpoint](/api-reference/endpoint/states) to get the full list of supported codes.

The [Google Search endpoint](/api-reference/endpoint/monitor-google) supports city-level geo-targeting via the `location` parameter, which accepts [Google canonical location names](https://developers.google.com/google-ads/api/reference/data/geotargets).

What's supported:

* ✅ Country-level targeting using ISO 3166-1 alpha-2 codes (e.g., `US`, `GB`, `JP`) on all endpoints
* ✅ State-level targeting via `state` parameter (e.g., `CA`, `NY`, `TX`) on ChatGPT, Copilot, Perplexity, Gemini, and Grok (US only for now)
* ✅ City-level targeting via `location` parameter (e.g., `New York,New York,United States`) on Google Search only

What's not supported:

* ❌ State-level targeting on Google Search or AI Mode (use `location` / `uule` instead)
* ❌ State-level targeting outside the US
* ❌ Metro/region targeting
* ❌ Zip/postal code targeting
* ❌ Latitude/longitude coordinates

### Why are my geo-targeted requests returning unexpected results?

Common causes and solutions:

* Invalid country codes: Make sure you're using ISO 3166-1 alpha-2 codes (two-letter format).

* Provider limitations: Not all providers support all countries equally. Some providers may have limited coverage in certain regions.

* Prompt language mismatch: Using English prompts with non-English countries may affect result quality.

### How does geo-targeting work?

When you specify a `country` parameter in monitoring requests, your request is processed through servers in or near the target region.

What geo-targeting affects:

* Search results and web sources
* Local business information
* Regional product availability (shopping cards)
* Language and cultural context
* Time zones and date formats

What geo-targeting doesn't affect:

* API pricing (same cost regardless of country)
* Response format or structure
* Available features or endpoints


## OpenAPI

````yaml api-reference/openapi.json GET /v1/countries
openapi: 3.1.0
info:
  title: cloro
  description: API for monitoring AI responses across different providers and regions
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.cloro.dev
    description: Production server
security:
  - bearerAuth: []
paths:
  /v1/countries:
    get:
      summary: List of countries
      description: >-
        Returns a list of all supported ISO 3166-1 alpha-2 country codes. Can be
        filtered by model to get countries available for specific AI providers.
      operationId: getCountries
      parameters:
        - name: model
          in: query
          description: Filter countries available for a specific model
          schema:
            type: string
            enum:
              - aimode
              - chatgpt
              - copilot
              - gemini
              - google
              - grok
              - perplexity
          example: chatgpt
      responses:
        '200':
          description: List of supported country codes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                  - AF
                  - AX
                  - AL
                  - DZ
                  - AS
        '400':
          description: Bad Request - Invalid model parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found - Route not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
components:
  schemas:
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Request validation failed
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: prompt
              message:
                type: string
                example: Prompt cannot be empty
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_API_KEY
                - INVALID_API_KEY_FORMAT
                - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: Missing or invalid API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    NotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Route not found
            details:
              type: object
              properties:
                id:
                  type: string
                  example: /v1/invalid-endpoint
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    InternalError:
      type: object
      oneOf:
        - properties:
            success:
              type: boolean
              example: false
            error:
              type: string
              example: Maximum retries exceeded
        - properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  example: INTERNAL_SERVER_ERROR
                message:
                  type: string
                  example: Internal server error
                timestamp:
                  type: string
                  format: date-time
                  example: '2025-01-15T12:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````