Overview
The top_locations endpoint returns the top visiting countries ranked by number of visits. It supports pagination and optional comparison with the previous period.
Endpoint
GET https://api.tinybird.co/v0/pipes/top_locations.json
Parameters
Start date (YYYY-MM-DD format). Defaults to 7 days ago.
End date (YYYY-MM-DD format). Defaults to today.
Set to “true” to include previous period comparison and growth percentages
Skip for pagination (offset)
Limit for pagination (max results)
SQL Query
The endpoint aggregates location data from analytics_pages_mv:
SELECT
location,
uniqMerge(visits) as current_visits,
countMerge(hits) as current_hits
FROM analytics_pages_mv
WHERE date >= (SELECT current_start FROM date_calculations)
AND date <= (SELECT current_end FROM date_calculations)
{% if defined(tenant_id) %}
AND tenant_id = {{ String(tenant_id, description="Filter by tenant ID") }}
{% end %}
{% if defined(domain) %}
AND domain = {{ String(domain, description="Filter by domain") }}
{% end %}
GROUP BY location
Response
The country code or location identifier
Number of unique visits from this location
Total number of pageviews from this location
Previous period visits (only when include_previous_period=true)
Previous period pageviews (only when include_previous_period=true)
Percentage change in visits (only when include_previous_period=true)
Percentage change in pageviews (only when include_previous_period=true)
TypeScript Usage
import { createAnalyticsClient } from '@tinybirdco/analytics-client';
const tinybird = createAnalyticsClient();
// Get top 50 locations (default)
const result = await tinybird.query.topLocations();
result.data.forEach(location => {
console.log(`${location.location}: ${location.visits} visits, ${location.hits} pageviews`);
});
// Get top locations for a specific date range
const rangeResult = await tinybird.query.topLocations({
date_from: '2024-01-01',
date_to: '2024-01-31',
domain: 'example.com',
limit: 10
});
// Get top locations with previous period comparison
const comparisonResult = await tinybird.query.topLocations({
date_from: '2024-01-01',
date_to: '2024-01-07',
include_previous_period: 'true',
limit: 20
});
comparisonResult.data.forEach(location => {
console.log(`${location.location}: ${location.visits} visits (${location.visits_growth_percentage}% growth)`);
});
// Paginate through results
const page1 = await tinybird.query.topLocations({
skip: 0,
limit: 10
});
const page2 = await tinybird.query.topLocations({
skip: 10,
limit: 10
});
// Calculate top regions
const locationResult = await tinybird.query.topLocations({ limit: 10 });
const totalVisits = locationResult.data.reduce((sum, l) => sum + Number(l.visits), 0);
locationResult.data.forEach(location => {
const percentage = (Number(location.visits) / totalVisits * 100).toFixed(2);
console.log(`${location.location}: ${percentage}%`);
});
Example Response
Without Previous Period
{
"data": [
{
"location": "US",
"visits": 8234,
"hits": 18456
},
{
"location": "GB",
"visits": 3421,
"hits": 7865
},
{
"location": "DE",
"visits": 2876,
"hits": 6543
},
{
"location": "FR",
"visits": 2134,
"hits": 4987
}
]
}
With Previous Period
{
"data": [
{
"location": "US",
"visits": 8234,
"hits": 18456,
"previous_visits": 7654,
"previous_hits": 17234,
"visits_growth_percentage": 7.58,
"hits_growth_percentage": 7.09
},
{
"location": "GB",
"visits": 3421,
"hits": 7865,
"previous_visits": 2987,
"previous_hits": 6876,
"visits_growth_percentage": 14.53,
"hits_growth_percentage": 14.38
}
]
}
Notes
- Locations are typically represented as ISO 3166-1 alpha-2 country codes (e.g., “US”, “GB”, “DE”)
- Location data is derived from IP address geolocation
- Results are ordered by visits in descending order
- Use pagination parameters for large result sets
