Skip to main content
The geographic data endpoint provides insights into where your redirect traffic originates, with the ability to group results by country, region, or city.

​
Endpoint

GET /analytics/redirect/:redirectId/stats/geo

​
Function signature

getGeographicData(
  redirectId: string,
  params?: { start?: string; end?: string; groupBy?: string }
): Promise<AxiosResponse>

​
Path parameters

​
redirectId
string
required
The unique identifier of the redirect to retrieve geographic data for

​
Query parameters

​
start
string
Start date for the analytics period in ISO 8601 formatExample: 2024-01-01T00:00:00Z
​
end
string
End date for the analytics period in ISO 8601 formatExample: 2024-01-31T23:59:59Z
​
groupBy
string
Geographic dimension to group results byAvailable values:
  • country - Group by country (default)
  • region - Group by region/state
  • city - Group by city
Geographic data is determined using IP geolocation. Accuracy varies by location, with city-level data being less precise than country-level.

​
Response

The endpoint returns an array of geographic locations with hit counts:
​
data
object
​
meta
object

​
Example request

import { getGeographicData } from '@quickleap/api';

// Get country-level geographic data
const response = await getGeographicData('redirect_abc123', {
  start: '2024-01-01T00:00:00Z',
  end: '2024-01-31T23:59:59Z',
  groupBy: 'country'
});

const { locations, summary } = response.data.data;

console.log(`Traffic from ${summary.totalLocations} countries`);
console.log(`Top country: ${summary.topLocation}`);

// Display top 5 countries
locations.slice(0, 5).forEach(location => {
  console.log(`${location.name}: ${location.hits} hits (${location.percentage}%)`);
});

​
Example response

{
  "data": {
    "locations": [
      {
        "code": "US",
        "name": "United States",
        "hits": 18542,
        "uniqueVisitors": 5234,
        "percentage": 40.6,
        "coordinates": {
          "latitude": 37.0902,
          "longitude": -95.7129
        }
      },
      {
        "code": "GB",
        "name": "United Kingdom",
        "hits": 8932,
        "uniqueVisitors": 2876,
        "percentage": 19.5,
        "coordinates": {
          "latitude": 51.5074,
          "longitude": -0.1278
        }
      },
      {
        "code": "DE",
        "name": "Germany",
        "hits": 6234,
        "uniqueVisitors": 1987,
        "percentage": 13.6,
        "coordinates": {
          "latitude": 51.1657,
          "longitude": 10.4515
        }
      }
    ],
    "summary": {
      "totalLocations": 87,
      "topLocation": "United States",
      "coverage": 98.3
    }
  },
  "meta": {
    "redirectId": "redirect_abc123",
    "groupBy": "country",
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    }
  }
}

​
Use cases

  • Geographic visualization: Create interactive maps showing traffic distribution
  • Localization: Identify which regions need localized content or redirects
  • CDN optimization: Determine optimal CDN edge locations for your traffic
  • Compliance: Ensure geographic data handling complies with regional regulations
  • Market analysis: Understand which geographic markets drive the most traffic
  • Fraud detection: Identify unusual geographic patterns that may indicate abuse

​
Best practices

  • Start with countries: Begin analysis at the country level before drilling down to regions or cities
  • Handle unknowns: Some traffic may not have geographic data (VPNs, privacy tools). Check the coverage field
  • Combine with other metrics: Cross-reference geographic data with device, browser, or referrer analytics
  • Coordinate visualization: Use the provided coordinates to plot locations on maps