Skip to main content
The referrer data endpoint provides insights into the sources of your redirect traffic, showing which websites, social media platforms, search engines, or campaigns are driving visitors to your redirects.

​
Endpoint

GET /analytics/redirect/:redirectId/stats/referrers

​
Function signature

getReferrerData(
  redirectId: string,
  params?: { start?: string; end?: string; limit?: number }
): Promise<AxiosResponse>

​
Path parameters

​
redirectId
string
required
The unique identifier of the redirect to retrieve referrer 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
​
limit
number
Maximum number of referrers to return. Results are ordered by hit count descending.Default: 100Maximum: 1000
Referrer data is collected from the HTTP Referer header. Some browsers and privacy tools may block or modify this header, resulting in “direct” or “unknown” traffic.

​
Response

The endpoint returns a list of referrers ordered by traffic volume:
​
data
object
​
meta
object

​
Example request

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

const response = await getReferrerData('redirect_abc123', {
  start: '2024-01-01T00:00:00Z',
  end: '2024-01-31T23:59:59Z',
  limit: 50
});

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

console.log(`Total referrers: ${summary.totalReferrers}`);
console.log(`Direct traffic: ${summary.directTraffic}%`);
console.log(`Search traffic: ${summary.searchTraffic}%`);
console.log(`Social traffic: ${summary.socialTraffic}%`);

// Display top 10 referrers
console.log('\nTop 10 Referrers:');
referrers.slice(0, 10).forEach((ref, index) => {
  console.log(`${index + 1}. ${ref.domain} - ${ref.hits} hits (${ref.percentage}%)`);
});

​
Example response

{
  "data": {
    "referrers": [
      {
        "url": "direct",
        "domain": "direct",
        "type": "direct",
        "hits": 15678,
        "uniqueVisitors": 8234,
        "percentage": 34.3
      },
      {
        "url": "https://www.google.com/search",
        "domain": "google.com",
        "type": "search",
        "hits": 12456,
        "uniqueVisitors": 6789,
        "percentage": 27.3
      },
      {
        "url": "https://twitter.com",
        "domain": "twitter.com",
        "type": "social",
        "hits": 8932,
        "uniqueVisitors": 4567,
        "percentage": 19.5
      },
      {
        "url": "https://www.linkedin.com",
        "domain": "linkedin.com",
        "type": "social",
        "hits": 4234,
        "uniqueVisitors": 2345,
        "percentage": 9.3
      },
      {
        "url": "https://example.com/blog",
        "domain": "example.com",
        "type": "website",
        "hits": 2876,
        "uniqueVisitors": 1456,
        "percentage": 6.3
      }
    ],
    "summary": {
      "totalReferrers": 287,
      "directTraffic": 34.3,
      "searchTraffic": 32.8,
      "socialTraffic": 24.5,
      "topReferrer": {
        "domain": "direct",
        "hits": 15678
      }
    }
  },
  "meta": {
    "redirectId": "redirect_abc123",
    "limit": 50,
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    }
  }
}

​
Use cases

  • Attribution tracking: Understand which marketing channels drive the most traffic
  • Content strategy: Identify which content pieces or partners send the most visitors
  • SEO analysis: Monitor search engine referral traffic and identify opportunities
  • Social media ROI: Measure the impact of social media campaigns
  • Partner tracking: Track traffic from partner websites and affiliates
  • Campaign analysis: Combine with UTM parameters for detailed campaign attribution

​
Best practices

  • Handle direct traffic: High direct traffic may indicate mobile apps, bookmarks, or privacy-conscious users
  • Group similar referrers: Combine subdomains (e.g., m.facebook.com and www.facebook.com) for clearer insights
  • Monitor changes: Track referrer distribution over time to spot new traffic sources or lost partnerships
  • UTM parameters: Use campaign analytics endpoint for more granular tracking of marketing campaigns
  • Privacy considerations: Be aware that referrer blocking is increasingly common for privacy reasons

​
Referrer types

The API automatically categorizes referrers into the following types:
  • search: Traffic from search engines (Google, Bing, DuckDuckGo, etc.)
  • social: Traffic from social media platforms (Twitter, Facebook, LinkedIn, etc.)
  • direct: No referrer information (typed URL, bookmark, mobile app, etc.)
  • email: Traffic from email clients (when detectable)
  • paid: Traffic from known advertising platforms
  • website: Traffic from other websites
  • unknown: Unable to categorize