bossplatform.site

Analytics API Documentation

The bossplatform.site analytics API lets you query raw visit data for the main site and any tenant subdomain. Each request is logged with rich Cloudflare metadata — geography, network, device, and protocol details — all queryable and groupable. All query parameters are validated with Zod — invalid inputs return structured error messages.

Endpoints

Method	Path	Description
`GET`	`/api/analytics`	Query visit data with filters, grouping & pagination
`GET`	`/api/schema`	OpenAPI 3.1 spec (JSON) — use to generate client types

Tracked Fields

Every visit records the following fields from Cloudflare's edge network:

Field	Type	Example	Category
`tenant`	string	`brand-a` / `_main`	meta
`path`	string	`/about.html`	meta
`country`	string	`US`	geo
`city`	string	`Austin`	geo
`continent`	string	`NA`	geo
`region`	string	`Texas`	geo
`region_code`	string	`TX`	geo
`timezone`	string	`America/Chicago`	geo
`colo`	string	`DFW`	tech
`asn`	integer	`395747`	net
`as_organization`	string	`Google Cloud`	net
`device_type`	string	`mobile`	tech
`referer`	string	`https://google.com`	meta
`http_protocol`	string	`HTTP/2`	tech
`tls_version`	string	`TLSv1.3`	tech
`is_eu`	integer	`1` / `0`	geo
`created_at`	datetime	`2026-02-11 14:30:00`	meta

Query Parameters

All parameters are optional and can be combined freely.

Filters

Any tracked field (except created_at) can be used as a filter. Pass a single value or comma-separated values for IN matching.

Parameter	Description	Example
`tenant`	Filter by tenant. `_main` = main site.	`?tenant=brand-a`
`country`	Single or multi country code	`?country=US,GB,DE`
`city`	Filter by city name	`?city=Austin`
`continent`	Continent code	`?continent=NA,EU`
`region`	Region name	`?region=Texas`
`region_code`	Region code	`?region_code=TX,CA`
`timezone`	IANA timezone	`?timezone=America/Chicago`
`colo`	Cloudflare data center	`?colo=DFW,LAX`
`asn`	ASN number	`?asn=395747`
`as_organization`	Network org name	`?as_organization=Google Cloud`
`device_type`	Device category	`?device_type=mobile,desktop`
`http_protocol`	HTTP version	`?http_protocol=HTTP/2`
`tls_version`	TLS version	`?tls_version=TLSv1.3`
`is_eu`	EU country flag	`?is_eu=1`

Date Range

Parameter	Description	Example
`start`	Start date (inclusive), `YYYY-MM-DD`	`?start=2026-02-01`
`end`	End date (inclusive), `YYYY-MM-DD`	`?end=2026-02-11`

Aggregation

Parameter	Description	Example
`group_by`	Comma-separated list of fields to GROUP BY. Returns `visits` count per group.	`?group_by=country,device_type`

Pagination

Parameter	Default	Description
`limit`	`200`	Max rows to return (1–10,000).
`offset`	`0`	Number of rows to skip.

Examples

Raw visits for a tenant

GET /api/analytics?tenant=brand-a

Visits by country (aggregated)

GET /api/analytics?group_by=country

Visits by country & device type

GET /api/analytics?group_by=country,device_type

Daily visits for a tenant

GET /api/analytics?tenant=brand-a&group_by=tenant&start=2026-02-01&end=2026-02-11

Mobile traffic from EU countries

GET /api/analytics?device_type=mobile&is_eu=1&group_by=country

Top Cloudflare data centers

GET /api/analytics?group_by=colo

UK cities breakdown

GET /api/analytics?country=GB&group_by=city

Traffic by network provider

GET /api/analytics?group_by=as_organization&limit=20

Protocol & TLS breakdown

GET /api/analytics?group_by=http_protocol,tls_version

Response

Raw visits (no group_by)

{
  "success": true,
  "count": 2,
  "data": [
    {
      "tenant": "brand-a",
      "path": "/index.html",
      "country": "US",
      "city": "Austin",
      "continent": "NA",
      "region": "Texas",
      "region_code": "TX",
      "timezone": "America/Chicago",
      "colo": "DFW",
      "asn": 395747,
      "as_organization": "Google Cloud",
      "device_type": "desktop",
      "referer": null,
      "http_protocol": "HTTP/2",
      "tls_version": "TLSv1.3",
      "is_eu": 0,
      "created_at": "2026-02-11 14:30:00"
    }
  ]
}

Aggregated (with group_by)

{
  "success": true,
  "count": 3,
  "data": [
    { "country": "US", "device_type": "desktop", "visits": 142 },
    { "country": "US", "device_type": "mobile", "visits": 87 },
    { "country": "GB", "device_type": "desktop", "visits": 34 }
  ]
}

Error

{
  "success": false,
  "error": "error message"
}

Notes

Without group_by, raw individual visits are returned (newest first).
With group_by, aggregated counts are returned sorted by visits descending.
All filterable fields accept comma-separated values for multi-match (e.g. ?country=US,GB,DE).
Country codes follow ISO 3166-1 alpha-2. Unknown locations are XX.
Device types: desktop, mobile, tablet, bot, unknown.
The API supports CORS — you can call it from any origin.
Cloudflare geo data (city, region, etc.) depends on the visitor's IP — some fields may be null for certain networks.
Invalid query parameters return a 400 response with detailed validation errors.

OpenAPI Schema & Type Generation

The full API schema is available as an OpenAPI 3.1 spec at /api/schema. Use it to auto-generate typed clients in any language:

TypeScript

npx openapi-typescript https://bossplatform.site/api/schema -o api.d.ts

Python (datamodel-code-generator)

pip install datamodel-code-generator
datamodel-codegen --url https://bossplatform.site/api/schema --output models.py

Any language

curl https://bossplatform.site/api/schema | jq .

Feed the JSON into any OpenAPI generator for Go, Rust, Java, C#, Swift, etc.

Validation Errors

If a query parameter is invalid, the API returns 400 with details:

{
  "success": false,
  "error": "Invalid query parameters",
  "issues": [
    { "field": "start", "message": "Invalid" },
    { "field": "limit", "message": "Number must be less than or equal to 10000" }
  ]
}

← Back to bossplatform.site