Analytics API - Lookup Usage Insights

Overview

The Analytics API provides comprehensive insights into your phone number lookup usage. Understand your traffic patterns, identify spam rates, see geographic distribution, and track trends over time.

Key Metrics

• Carrier Type Breakdown: WIRELESS, PCS, CLEC, VOIP, LANDLINE distribution
• Top Carriers: Actual carrier names (AT&T, Verizon, T-Mobile, etc.) with counts
• Spam Analysis: CLEAN, SPAM, SCAM, ROBOCALL percentages
• Geographic Distribution: Top U.S. states by lookup count
• Trends: Daily lookup volume with spam counts over time

Authentication

All API requests require authentication using your API key. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Don't have an API key? Get your API key here.

Endpoint

Example Requests

# Get 30-day analytics (default)
GET https://api-service.verirouteintel.io/api/v1/analytics

# Get 7-day analytics
GET https://api-service.verirouteintel.io/api/v1/analytics?preset=7d

# Get 90-day analytics
GET https://api-service.verirouteintel.io/api/v1/analytics?preset=90d

# Custom date range
GET https://api-service.verirouteintel.io/api/v1/analytics?start_date=2025-12-01&end_date=2025-12-26

Parameters

Response Format

Success Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-11-26",
      "end": "2025-12-26"
    },
    "total_lookups": 847,
    "carrier_type_breakdown": {
      "WIRELESS": 567,
      "CLEC": 142,
      "VOIP": 89,
      "PCS": 49
    },
    "spam_breakdown": {
      "CLEAN": 652,
      "SPAM": 127,
      "SCAM": 45,
      "ROBOCALL": 23
    },
    "geographic_breakdown": {
      "CA": 156,
      "TX": 112,
      "FL": 89,
      "NY": 67,
      "IL": 45
    },
    "trends": [
      {"date": "2025-12-25", "count": 45, "spam_count": 5},
      {"date": "2025-12-24", "count": 52, "spam_count": 8},
      {"date": "2025-12-23", "count": 61, "spam_count": 12}
    ]
  }
}

Response Fields

Carrier Types

• WIRELESS - Mobile/cellular carriers
• PCS - Personal Communications Service
• CLEC - Competitive Local Exchange Carrier
• VOIP - Voice over IP providers
• LANDLINE - Traditional landline numbers

Spam Categories

• CLEAN - No spam detected
• SPAM - Known spam number
• SCAM - Fraudulent caller
• ROBOCALL - Automated calling system

Code Examples

cURL

# Get 30-day analytics
curl -X GET "https://api-service.verirouteintel.io/api/v1/analytics" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get 7-day analytics
curl -X GET "https://api-service.verirouteintel.io/api/v1/analytics?preset=7d" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Custom date range
curl -X GET "https://api-service.verirouteintel.io/api/v1/analytics?start_date=2025-12-01&end_date=2025-12-26" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api-service.verirouteintel.io"

def get_analytics(preset="30d", start_date=None, end_date=None):
    """Get lookup analytics for your account."""
    headers = {"Authorization": f"Bearer {API_KEY}"}

    params = {}
    if start_date and end_date:
        params["start_date"] = start_date
        params["end_date"] = end_date
    else:
        params["preset"] = preset

    response = requests.get(
        f"{BASE_URL}/api/v1/analytics",
        headers=headers,
        params=params
    )
    return response.json()

# Get 30-day analytics
analytics = get_analytics()
print(f"Total lookups: {analytics['data']['total_lookups']}")
print(f"Spam rate: {sum(analytics['data']['spam_breakdown'].get(k, 0) for k in ['SPAM', 'SCAM', 'ROBOCALL']) / analytics['data']['total_lookups'] * 100:.1f}%")

# Get carrier breakdown
for carrier_type, count in analytics['data']['carrier_type_breakdown'].items():
    print(f"  {carrier_type}: {count}")

# Get 7-day analytics
weekly = get_analytics(preset="7d")

# Custom date range
custom = get_analytics(start_date="2025-12-01", end_date="2025-12-15")

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api-service.verirouteintel.io';

async function getAnalytics(options = {}) {
  const { preset = '30d', startDate, endDate } = options;

  const params = startDate && endDate
    ? { start_date: startDate, end_date: endDate }
    : { preset };

  const response = await axios.get(`${BASE_URL}/api/v1/analytics`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` },
    params
  });

  return response.data;
}

// Get 30-day analytics
const analytics = await getAnalytics();
console.log(`Total lookups: ${analytics.data.total_lookups}`);

// Calculate spam rate
const spamCount = ['SPAM', 'SCAM', 'ROBOCALL'].reduce(
  (sum, key) => sum + (analytics.data.spam_breakdown[key] || 0), 0
);
const spamRate = (spamCount / analytics.data.total_lookups * 100).toFixed(1);
console.log(`Spam rate: ${spamRate}%`);

// Get weekly analytics
const weekly = await getAnalytics({ preset: '7d' });

// Custom date range
const custom = await getAnalytics({
  startDate: '2025-12-01',
  endDate: '2025-12-15'
});

Error Handling

The API returns standard HTTP status codes and detailed error messages:

403 Upgrade Required

Returned when a free user attempts to access analytics:

{
  "success": false,
  "error": "Analytics is available for paid users only. Please upgrade your account.",
  "code": "UPGRADE_REQUIRED"
}

400 Invalid Date Format

Returned when date parameters are invalid:

{
  "success": false,
  "error": "Invalid date format: time data '12-01-2025' does not match format '%Y-%m-%d'. Use YYYY-MM-DD.",
  "code": "INVALID_DATE_FORMAT"
}

401 Unauthorized

Returned when API key is missing or invalid:

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Rate Limits

The Analytics API has the following rate limits:

• 60 requests per hour
• 10 requests per minute

429 Too Many Requests

When rate limits are exceeded, the API returns a 429 status code:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before making another request.",
  "retry_after": 60
}

FAQs