Skip to main content
The Stats API provides comprehensive analytics for your links and workspaces. Track clicks, unique visitors, geographic data, device information, and more to understand how your shortened links are performing.

​
Base URL

https://api.taap.it/v1/stats
Retrieve detailed statistics for a specific link within a date range. 
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'

[
  {
    "id": "stat_123456789",
    "link_id": "link_987654321",
    "click_date": "2024-01-15",
    "total_clicks": 45,
    "unique_visitors": 38,
    "country_stats": {
      "US": 25,
      "CA": 12,
      "UK": 8
    },
    "device_stats": {
      "mobile": 28,
      "desktop": 15,
      "tablet": 2
    },
    "browser_stats": {
      "Chrome": 32,
      "Safari": 8,
      "Firefox": 3,
      "Edge": 2
    },
    "scans_only": 5,
    "created_at": "2024-01-16T00:00:00Z"
  }
]
​
link_id
string
required
Unique identifier for the link
​
start_date
string
Start date for statistics (YYYY-MM-DD or ISO datetime)
​
end_date
string
End date for statistics (YYYY-MM-DD or ISO datetime)
​
max_days
integer
default:"30"
Maximum allowed days between start and end date (1-30)
Get aggregated statistics for a link within a date range. 
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321/summary?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'

{
  "link_id": "link_987654321",
  "total_clicks": 1250,
  "top_countries": [
    {"name": "US", "count": 650},
    {"name": "CA", "count": 280},
    {"name": "UK", "count": 180},
    {"name": "DE", "count": 90},
    {"name": "FR", "count": 50}
  ],
  "top_devices": [
    {"name": "mobile", "count": 750},
    {"name": "desktop", "count": 400},
    {"name": "tablet", "count": 100}
  ],
  "top_browsers": [
    {"name": "Chrome", "count": 800},
    {"name": "Safari", "count": 250},
    {"name": "Firefox", "count": 120},
    {"name": "Edge", "count": 80}
  ],
  "qr_code_usage": 45,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}
​
link_id
string
required
Unique identifier for the link
​
start_date
string
Start date for summary (YYYY-MM-DD or ISO datetime)
​
end_date
string
End date for summary (YYYY-MM-DD or ISO datetime)
​
max_days
integer
default:"30"
Maximum allowed days between start and end date (1-30)

​
Workspace Statistics

​
Get Workspace Stats

Retrieve detailed statistics for a specific workspace within a date range. 
curl -X GET 'https://api.taap.it/v1/stats/workspaces/ws_123456789?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'

[
  {
    "id": "ws_stat_123456789",
    
    "click_date": "2024-01-15",
    "total_clicks": 1250,
    "unique_visitors": 980,
    "country_stats": {
      "US": 650,
      "CA": 280,
      "UK": 180,
      "DE": 90
    },
    "device_stats": {
      "mobile": 750,
      "desktop": 400,
      "tablet": 100
    },
    "browser_stats": {
      "Chrome": 800,
      "Safari": 250,
      "Firefox": 120,
      "Edge": 80
    },
    "scans_only": 45,
    "created_at": "2024-01-16T00:00:00Z"
  }
]
​
workspace_id
string
required
Unique identifier for the workspace
​
start_date
string
Start date for statistics (YYYY-MM-DD or ISO datetime)
​
end_date
string
End date for statistics (YYYY-MM-DD or ISO datetime)
​
max_days
integer
default:"30"
Maximum allowed days between start and end date (1-30)

​
Get Workspace Stats Summary

Get aggregated statistics for a workspace within a date range. 
curl -X GET 'https://api.taap.it/v1/stats/workspaces/ws_123456789/summary?start_date=2024-01-01&end_date=2024-01-31' \
  -H 'Authorization: Bearer taapit_your_api_key_here'

{
  
  "total_clicks": 15750,
  "top_countries": [
    {"name": "US", "count": 8250},
    {"name": "CA", "count": 3150},
    {"name": "UK", "count": 2250},
    {"name": "DE", "count": 1200},
    {"name": "FR", "count": 900}
  ],
  "top_devices": [
    {"name": "mobile", "count": 9450},
    {"name": "desktop", "count": 5250},
    {"name": "tablet", "count": 1050}
  ],
  "top_browsers": [
    {"name": "Chrome", "count": 10200},
    {"name": "Safari", "count": 3150},
    {"name": "Firefox", "count": 1800},
    {"name": "Edge", "count": 600}
  ],
  "qr_code_usage": 525,
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}
​
workspace_id
string
required
Unique identifier for the workspace
​
start_date
string
Start date for summary (YYYY-MM-DD or ISO datetime)
​
end_date
string
End date for summary (YYYY-MM-DD or ISO datetime)
​
max_days
integer
default:"30"
Maximum allowed days between start and end date (1-30)

​
Date Range Handling

The Stats API automatically handles date ranges with the following behavior:

​
Auto Date Range

If you provide only a start_date, the API automatically sets the end_date to 30 days later: 
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321?start_date=2024-01-01' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
This is equivalent to: 
curl -X GET 'https://api.taap.it/v1/stats/links/link_987654321?start_date=2024-01-01&end_date=2024-01-31'

​
Date Range Validation

  • Maximum range: 30 days
  • Start date cannot be after end date
  • Dates can be in YYYY-MM-DD format or full ISO datetime format
{
  "detail": "Date range cannot exceed 30 days. Current range: 45 days"
}

​
Analytics Data Structure

​
Country Statistics

Country data is provided as a dictionary with country codes and click counts: 
{
  "country_stats": {
    "US": 650,
    "CA": 280,
    "UK": 180,
    "DE": 90,
    "FR": 50
  }
}

​
Device Statistics

Device types tracked include mobile, desktop, and tablet: 
{
  "device_stats": {
    "mobile": 750,
    "desktop": 400,
    "tablet": 100
  }
}

​
Browser Statistics

Popular browsers are tracked with their usage counts: 
{
  "browser_stats": {
    "Chrome": 800,
    "Safari": 250,
    "Firefox": 120,
    "Edge": 80,
    "Other": 50
  }
}

​
Analytics Use Cases

​
Campaign Performance Tracking

Track the performance of marketing campaigns: 
// Get campaign performance
async function getCampaignStats(campaignLinks) {
  const stats = await Promise.all(
    campaignLinks.map(link => 
      fetch(`/v1/stats/links/${link.id}/summary?start_date=2024-01-01&end_date=2024-01-31`)
    )
  );
  
  return stats.reduce((total, stat) => ({
    total_clicks: total.total_clicks + stat.total_clicks
  }), { total_clicks: 0 });
}

​
Geographic Analysis

Analyze where your traffic is coming from: 
// Geographic analysis
async function analyzeGeographicData(workspaceId) {
  const stats = await fetch(
    `/v1/stats/workspaces/${workspaceId}/summary?start_date=2024-01-01&end_date=2024-01-31`
  ).then(r => r.json());
  
  const topCountries = stats.top_countries.map(country => ({
    country: country.name,
    percentage: (country.count / stats.total_clicks * 100).toFixed(2) + '%',
    clicks: country.count
  }));
  
  return topCountries;
}
Track device and browser usage patterns: 
# Device and browser trends
def analyze_device_trends(link_id):
    stats = requests.get(
        f'/v1/stats/links/{link_id}/summary',
        params={'start_date': '2024-01-01', 'end_date': '2024-01-31'},
        headers={'Authorization': f'Bearer {api_key}'}
    ).json()
    
    device_breakdown = {
        'mobile_percentage': stats['top_devices'][0]['count'] / stats['total_clicks'] * 100,
        'desktop_percentage': stats['top_devices'][1]['count'] / stats['total_clicks'] * 100,
        'tablet_percentage': stats['top_devices'][2]['count'] / stats['total_clicks'] * 100
    }
    
    return device_breakdown

​
Error Responses

{
  "detail": "Date range cannot exceed 30 days. Current range: 45 days"
}

{
  "detail": "Access denied to this link"
}

{
  "detail": "No stats found for this link"
}

​
Rate Limits

  • Plan-based Rate Limits: Rate limits vary based on your subscription plan
  • Stats operations: 500 requests per hour per resource

​
Best Practices

  • Use summary endpoints for high-level overviews
  • Use detailed stats for granular analysis
  • Combine link and workspace stats for comprehensive insights
  • Monitor trends over time with regular data collection
  • Cache frequently accessed analytics data
  • Use appropriate date ranges to limit data transfer
  • Implement pagination for large datasets
  • Schedule regular analytics updates rather than real-time polling
  • Analyze total clicks to understand link engagement
  • Analyze geographic data for market expansion opportunities
  • Monitor device trends for mobile optimization
  • Track browser usage for compatibility considerations

​
Real-time Analytics

While the Stats API provides historical data, for real-time analytics:
  1. Use Link Access Tracking: The /links/code/{code} endpoint automatically tracks clicks
  2. Implement Webhooks: Set up webhooks for real-time click notifications
  3. Polling Strategy: Poll stats endpoints at regular intervals for near real-time updates

Next: Workspaces

Learn how to manage workspaces and team collaboration features.