API Documentation

The Tinylytics API provides programmatic access to your analytics data. Perfect for building custom dashboards, integrations, or automated reporting.

Quick Start

Base URL: https://tinylytics.app/api/v1/

Authentication: Include your API key in the Authorization header:

Authorization: Bearer tly-ro-your-api-key-here

Get an API Key: Account Settings → API Access → Create New API Key

Endpoints

GET /me

Test your API key and get account information.

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/me

GET /sites

List all your sites.

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites

GET /sites/:id

Get details for a specific site.

curl -H "Authorization: Bearer tly-ro-your-api-key" \
  https://tinylytics.app/api/v1/sites/456

GET /sites/:id/hits

Get analytics data for a site with filtering and grouping options.

Key Parameters:

• start_date / end_date - Date range (YYYY-MM-DD, max 365 days)
• country - Filter by country code (e.g., “US”, “GB”)
• path - Filter by exact path (e.g., “/blog/post”)
• referrer - Filter by referrer (partial match)
• grouped=true - Return aggregated data
• group_by - Group by: path, country, referrer, browser_name, platform_name
• page / per_page - Pagination (max 1000 per page)

GET /sites/:id/leaderboard

Get a leaderboard of all paths for a site, ranked by total hits with caching for performance.

Key Parameters:

• path - Filter paths containing this term (case-insensitive, partial match)
• page / per_page - Pagination (max 1000 per page)

Features:

• Returns all-time data (no date filtering)
• Includes total hits, unique hits, and percentage of site traffic
• 1-hour caching for optimal performance
• Separate cache for filtered vs unfiltered results

Examples

Basic Analytics

# Last 7 days of hits
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?start_date=2023-05-28&end_date=2023-06-04"

# Filter by country and path
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?country=US&path=/blog"

Grouped Analytics

# Most popular pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=path"

# Top traffic sources
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=referrer"

# Geographic distribution
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/hits?grouped=true&group_by=country"

Leaderboard

# All-time top pages
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard"

# Filter blog posts only
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard?path=blog"

# Paginated results
curl -H "Authorization: Bearer tly-ro-your-api-key" \
  "https://tinylytics.app/api/v1/sites/456/leaderboard?page=2&per_page=50"

Response Format

Individual Hits

{
  "hits": [
    {
      "id": 789012,
      "url": "https://example.com/blog/my-post",
      "path": "/blog/my-post",
      "referrer": "https://twitter.com",
      "country": "US",
      "browser_name": "Chrome",
      "platform_name": "macOS",
      "is_mobile": false,
      "created_at": "2023-06-04T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 1547,
    "total_pages": 16
  }
}

Grouped Data

{
  "grouped_hits": [
    {
      "path": "/blog/popular-post",
      "hit_count": 247
    },
    {
      "path": "/",
      "hit_count": 156
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 25,
    "total_pages": 1
  }
}

Leaderboard Data

{
  "leaderboard": [
    {
      "path": "/blog/popular-post",
      "total_hits": 1250,
      "unique_hits": 890,
      "percentage": 15.2
    },
    {
      "path": "/about",
      "total_hits": 800,
      "unique_hits": 650,
      "percentage": 9.7
    }
  ],
  "site": {
    "id": 456,
    "uid": "abc123",
    "url": "https://example.com",
    "label": "My Blog"
  },
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 245,
    "total_pages": 3
  },
  "cache_info": {
    "cached_at": "2024-01-01T12:00:00Z",
    "expires_at": "2024-01-01T13:00:00Z"
  },
  "filters": {
    "path": "blog"
  }
}

Common Use Cases

Custom Dashboard: Combine /sites and /sites/:id/hits to build analytics dashboards

Traffic Monitoring: Fetch daily hits and compare against historical data for automated alerts

Content Analysis: Use grouped data to identify popular pages, top referrers, and audience demographics

Performance Insights: Group by browser, platform, or country for technical and geographic analytics

Top Content Discovery: Use /sites/:id/leaderboard to find your most popular content across all time

Content Strategy: Filter leaderboard by path segments (e.g., “/blog”, “/product”) to analyze specific content types

Error Handling

Error Response:

{
  "error": "API access requires an active subscription"
}

Rate Limits

API requests are subject to reasonable rate limits. If exceeded, you’ll receive a 429 status code.

Need Help?

Contact us at [email protected] for API questions or implementation assistance. We aim to respond within 24 hours.