Skip to main content
GET
/
v1
/
countries
List of countries
curl --request GET \
  --url https://api.cloro.dev/v1/countries \
  --header 'Authorization: Bearer <token>'
[
  "AF",
  "AX",
  "AL",
  "DZ",
  "AS"
]

Documentation Index

Fetch the complete documentation index at: https://docs.cloro.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeDescriptionExample
modelstringFilter 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

curl -X GET "https://api.cloro.dev/v1/countries" \
  -H "Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef"

​
Filter by model

curl -X GET "https://api.cloro.dev/v1/countries?model=chatgpt" \
  -H "Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef"

​
Response schema

FieldTypeDescription
ResponsearrayArray of supported country codes in ISO 3166-1 alpha-2 format

​
Authentication

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

​
Caching and performance

PracticeRecommendationReason
Cache duration24+ hoursCountry list rarely changes
ImplementationStore locally after first callReduces API calls and improves performance
ValidationUse for client-side country validationPrevents 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 above for how to query all countries or filter by specific provider.

​
Can I target specific cities or metro areas?

The Google Search endpoint supports city-level geo-targeting via the location parameter, which accepts Google canonical location names. For all other endpoints, only country-level targeting is available. What’s supported:
  • ✅ Country-level targeting using ISO 3166-1 alpha-2 codes (e.g., US, GB, JP) on all endpoints
  • ✅ City-level targeting via location parameter (e.g., New York,New York,United States) on Google Search only
What’s not supported:
  • ❌ City-level targeting on endpoints other than Google Search
  • ❌ 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

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
model
enum<string>

Filter countries available for a specific model

Available options:
aimode,
aioverview,
chatgpt,
copilot,
gemini,
google,
grok,
perplexity

Response

List of supported country codes

Example:
["AF", "AX", "AL", "DZ", "AS"]