3 min de leitura

GET /analytics/:websiteId/countries

Retrieve visitor data grouped by country. Returns country codes, names, visitor counts, and average value scores sorted by visitor count descending.

GET/api/external/v1/analytics/:websiteId/countries

Get geographic breakdown of visitors

Authentication

AuthenticationBash

curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/a1b2c3d4-e5f6-7890-abcd-ef1234567890/countries?range=30d' \
-H 'X-API-Key: YOUR_API_KEY'

Parameters

Name	Type	Required	Default	Description
`websiteId`	string (path)	Yes	-	The UUID of the website
`range`	string (query)	No	`7d`	Time range: `24h`, `7d`, `30d`, `90d`, `1y`
`limit`	integer (query)	No	`20`	Number of countries to return (max: 100)

Response

Response (200 OK)JSON

{
"success": true,
"data": {
  "countries": [
    {
      "country_code": "US",
      "country_name": "United States",
      "visitors": 4521,
      "avg_value_score": 52.34
    },
    {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "visitors": 1823,
      "avg_value_score": 48.91
    },
    {
      "country_code": "DE",
      "country_name": "Germany",
      "visitors": 1456,
      "avg_value_score": 44.67
    },
    {
      "country_code": "FR",
      "country_name": "France",
      "visitors": 987,
      "avg_value_score": 39.12
    },
    {
      "country_code": "CA",
      "country_name": "Canada",
      "visitors": 832,
      "avg_value_score": 55.78
    }
  ]
},
"timestamp": "2026-02-07T12:00:00.000Z"
}

Response Fields

Field	Type	Description
`countries`	array	List of country statistics sorted by visitors descending
`countries[].country_code`	string	Two-letter ISO 3166-1 country code
`countries[].country_name`	string	Full country name
`countries[].visitors`	number	Total visitors from this country
`countries[].avg_value_score`	number	Average visitor value score (0-100)

TypeScript Interface

CountriesResponseTypeScript

interface CountryStat {
country_code: string;
country_name: string;
visitors: number;
avg_value_score: number;
}

interface CountriesResponse {
success: true;
data: {
  countries: CountryStat[];
};
timestamp: string;
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key does not have access to this website
404	Not Found - Website not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Code Examples

cURLBash

curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/a1b2c3d4-e5f6-7890-abcd-ef1234567890/countries?range=30d&limit=10' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

Error Handling

Error Response (500 Internal Server Error)JSON

{
"success": false,
"error": {
  "message": "Failed to fetch country data",
  "code": "INTERNAL_ERROR",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}