Collects custom events and pageviews server-side by POSTing a JSON payload (event type, hostname, path, optional metadata) to the collection endpoint, mirroring what the client-side sa_event() function sends.
openapi: 3.0.1
info:
title: Simple Analytics API
description: >-
Specification of the Simple Analytics REST API. Simple Analytics is a
privacy-first, cookieless web analytics platform. The API exposes aggregated
dashboard statistics (Stats API), raw data point exports (Export API),
server-side event collection, and website administration (Admin API).
termsOfService: https://www.simpleanalytics.com/terms
contact:
name: Simple Analytics Support
email: support@simpleanalytics.com
version: '6'
servers:
- url: https://simpleanalytics.com
description: Stats, Export, and Admin API
- url: https://queue.simpleanalyticscdn.com
description: Event collection endpoint
security:
- ApiKeyAuth: []
UserId: []
paths:
/{hostname}.json:
get:
operationId: getStats
tags:
- Stats
summary: Get aggregated statistics for a website.
description: >-
Returns the aggregated statistics shown in the dashboard as JSON for the
given hostname. Public websites can be queried without credentials;
private websites require Api-Key and User-Id headers.
parameters:
- name: hostname
in: path
required: true
description: The website hostname, e.g. simpleanalytics.com
schema:
type: string
- name: version
in: query
description: API version. Latest is 6.
schema:
type: integer
default: 6
- name: start
in: query
description: Start date in YYYY-MM-DD format. Defaults to one month ago.
schema:
type: string
- name: end
in: query
description: End date in YYYY-MM-DD format. Defaults to today.
schema:
type: string
- name: fields
in: query
description: >-
Comma-separated list of fields to return, e.g.
pageviews,visitors,histogram,pages,countries,referrers,utm_sources.
schema:
type: string
- name: limit
in: query
description: Number of results for list fields (1-1000).
schema:
type: integer
- name: timezone
in: query
description: A valid timezone such as Europe/Amsterdam.
schema:
type: string
- name: interval
in: query
description: Histogram interval.
schema:
type: string
enum:
- hour
- day
- week
- month
- year
- name: page
in: query
description: Filter by a page path, supports the * wildcard.
schema:
type: string
- name: country
in: query
description: Filter by ISO country code.
schema:
type: string
- name: referrer
in: query
description: Filter by referrer.
schema:
type: string
- name: utm_source
in: query
schema:
type: string
- name: utm_medium
in: query
schema:
type: string
- name: utm_campaign
in: query
schema:
type: string
responses:
'200':
description: Aggregated statistics for the website.
content:
application/json:
schema:
$ref: '#/components/schemas/Stats'
/api/export/datapoints:
get:
operationId: exportDataPoints
tags:
- Export
summary: Export raw data points.
description: >-
Exports raw, per-event data points (pageviews or events) for a hostname
as CSV or JSON. Requires Api-Key and User-Id headers and a Business or
Enterprise plan.
parameters:
- name: version
in: query
required: true
schema:
type: integer
default: 6
- name: format
in: query
required: true
description: Response format.
schema:
type: string
enum:
- csv
- json
- name: hostname
in: query
required: true
description: Website hostname to export data from.
schema:
type: string
- name: type
in: query
required: true
description: Data type to export.
schema:
type: string
enum:
- pageviews
- events
- name: start
in: query
required: true
description: Start date as YYYY-MM-DD or YYYY-MM-DDTHH for hourly granularity.
schema:
type: string
- name: end
in: query
required: true
description: End date as YYYY-MM-DD or YYYY-MM-DDTHH for hourly granularity.
schema:
type: string
- name: fields
in: query
required: true
description: >-
Comma-separated list of fields to include, e.g.
added_iso,hostname,path,referrer.
schema:
type: string
- name: timezone
in: query
required: true
schema:
type: string
- name: robots
in: query
description: Whether to include robot traffic.
schema:
type: boolean
responses:
'200':
description: Raw data points in the requested format.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataPoint'
text/csv:
schema:
type: string
/api/websites:
get:
operationId: listWebsites
tags:
- Websites
summary: List websites.
description: >-
Returns all websites for the authenticated user. Available on all plans.
Requires Api-Key and User-Id headers.
responses:
'200':
description: A list of websites.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Website'
/api/websites/add:
post:
operationId: addWebsite
tags:
- Websites
summary: Add a website.
description: >-
Adds a new website to the dashboard. Requires a Business or Enterprise
plan and Api-Key and User-Id headers.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddWebsiteRequest'
responses:
'200':
description: The created website.
content:
application/json:
schema:
$ref: '#/components/schemas/Website'
/events:
post:
operationId: collectEvent
tags:
- Events
summary: Collect a server-side event or pageview.
description: >-
Sends a custom event or pageview to Simple Analytics from the server
side. POST to https://queue.simpleanalyticscdn.com/events with a JSON
payload describing the event.
servers:
- url: https://queue.simpleanalyticscdn.com
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CollectEventRequest'
responses:
'201':
description: Event accepted.
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: API key starting with sa_api_key_
UserId:
type: apiKey
in: header
name: User-Id
description: User identifier starting with sa_user_id_
schemas:
Stats:
type: object
properties:
ok:
type: boolean
pageviews:
type: integer
visitors:
type: integer
start:
type: string
end:
type: string
histogram:
type: array
items:
type: object
properties:
date:
type: string
pageviews:
type: integer
visitors:
type: integer
pages:
type: array
items:
type: object
properties:
value:
type: string
pageviews:
type: integer
visitors:
type: integer
referrers:
type: array
items:
type: object
properties:
value:
type: string
pageviews:
type: integer
visitors:
type: integer
countries:
type: array
items:
type: object
properties:
value:
type: string
visitors:
type: integer
utm_sources:
type: array
items:
type: object
properties:
value:
type: string
visitors:
type: integer
DataPoint:
type: object
properties:
added_iso:
type: string
format: date-time
hostname:
type: string
path:
type: string
referrer:
type: string
utm_source:
type: string
country_code:
type: string
browser_name:
type: string
os_name:
type: string
device_type:
type: string
Website:
type: object
properties:
hostname:
type: string
public:
type: boolean
timezone:
type: string
label:
type: string
AddWebsiteRequest:
type: object
required:
- hostname
properties:
hostname:
type: string
description: Domain name of the website to add.
timezone:
type: string
description: Timezone for the website. Defaults to UTC.
public:
type: boolean
description: Whether the website stats are public.
label:
type: string
description: A custom label for organizing the website.
CollectEventRequest:
type: object
required:
- type
- hostname
properties:
type:
type: string
description: Event type, e.g. event or pageview.
example: event
hostname:
type: string
event:
type: string
description: Custom event name (alphanumeric and underscores, max 200 chars).
path:
type: string
ua:
type: string
description: User agent string.
metadata:
type: object
additionalProperties: true