Skip to content

  Geography

Query analytics data by geographic information.

Countries

Group results by country code.

Returns a list of results with the 2 character ISO 3166-1 country code and the name of the country (in English) alongside requested metrics.

Top 10 countries over past week
<base>/stream/totals/countries?range=last_7_days&limit=10

"results": [
    {
        "country_code": "ZA",
        "country": "South Africa",
        "users": 564,
        "sessions": 989
    },
    {
        "country_code": "AU",
        "country": "Australia",
        "users": 11,
        "sessions": 25
    },
    ...
]

Regions

Group results by country "region" or province.

Uses the list of ISO3166-2 principal sub-divisions.

Top regions for Germany and UK over the past week
<base>/stream/totals/regions?range=last_7_days&countries=GB,DE

"results": [
    {
        "country": "United Kingdom",
        "country_code": "GB",
        "region": "England",
        "region_code": "ENG",
        "users": 2615,
    },
    {
        "country": "Germany",
        "country_code": "DE",
        "region": "Hesse",
        "region_code": "HE",
        "users": 233,
    },        

    {
        "country": "South Africa",
        "country_code": "ZA",
        "region": "Western Cape",
        "region_code": "WC",
        "users": 17026,
    },
    ...
]

Cities

Group results by city name.

Cities has no official list of codes, names used directly from IP lookup result.

Top cities in Sweden over the past week
<base>/stream/totals/cities?range=last_7_days&countries=SE

"results": [
    {
        "country": "Sweden",
        "country_code": "SE",
        "city": "Stockholm",
        "users": 13,
    },
    {
        "country": "Sweden",
        "country_code": "SE",
        "city": "Gothenburg",
        "users": 5,
    },    
    ...
]

Combined geography

Group results by combining country code, region code and city name.

Top combined results for past week
<base>/stream/totals/geo_combined?range=last_7_days    

"results": [
    {
        "country": "South Africa",
        "country_code": "ZA",
        "region": "Western Cape",
        "region_code": "WC",
        "city": "Cape Town",
        "users": 3304,
    },
    {
        "country": "Namibia",
        "country_code": "NA",
        "region": "Khomas",
        "region_code": "KH",
        "city": "Windhoek",
        "users": 3104,
    },        
    ...
]

UN Regions

Group results by combining the region and sub-region from the UN geoschema codes.

Top UN regions for past week
<base>/stream/totals/unregion_combined?range=last_7_days    

"results": [
    {
        "region": "Africa",
        "subregion": "Sub-Saharan Africa",
        "users": 119713,
    },
    {
        "region": "Europe",
        "subregion": "Northern Europe",
        "users": 3330,
    },
    ...
]

H3 Geopoints

Group results by their H3 cell ID. Allows rendering geographic density maps without relying on discrete latitude/longitude markers.

The API uses the level 5 resolution, dividing the globe into ~2m hexagonal cells of ±250 km2. Each cell is approximately 16km in diameter.

Top H3 cells for past week
<base>/stream/totals/h3geopoints?range=last_7_days    

"results": [
    {
        "h3geo_5": "85bcdc87fffffff",
        "users": 14984,
    },
    {
        "h3geo_5": "85bcc357fffffff",
        "users": 10943,
    },
    ...
]