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