GET
https://jmpy.me/api/v1
/
analytics
/
referrers
Referrer Analytics
curl --request GET \
  --url https://jmpy.me/api/v1/analytics/referrers \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "referrer": "<string>",
      "source_category": "<string>",
      "clicks": 123,
      "unique_visitors": 123,
      "percentage": 123
    }
  ],
  "traffic_sources": {
    "social": 123,
    "search": 123,
    "direct": 123,
    "other": 123
  },
  "category_totals": {}
}
Get detailed traffic source analysis showing where your clicks are coming from, including social media platforms, search engines, and direct traffic.
This endpoint returns user-level aggregated referrer data. Traffic is automatically categorized into sources like social media, search engines, messaging apps, and direct traffic.

Query Parameters

days
integer
default:30
Number of days to include in analytics (1-365).
dateRange
string
Predefined date range: 7d, 30d, 90d, 1y, all_time, custom. Takes precedence over days if specified.
startDate
string
Start date for custom range (ISO 8601). Required when dateRange is custom.
endDate
string
End date for custom range (ISO 8601). Required when dateRange is custom.

Response

data
array
Array of referrer records.
traffic_sources
object
Aggregated traffic by category.
category_totals
object
Detailed breakdown by category with clicks, unique visitors, and percentage.

Request Examples

# Get referrer data for last 30 days
curl -X GET "https://jmpy.me/api/v1/analytics/referrers?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get referrer data for last 7 days
curl -X GET "https://jmpy.me/api/v1/analytics/referrers?dateRange=7d" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Custom date range
curl -X GET "https://jmpy.me/api/v1/analytics/referrers?dateRange=custom&startDate=2024-01-01&endDate=2024-03-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

{
  "success": true,
  "data": {
    "data": [
      {
        "referrer": "Direct",
        "source_category": "Direct",
        "clicks": 1890,
        "unique_visitors": 1654,
        "percentage": 41.8
      },
      {
        "referrer": "https://google.com",
        "source_category": "Google",
        "clicks": 1234,
        "unique_visitors": 1098,
        "percentage": 27.3
      },
      {
        "referrer": "https://twitter.com",
        "source_category": "Twitter",
        "clicks": 567,
        "unique_visitors": 489,
        "percentage": 12.5
      },
      {
        "referrer": "https://facebook.com",
        "source_category": "Facebook",
        "clicks": 432,
        "unique_visitors": 398,
        "percentage": 9.5
      },
      {
        "referrer": "https://linkedin.com",
        "source_category": "LinkedIn",
        "clicks": 234,
        "unique_visitors": 212,
        "percentage": 5.2
      },
      {
        "referrer": "https://example-blog.com",
        "source_category": "Other",
        "clicks": 166,
        "unique_visitors": 143,
        "percentage": 3.7
      }
    ],
    "traffic_sources": {
      "social": 1233,
      "search": 1234,
      "direct": 1890,
      "other": 166
    },
    "category_totals": {
      "Direct": {
        "clicks": 1890,
        "unique_visitors": 1654,
        "percentage": 41.8
      },
      "Google": {
        "clicks": 1234,
        "unique_visitors": 1098,
        "percentage": 27.3
      },
      "Twitter": {
        "clicks": 567,
        "unique_visitors": 489,
        "percentage": 12.5
      },
      "Facebook": {
        "clicks": 432,
        "unique_visitors": 398,
        "percentage": 9.5
      },
      "LinkedIn": {
        "clicks": 234,
        "unique_visitors": 212,
        "percentage": 5.2
      },
      "Other": {
        "clicks": 166,
        "unique_visitors": 143,
        "percentage": 3.7
      }
    }
  }
}

Traffic Source Categories

The API automatically categorizes referrers into the following sources:
CategoryPlatforms
Social MediaFacebook, Twitter, LinkedIn, Instagram, YouTube, TikTok, Reddit, Pinterest
MessagingWhatsApp, Telegram, Discord
Search EnginesGoogle, Bing, Yahoo, DuckDuckGo
DirectNo referrer (typed URL, bookmarks, etc.)
OtherAny other referring domain

Use Cases

Compare performance across different marketing channels to optimize spend.
async function analyzeChannelROI() {
  const response = await fetch(
    'https://jmpy.me/api/v1/analytics/referrers?days=30',
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const { data } = await response.json();
  
  const sources = data.traffic_sources;
  const total = Object.values(sources).reduce((a, b) => a + b, 0);
  
  // Calculate cost per click for each channel (example data)
  const channelCosts = {
    social: { spend: 500, name: 'Social Media Ads' },
    search: { spend: 300, name: 'Search Ads' },
    direct: { spend: 0, name: 'Direct/Organic' },
    other: { spend: 100, name: 'Other Campaigns' }
  };
  
  console.log('Channel ROI Analysis (Last 30 Days)');
  console.log('=====================================');
  
  Object.entries(sources).forEach(([channel, clicks]) => {
    const cost = channelCosts[channel];
    const cpc = cost.spend > 0 ? (cost.spend / clicks).toFixed(2) : 'Free';
    const share = ((clicks / total) * 100).toFixed(1);
    
    console.log(`${cost.name}:`);
    console.log(`  Clicks: ${clicks} (${share}%)`);
    console.log(`  Cost: $${cost.spend}`);
    console.log(`  CPC: $${cpc}`);
    console.log('');
  });
}
Build a dashboard showing social media traffic breakdown.
interface SocialMetrics {
  platform: string;
  clicks: number;
  uniqueVisitors: number;
  percentage: number;
  trend: 'up' | 'down' | 'stable';
}

async function getSocialMetrics(): Promise<SocialMetrics[]> {
  const socialPlatforms = [
    'Facebook', 'Twitter', 'LinkedIn', 'Instagram', 
    'YouTube', 'TikTok', 'Reddit', 'Pinterest'
  ];
  
  const response = await fetch(
    'https://jmpy.me/api/v1/analytics/referrers?days=30',
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const { data } = await response.json();
  
  return data.data
    .filter(ref => socialPlatforms.includes(ref.source_category))
    .map(ref => ({
      platform: ref.source_category,
      clicks: ref.clicks,
      uniqueVisitors: ref.unique_visitors,
      percentage: ref.percentage,
      trend: 'stable' as const // Would compare with previous period
    }))
    .sort((a, b) => b.clicks - a.clicks);
}
Find and analyze traffic from unexpected sources.
import requests

def find_unknown_referrers():
    known_sources = {
        'Facebook', 'Twitter', 'LinkedIn', 'Instagram', 'YouTube',
        'TikTok', 'Reddit', 'Pinterest', 'WhatsApp', 'Telegram',
        'Discord', 'Google', 'Bing', 'Yahoo', 'DuckDuckGo', 'Direct'
    }
    
    response = requests.get(
        'https://jmpy.me/api/v1/analytics/referrers',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params={'days': 30}
    )
    
    referrers = response.json()['data']['data']
    
    # Find referrers categorized as "Other"
    unknown = [
        ref for ref in referrers 
        if ref['source_category'] == 'Other'
    ]
    
    print("Unknown/Other Referrers:")
    print("=" * 50)
    
    for ref in sorted(unknown, key=lambda x: -x['clicks']):
        print(f"\n{ref['referrer']}:")
        print(f"  Clicks: {ref['clicks']}")
        print(f"  Unique Visitors: {ref['unique_visitors']}")
        print(f"  Share: {ref['percentage']}%")
        
        # Potential action
        if ref['clicks'] > 100:
            print("  ⚠️  High traffic - consider adding to known sources")