Analytics

The QRCodeKIT API provides a powerful analytics query system to help you understand how your QR codes are performing. You can query analytics data with flexible metrics, dimensions, and filters.

Analytics features are only available for Enterprise plans. Contact our sales team to upgrade your plan and access detailed analytics.

Overview

The analytics system allows you to:

Query visit data - Get total and unique visits for your QR codes
Filter by QR codes - Analyze specific QR codes or groups
Group by dimensions - Break down data by time, geography, devices, etc.
Set date ranges - Analyze data for specific time periods

Analytics Query Endpoint

All analytics queries use the /api/analytics/query endpoint:

bash

curl 'https://api.v2.qrcodekit.com/api/analytics/query' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": {
      "start": "2025-07-23 00:00:00",
      "end": "2025-08-22 23:59:59",
      "interval": "1d"
    },
    "metrics": ["visits:total", "visits:unique"],
    "dimensions": [],
    "filters": [
      ["in", "context.path.keyword", ["bZoxuf"]]
    ]
  }'

Request Parameters

Date Range

Parameter	Type	Required	Description	Example
`start`	string	Yes	Start date and time (ISO format)	`"2025-07-23 00:00:00"`
`end`	string	Yes	End date and time (ISO format)	`"2025-08-22 23:59:59"`
`interval`	string	No	Time interval for grouping	`"1d"`, `"1h"`, `"1w"`

Metrics

Available metrics for querying:

Metric	Description
`visits:total`	Total number of visits
`visits:unique`	Number of unique visits

Dimensions

Available dimensions for grouping data:

Dimension	Description
`user_agent_info.name`	Browser/device name
`geoip.country_name`	Country name
`geoip.city_name`	City name
`context.path.keyword`	QR code path

Filters

Filter data using various conditions:

Filter Type	Description	Example
`in`	Exact match or multiple values	`["in", "context.path.keyword", ["bZoxuf"]]`
`in`	Multiple values	`["in", "geoip.country_name", ["US", "CA"]]`

Example Queries

Basic Visit Data

Get total and unique visits for a specific QR code:

bash

curl 'https://api.v2.qrcodekit.com/api/analytics/query' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": {
      "start": "2025-07-23 00:00:00",
      "end": "2025-08-22 23:59:59",
      "interval": "1d"
    },
    "metrics": ["visits:total", "visits:unique"],
    "dimensions": [],
    "filters": [
      ["is", "context.path.keyword", ["bZoxuf"]]
    ]
  }'

Response:

JSON

{
  "@context": {
    "@vocab": "https://api.v2.qrcodekit.com/api/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "result": "QueryResult/result"
  },
  "@type": "QueryResult",
  "@id": "/api/.well-known/genid/6acb3ebc8e47d75c4a9f",
  "result": [
    {
      "metrics": {
        "visits:total": 1,
        "visits:unique": 1
      },
      "time": "2025-08-20T00:00:00.000Z"
    }
  ]
}

Device Analytics

Get visits broken down by browser/device:

bash

curl 'https://api.v2.qrcodekit.com/api/analytics/query' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": {
      "start": "2025-07-23 00:00:00",
      "end": "2025-08-22 23:59:59"
    },
    "metrics": ["visits:total"],
    "dimensions": ["user_agent_info.name"],
    "filters": [
      ["is", "context.path.keyword", ["bZoxuf"]]
    ]
  }'

Response:

JSON

{
  "@context": {
    "@vocab": "https://api.v2.qrcodekit.com/api/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "result": "QueryResult/result"
  },
  "@type": "QueryResult",
  "@id": "/api/.well-known/genid/9c8e544296c322d82d72",
  "result": [
    {
      "user_agent_info.name": [
        {
          "key": "Chrome",
          "metrics": {
            "visits:total": 1
          }
        }
      ]
    }
  ]
}

Geographic Analytics

Get visits broken down by country and city:

bash

curl 'https://api.v2.qrcodekit.com/api/analytics/query' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": {
      "start": "2025-07-23 00:00:00",
      "end": "2025-08-22 23:59:59"
    },
    "metrics": ["visits:total"],
    "dimensions": ["geoip.country_name", "geoip.city_name"],
    "filters": [
      ["is", "context.path.keyword", ["bZoxuf"]]
    ]
  }'

Response:

JSON

{
  "@context": {
    "@vocab": "https://api.v2.qrcodekit.com/api/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "result": "QueryResult/result"
  },
  "@type": "QueryResult",
  "@id": "/api/.well-known/genid/009d44def05d4f51ccf6",
  "result": [
    {
      "geoip.country_name": [
        {
          "key": "Malaysia",
          "metrics": {
            "visits:total": 1
          }
        }
      ],
      "geoip.city_name": [
        {
          "key": "Cyberjaya",
          "metrics": {
            "visits:total": 1
          }
        }
      ]
    }
  ]
}

Total Analytics

Get overall totals for a QR code (all time):

bash

curl 'https://api.v2.qrcodekit.com/api/analytics/query' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: /api/user-accounts/YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": {
      "start": "2020-01-01",
      "end": "2025-08-22 23:59:59"
    },
    "metrics": ["visits:total", "visits:unique"],
    "dimensions": [],
    "filters": [
      ["is", "context.path.keyword", ["bZoxuf"]]
    ]
  }'

Response:

JSON

{
  "@context": {
    "@vocab": "https://api.v2.qrcodekit.com/api/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "result": "QueryResult/result"
  },
  "@type": "QueryResult",
  "@id": "/api/.well-known/genid/48db865c951e9189e8ad",
  "result": [
    {
      "metrics": {
        "visits:total": 1,
        "visits:unique": 1
      }
    }
  ]
}

Query Best Practices

Performance Optimization

Use specific date ranges - Avoid querying very large date ranges
Limit dimensions - Don't group by too many dimensions at once
Use filters - Filter data to reduce query size
Cache results - Cache frequently used queries

Data Interpretation

Understand time zones - All dates are in UTC
Check data freshness - Analytics data may have a delay
Consider sampling - Large queries may use sampling
Validate filters - Ensure filter values exist in your data

Common Use Cases

Daily monitoring - Query daily visit counts
Geographic analysis - Understand where your QR codes are scanned
Device analysis - See which devices are most common
Performance tracking - Monitor QR code performance over time

Error Handling

Common Errors

Error	Description	Solution
`Invalid date range`	Date format is incorrect	Use ISO format: `"2025-07-23 00:00:00"`
`Invalid metric`	Metric doesn't exist	Use only supported metrics
`Invalid dimension`	Dimension doesn't exist	Use only supported dimensions
`Query too large`	Query returns too much data	Reduce date range or add filters

Rate Limits

Query requests: 100 requests per minute
Data retention: Analytics data is retained for 2 years
Query timeout: 30 seconds maximum

Analytics

Overview

Analytics Query Endpoint

Request Parameters

Date Range

Metrics

Dimensions

Filters

Example Queries

Basic Visit Data

Device Analytics

Geographic Analytics

Total Analytics

Query Best Practices

Performance Optimization

Data Interpretation

Common Use Cases

Error Handling

Common Errors

Rate Limits

Next Steps