Analytics API

Track and analyze QR code performance with detailed scan data, geographic information, device breakdowns, and trend analysis.

Scan Trends

Track scans over time with daily, weekly, or monthly breakdowns

Geographic Data

See where your QR codes are being scanned by country and city

Device Info

Understand device types, operating systems, and browsers

Referrer Data

Track where scans originate from for campaign attribution

Endpoints

Method	Endpoint	Description
GET	/organizations/:orgId/qr-codes/analytics	Organization-wide analytics
GET	/organizations/:orgId/qr-codes/:id/analytics	Single QR code analytics
GET	/organizations/:orgId/qr-codes/:id/analytics/export	Export analytics as CSV
GET	/organizations/:orgId/qr-codes/:id/scans	Get individual scan records

Get QR Code Analytics

Retrieve comprehensive analytics for a specific QR code.

GET

/organizations/:orgId/qr-codes/:id/analytics

Query Parameters

Parameter	Type	Description
startDate	string	Start date (ISO 8601 format)
endDate	string	End date (ISO 8601 format)
interval	string	Grouping interval: day, week, month

Example Request

curl -X GET \
  "https://i-love-qr-production-645dbff8d2fe.herokuapp.com/api/v1/organizations/org_abc123/qr-codes/qr_xyz789/analytics?startDate=2024-01-01&endDate=2024-01-31&interval=day" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "qrCodeId": "qr_xyz789",
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "summary": {
    "totalScans": 1542,
    "uniqueScans": 1203,
    "avgDailyScans": 49.7
  },
  "timeline": [
    { "date": "2024-01-01", "scans": 45, "uniqueScans": 38 },
    { "date": "2024-01-02", "scans": 52, "uniqueScans": 41 },
    ...
  ],
  "geography": {
    "countries": [
      { "country": "US", "scans": 823, "percentage": 53.4 },
      { "country": "GB", "scans": 234, "percentage": 15.2 },
      { "country": "DE", "scans": 156, "percentage": 10.1 }
    ],
    "cities": [
      { "city": "New York", "country": "US", "scans": 234 },
      { "city": "London", "country": "GB", "scans": 189 },
      { "city": "Los Angeles", "country": "US", "scans": 145 }
    ]
  },
  "devices": {
    "types": [
      { "type": "mobile", "scans": 1234, "percentage": 80.0 },
      { "type": "desktop", "scans": 231, "percentage": 15.0 },
      { "type": "tablet", "scans": 77, "percentage": 5.0 }
    ],
    "os": [
      { "os": "iOS", "scans": 687, "percentage": 44.6 },
      { "os": "Android", "scans": 547, "percentage": 35.5 },
      { "os": "Windows", "scans": 189, "percentage": 12.3 }
    ],
    "browsers": [
      { "browser": "Safari", "scans": 654, "percentage": 42.4 },
      { "browser": "Chrome", "scans": 521, "percentage": 33.8 },
      { "browser": "Firefox", "scans": 156, "percentage": 10.1 }
    ]
  }
}

Geographic Analytics

The analytics response includes detailed geographic breakdown of scans by country and city. This data is derived from IP geolocation of scan requests.

Available Geographic Data

• Country: ISO country code and scan count
• City: City name with country context
• Percentage: Relative distribution of scans
• Coordinates: Approximate lat/lng (when available)

Privacy Note: We don't store exact user locations. Geographic data is derived from IP addresses and provides approximate city-level accuracy.

Export Analytics

Export analytics data as CSV for further analysis in spreadsheets or BI tools.

GET

/organizations/:orgId/qr-codes/:id/analytics/export

Export to CSV

curl -X GET \
  "https://i-love-qr-production-645dbff8d2fe.herokuapp.com/api/v1/organizations/org_abc123/qr-codes/qr_xyz789/analytics/export?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o analytics.csv

CSV Columns

Column	Description
timestamp	Scan timestamp (ISO 8601)
country	Country code
city	City name
device_type	mobile, desktop, tablet
os	Operating system
browser	Browser name
is_unique	First-time scan (true/false)

Organization-wide Analytics

Get aggregated analytics across all QR codes in your organization.

GET

/organizations/:orgId/qr-codes/analytics

curl -X GET \
  "https://i-love-qr-production-645dbff8d2fe.herokuapp.com/api/v1/organizations/org_abc123/qr-codes/analytics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: YOUR_API_KEY"

Next Steps

Learn about related features: