SimpleStats

https://simplestats.io/docs
Admin
SimpleStats is a server-side analytics platform for Laravel applications that provides detailed...
Tokens:51,756
Snippets:402
Trust Score:6.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://simplestats.io/docs/php-client.html

Install the SimpleStats PHP client via Composer.

```APIDOC
## Installation

### Description
Install the SimpleStats PHP client package using Composer.

### Command
```bash
composer require simplestats-io/php-client
```
```

--------------------------------

### Install with Composer

Source: https://simplestats.io/docs/php-client.html

Install the SimpleStats PHP client package using Composer.

```bash
composer require simplestats-io/php-client
```

--------------------------------

### Install the addon via Composer

Source: https://simplestats.io/docs/statamic-addon.html

Run this command to install the SimpleStats Statamic addon. Requires PHP 8.2+, Statamic 6+, and a SimpleStats API token.

```bash
composer require simplestats-io/statamic-addon
```

--------------------------------

### GET /api/v1/stats/grouped - Example Response

Source: https://simplestats.io/docs/query-api.html

Example JSON response with grouped data and meta information. The meta includes project_id, range details, and preset.

```json
{
    "data": [
        {
            "name": "google",
            "type_id": 3,
            "visitors": 120,
            "reg": 15,
            "cr": 12.5,
            "dau": 8,
            "net": 45000,
            "total": 1
        },
        {
            "name": "twitter",
            "type_id": 7,
            "visitors": 85,
            "reg": 10,
            "cr": 11.76,
            "dau": 5,
            "net": 20000,
            "total": 1
        }
    ],
    "meta": {
        "project_id": 1,
        "range_amount": 7,
        "range_type": "days",
        "range_start": "2026-03-11",
        "comparison": "0",
        "preset": "last_7_days",
        ...
    }
}
```

--------------------------------

### Create Visitor - JSON Response Example

Source: https://simplestats.io/docs/ingest-api.html

Example JSON response from the Create Visitor endpoint. Returns a success message and a visitor_hash. If no visitor_hash is provided, it is generated from time, ip, and user_agent.

```json
{
    "message": "Stats Visitor Request accepted.",
    "visitor_hash": "9a7c4f2e8b1d6a3c5e0f7b2d4a8c1e6f"
}
```

--------------------------------

### Install SimpleStats Laravel client via Composer

Source: https://simplestats.io/docs/installation.html

Run this command to install the simplestats-io/laravel-client package. Supports Laravel versions 11, 12, and 13; for Laravel 8, 9, and 10, use client package version 3 or earlier.

```bash
composer require simplestats-io/laravel-client
```

--------------------------------

### Install Filament plugin via Composer

Source: https://simplestats.io/docs/filament-plugin.html

Install the SimpleStats Filament plugin package using Composer.

```bash
composer require simplestats-io/filament-plugin
```

--------------------------------

### Frontend tracking request example

Source: https://simplestats.io/docs/headless-stateless-spa.html

JavaScript snippet to place at the top of the SPA's root component. Sends a single GET request to a tracking endpoint with UTM parameters, document referrer, and page path as headers. The document referrer is only forwarded if it is external to the frontend domain. This call populates the cache for the rest of the day.

```js
const params = new URLSearchParams(location.search)

const referrer = document.referrer;

// this check drops your own frontend as a referrer on in-app navigation, reloads, or expired sessions, only an external referrer is forwarded.
const documentReferer = referrer && new URL(referrer).hostname !== location.hostname ? referrer : '' ;

fetch('https://api.your-app.com/track-init', {
  method: 'GET',
  credentials: 'include',
  headers: {
    'X-Utm-Source': params.get('utm_source') ?? '',
    'X-Utm-Medium': params.get('utm_medium') ?? '',
    'X-Utm-Campaign': params.get('utm_campaign') ?? '',
    'X-Utm-Term': params.get('utm_term') ?? '',
    'X-Utm-Content': params.get('utm_content') ?? '',
    'X-Document-Referer': documentReferer,
    'X-Page': location.pathname,
  },
})
```

--------------------------------

### Create Visitor - JSON Payload Example

Source: https://simplestats.io/docs/ingest-api.html

Example JSON payload for the Create Visitor endpoint. The 'time' field is required and must be in 'Y-m-d H:i:s P' format, before or equal to now. The 'ip' and 'user_agent' fields are nullable and are not stored.

```json
{
    "ip": "127.0.0.1",
    "user_agent": "Mozilla/5.0 (Linux; Android 13; Pixel 6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
    "track_source": "test",
    "time": "2024-04-04"
}
```

--------------------------------

### Headless / SPA configuration

Source: https://simplestats.io/docs/headless-stateless-spa.html

Configuration for headless setups where the frontend lives on a separate domain (Vue, React, Next, mobile app) and only talks to the Laravel API. Uses the 'api' middleware group and 'cache' storage.

```php
// config/simplestats-client.php
'middleware_groups' => ['api'],
'tracking_storage' => 'cache',
```

--------------------------------

### Extend PaddleTransaction and implement TrackablePaymentWithCondition for Cashier Paddle

Source: https://simplestats.io/docs/how-to-track-a-new-payment.html

For Cashier Paddle, extend the shipped PaddleTransaction model, implement the contract, and register the subclass. This example shows the full implementation including tracking person, time, gross, net, currency, subscription, and condition methods.

```php
<?php

namespace App\Models;

use Carbon\CarbonInterface;
use Laravel\Paddle\Transaction as PaddleTransaction;
use SimpleStatsIo\LaravelClient\Contracts\TrackablePerson;
use SimpleStatsIo\LaravelClient\Contracts\TrackablePaymentWithCondition;
use SimpleStatsIo\LaravelClient\Data\TrackingSubscription;

class Transaction extends PaddleTransaction implements TrackablePaymentWithCondition
{
    public function getTrackingPerson(): TrackablePerson
    {
        return $this->billable;
    }

    public function getTrackingTime(): CarbonInterface
    {
        return $this->created_at;
    }

    public function getTrackingGross(): float
    {
        return $this->total;
    }

    public function getTrackingNet(): float
    {
        return $this->total - $this->tax;
    }

    public function getTrackingCurrency(): string
    {
        return $this->currency;
    }

    public function getTrackingSubscription(): ?TrackingSubscription
    {
        return null; // or build it from your Paddle price ids, see "Subscriptions" above
    }

    public function passTrackingCondition(): bool
    {
        return $this->status === 'completed';
    }

    public function watchTrackingFields(): array
    {
        return ['status'];
    }
}
```

--------------------------------

### GET /api/v1/stats/grouped - Example Request

Source: https://simplestats.io/docs/query-api.html

Example request to get grouped stats for track_source with a limit of 5 results.

```http
GET /api/v1/stats/grouped?stats_type=track_source&limit=5
```

--------------------------------

### GET /api/v1/stats/groups - Example Response

Source: https://simplestats.io/docs/query-api.html

Example JSON response showing available values with their ids. Use the id as the filter value in the Stats or Grouped Stats endpoints, e.g., GET /api/v1/stats?track_source=3.

```json
{
    "data": [
        {
            "id": 3,
            "name": "google"
        },
        {
            "id": 7,
            "name": "twitter"
        },
        {
            "id": 12,
            "name": "newsletter"
        }
    ]
}
```

--------------------------------

### Configuration

Source: https://simplestats.io/docs/php-client.html

Create a client instance with your API token and optional configuration options.

```APIDOC
## Configuration

### Description
Create a SimpleStats client instance with your API token and optional settings.

### Constructor
`new SimplestatsClient(array $config)`

### Parameters
- **api_token** (string) - Required - Your SimpleStats API token.
- **api_url** (string) - Optional - The API base URL. Default: `https://simplestats.io/api/v1/`
- **timeout** (int) - Optional - Request timeout in seconds. Default: 5
- **max_retries** (int) - Optional - Maximum number of retries. Default: 3
- **enabled** (bool) - Optional - Set to `false` to disable tracking. Default: `true`

### Example
```php
use SimpleStatsIo\PhpClient\SimplestatsClient;

$client = new SimplestatsClient([
    'api_token'   => 'your-api-token',
    'api_url'     => 'https://simplestats.io/api/v1/',
    'timeout'     => 5,
    'max_retries' => 3,
    'enabled'     => true,
]);
```
```

--------------------------------

### GET /api/v1/stats/groups - Example Request

Source: https://simplestats.io/docs/query-api.html

Example request to list available values for the track_source stats type. The response provides ids that can be used as filter values in other endpoints.

```http
GET /api/v1/stats/groups?stats_type=track_source
```

--------------------------------

### Publish SimpleStats client config file

Source: https://simplestats.io/docs/installation.html

Publishes the configuration file for the SimpleStats client. Run this after registering an account and obtaining an API token, then set SIMPLESTATS_API_TOKEN in your .env file.

```bash
php artisan vendor:publish --tag="simplestats-client-config"
```

--------------------------------

### Stats Endpoint Example Request

Source: https://simplestats.io/docs/query-api.html

GET request to retrieve time-series stats for the last 7 days. Uses the preset parameter to define the date range.

```http
GET /api/v1/stats?preset=last_7_days
```

--------------------------------

### GET /api/v1/stats/groups

Source: https://simplestats.io/docs/query-api.html

Returns the available values for a specific stats type. Use this to discover the ids you need for filtering. For example, to find the id for a specific referrer, call this endpoint with statsType=trackReferer.

```APIDOC
## GET /api/v1/stats/groups

### Description
Returns the available values for a specific stats type. Use this to discover the `id`s you need for filtering. For example, to find the `id` for a specific referrer, call this endpoint with `statsType=trackReferer`.

### Method
GET

### Endpoint
/api/v1/stats/groups

### Parameters
#### Query Parameters
- **stats_type** (string) - Required - The stats type to list values for. See Available Stats Types below.

### Request Example
GET /api/v1/stats/groups?stats_type=track_source

### Response
#### Success Response (200)
- **data** (array) - List of objects with `id` and `name` fields.

#### Response Example
{
    "data": [
        {
            "id": 3,
            "name": "google"
        },
        {
            "id": 7,
            "name": "twitter"
        },
        {
            "id": 12,
            "name": "newsletter"
        }
    ]
}
```

--------------------------------

### MySQL: Export user data with id and time

Source: https://simplestats.io/docs/how-to-import-existing-data.html

Example SQL query for MySQL to export user data with the required fields id and time. The time field is formatted as 'Y-m-d H:i:s' using DATE_FORMAT. This query serves as a starting point; actual table structures may vary.

```sql
SELECT
    id,
    DATE_FORMAT(created_at, '%Y-%m-%d %H:%i:%s') AS `time`
FROM
    users;
```

--------------------------------

### MySQL: Export user data with condition on email_verified_at

Source: https://simplestats.io/docs/how-to-import-existing-data.html

Example SQL query for MySQL that exports only users who have verified their email address, using a WHERE clause on email_verified_at. The time field is formatted as 'Y-m-d H:i:s' using DATE_FORMAT. This query serves as a starting point; actual table structures may vary.

```sql
SELECT
    id,
    DATE_FORMAT(created_at, '%Y-%m-%d %H:%i:%s') AS `time`
FROM
    users
WHERE
    email_verified_at IS NOT NULL;
```

--------------------------------

### Create a client instance with API token

Source: https://simplestats.io/docs/php-client.html

Instantiate the SimplestatsClient with your API token. Requires PHP 8.2+ and Guzzle 7.5+.

```php
use SimpleStatsIo\PhpClient\SimplestatsClient;

$client = new SimplestatsClient([
    'api_token' => 'your-api-token',
]);
```

--------------------------------

### PostgreSQL: Export user data with id and time

Source: https://simplestats.io/docs/how-to-import-existing-data.html

Example SQL query for PostgreSQL to export user data with the required fields id and time. The time field is formatted as 'YYYY-MM-DD HH24:MI:SS' using to_char. This query serves as a starting point; actual table structures may vary.

```sql
SELECT
    id,
    to_char(created_at, 'YYYY-MM-DD HH24:MI:SS') AS "time"
FROM
    users;
```

--------------------------------

### Configure client options

Source: https://simplestats.io/docs/php-client.html

Shows all available configuration options for the client, including api_url, timeout, max_retries, and enabled. The api_token is required; others have defaults.

```php
$client = new SimplestatsClient([
    'api_token'   => 'your-api-token',       // required
    'api_url'     => 'https://simplestats.io/api/v1/',  // default
    'timeout'     => 5,                      // seconds, default 5
    'max_retries' => 3,                      // default 3
    'enabled'     => true,                   // set false to disable tracking
]);
```

--------------------------------

### Configure client for self-hosted instance

Source: https://simplestats.io/docs/php-client.html

Point the client to your own SimpleStats instance by providing the API token and API URL in the constructor options.

```php
$client = new SimplestatsClient([
    'api_token' => 'your-api-token',
    'api_url'   => 'https://stats.yourdomain.com/api/v1/',
]);
```

--------------------------------

### Publish and run SimpleStats migrations

Source: https://simplestats.io/docs/how-to-track-a-new-payment.html

Publishes the SimpleStats client migrations and runs them to add the visitor_hash column to your payment model.

```bash
php artisan vendor:publish --tag=simplestats-client-migrations
php artisan migrate
```

--------------------------------

### PostgreSQL: Export user data with condition on email_verified_at

Source: https://simplestats.io/docs/how-to-import-existing-data.html

Example SQL query for PostgreSQL that exports only users who have verified their email address, using a WHERE clause on email_verified_at. The time field is formatted as 'YYYY-MM-DD HH24:MI:SS' using to_char. This query serves as a starting point; actual table structures may vary.

```sql
SELECT
    id,
    to_char(created_at, 'YYYY-MM-DD HH24:MI:SS') AS "time"
FROM
    users
WHERE
    email_verified_at IS NOT NULL;
```

--------------------------------

### Test queue with php artisan queue:listen

Source: https://simplestats.io/docs/troubleshooting.html

For database queues, ensure the queue is running. Locally, run this command to test the queue.

```bash
php artisan queue:listen
```

--------------------------------

### Enable the beacon in SimpleStats client config

Source: https://simplestats.io/docs/static-caching.html

Enable the beacon and set its path in config/simplestats-client.php. The route is registered in the first middleware group, so it always carries tracking middleware. Ensure the path does not match your 'except' list; the package logs a warning if it does.

```php
// config/simplestats-client.php

'beacon' => [
    'enabled' => env('SIMPLESTATS_BEACON_ENABLED', false),
    'path' => env('SIMPLESTATS_BEACON_PATH', 'assets/v'),
],
```

--------------------------------

### Self-hosted API configuration

Source: https://simplestats.io/docs/statamic-addon.html

Environment variables to point the addon to a self-hosted SimpleStats instance.

```env
SIMPLESTATS_API_URL=https://stats.yourdomain.com/api/v1
SIMPLESTATS_API_TOKEN=your-api-token-here
```

--------------------------------

### Build tracking data manually

Source: https://simplestats.io/docs/php-client.html

Create a TrackingData instance manually with explicit IP, user agent, source, medium, and campaign values.

```php
$trackingData = new TrackingData(
    ip: '203.0.113.42',
    userAgent: 'Mozilla/5.0 ...',
    source: 'google',
    medium: 'cpc',
    campaign: 'spring-sale',
);
```

--------------------------------

### Publish the config file

Source: https://simplestats.io/docs/statamic-addon.html

Run this Artisan command to publish the addon's config file, allowing you to override defaults.

```bash
php artisan vendor:publish --tag="simplestats-config"
```

--------------------------------

### Invalid tracking URLs

Source: https://simplestats.io/docs/tracking-codes.html

These URL examples are not tracked because they use parameters not defined in the tracking_codes config.

```text
https://example.com?my_source=twitter&my_medium=desktop
https://example.com?my_ref=google&group=banner
```

--------------------------------

### Valid tracking URLs

Source: https://simplestats.io/docs/tracking-codes.html

These URL examples are tracked and associated with the user at registration because they use parameters defined in the tracking_codes config.

```text
https://example.com?utm_source=twitter&utm_medium=desktop
https://example.com?utm_source=twitter&utm_medium=mobile
https://example.com?ref=google&adGroup=banner
```

--------------------------------

### Track user registration with auto-login

Source: https://simplestats.io/docs/php-client.html

Record a login event at the same time as registration by setting addLogin to true.

```php
$client->trackUser(
    id: $user->id,
    registeredAt: $user->createdAt,
    trackingData: $trackingData,
    addLogin: true,
);
```

--------------------------------

### Configure plugin via fluent methods

Source: https://simplestats.io/docs/filament-plugin.html

Configure the plugin directly in the PanelProvider using the fluent API. Methods include navigationGroup, navigationLabel, navigationSort, navigationIcon, and cacheTtl.

```php
SimplestatsPlugin::make()
    ->navigationGroup('Analytics')
    ->navigationLabel('Stats')
    ->navigationSort(5)
    ->navigationIcon('heroicon-o-chart-bar-square')
    ->cacheTtl(120)
```

--------------------------------

### GET /api/v1/stats

Source: https://simplestats.io/docs/query-api.html

Returns time-series analytics data for your project. Supports various parameters for date ranges, granularity, comparison, and filtering by group IDs.

```APIDOC
## GET /api/v1/stats

### Description
Returns time-series analytics data for your project.

### Method
GET

### Endpoint
/api/v1/stats

### Parameters
#### Query Parameters
- **preset** (string) - Optional - A predefined date range. See Available Presets below.
- **range_type** (string) - Optional - The granularity of the data: `hours`, `days`, `weeks`, `months`, `years`.
- **range_amount** (integer) - Optional - Number of periods to include.
- **range_start** (date) - Optional - The starting point from which the range is calculated **backwards** (format: `Y-m-d`). Defaults to today.
- **comparison** (string) - Optional - Compare with a previous period: `period` or `year`.
- **track_referer** (integer) - Optional - Filter by referrer `id`.
- **track_source** (integer) - Optional - Filter by source `id`.
- **track_medium** (integer) - Optional - Filter by medium `id`.
- **track_campaign** (integer) - Optional - Filter by campaign `id`.
- **track_term** (integer) - Optional - Filter by term `id`.
- **track_content** (integer) - Optional - Filter by content `id`.
- **location_country** (integer) - Optional - Filter by country `id`.
- **location_region** (integer) - Optional - Filter by region `id`.
- **location_city** (integer) - Optional - Filter by city `id`.
- **device_type** (integer) - Optional - Filter by device type `id`.
- **device_platform** (integer) - Optional - Filter by platform `id`.
- **device_browser** (integer) - Optional - Filter by browser `id`.
- **page_entry** (integer) - Optional - Filter by entry page `id`.
- **custom_event_name** (integer) - Optional - Filter by custom event name `id`.

### Request Example
GET /api/v1/stats?preset=last_7_days

### Response
#### Success Response (200)
Results are returned in **reverse** chronological order (most recent first).

#### Response Example
{
    "data": [
        {
            "date": "2026-03-11",
            "date_clear": "2026-03-11",
            "pd_visitor": 42,
            "pd_reg": 5,
            "pd_cr": 11.9,
            "pd_net": 15000,
            "pd_gross": 17850,
            "pd_dau": 12,
            "lt_visitor": 1250,
            "lt_reg": 180,
            "lt_net": 450000,
            "lt_arpu": 2500,
            "lt_arppu": 7500,
            "lt_arpv": 360,
            "lt_pu": 60
        }
    ],
    "meta": {
        "project_id": 1,
        "range_amount": 7,
        "range_type": "days",
        "range_start": "2026-03-11",
        "comparison": "0",
        "preset": "last_7_days",
        ...
    }
}

### Response with comparison
When the `comparison` parameter is set to `period` or `year`, the response includes an additional `data_previous` array with the same structure.

#### Response Example
GET /api/v1/stats?preset=last_7_days&comparison=period

{
    "data": [ ... ],
    "data_previous": [ ... ],
    "meta": {
        "project_id": 1,
        "range_amount": 7,
        "range_type": "days",
        "range_start": "2026-03-11",
        "comparison": "period",
        "preset": "last_7_days",
        ...
    }
}
```

--------------------------------

### Self-Hosted Configuration

Source: https://simplestats.io/docs/php-client.html

Configures the client to point to a self-hosted SimpleStats instance.

```APIDOC
## Self-Hosted Configuration

### Description
Configures the client to point to a self-hosted SimpleStats instance.

### Method
SDK Configuration

### Endpoint
`new SimplestatsClient([...])`

### Parameters
- **api_token** (string) - Required - API token for authentication.
- **api_url** (string) - Required - Base URL of the self-hosted SimpleStats API.

### Request Example
```php
$client = new SimplestatsClient([
    'api_token' => 'your-api-token',
    'api_url'   => 'https://stats.yourdomain.com/api/v1/',
]);
```

### Response
No response details provided in the source.
```

--------------------------------

### GET /api/v1/stats/grouped

Source: https://simplestats.io/docs/query-api.html

Returns analytics data grouped by a specific group (e.g., sources, countries, browsers). Supports sorting, limiting, and date range filtering.

```APIDOC
## GET /api/v1/stats/grouped

### Description
Returns analytics data grouped by a specific group (e.g., sources, countries, browsers).

### Method
GET

### Endpoint
/api/v1/stats/grouped

### Parameters
#### Query Parameters
- **stats_type** (string) - Required - The group to aggregate by. See Available Stats Types below.
- **stats_sort** (string) - Optional - Sort results by: `name`, `visitors`, `reg`, `cr`, `dau`, `net`, `total`. Default: `visitors`.
- **limit** (integer) - Optional - Maximum number of results (1-100). Default: 10.
- **preset** (string) - Optional - A predefined date range. See Available Presets below.
- **range_type** (string) - Optional - The granularity: `hours`, `days`, `weeks`, `months`, `years`.
- **range_amount** (integer) - Optional - Number of periods to include.
- **range_start** (date) - Optional - The starting point from which the range is calculated backwards (format: `Y-m-d`). Defaults to today.

#### Filter Parameters
The same filter parameters as the Stats endpoint apply here as well.

### Request Example
GET /api/v1/stats/grouped?stats_type=track_source&limit=5

### Response
#### Success Response (200)
- **data** (array) - List of objects with fields: `name`, `type_id`, `visitors`, `reg`, `cr`, `dau`, `net`, `total`.
- **meta** (object) - Metadata including `project_id`, `range_amount`, `range_type`, `range_start`, `comparison`, `preset`, and possibly other fields.

#### Response Example
{
    "data": [
        {
            "name": "google",
            "type_id": 3,
            "visitors": 120,
            "reg": 15,
            "cr": 12.5,
            "dau": 8,
            "net": 45000,
            "total": 1
        },
        {
            "name": "twitter",
            "type_id": 7,
            "visitors": 85,
            "reg": 10,
            "cr": 11.76,
            "dau": 5,
            "net": 20000,
            "total": 1
        }
    ],
    "meta": {
        "project_id": 1,
        "range_amount": 7,
        "range_type": "days",
        "range_start": "2026-03-11",
        "comparison": "0",
        "preset": "last_7_days",
        ...
    }
}
```

--------------------------------

### Stats Endpoint with Comparison Parameter

Source: https://simplestats.io/docs/query-api.html

GET request that includes the comparison parameter set to 'period' to compare with a previous period. The response includes an additional data_previous array.

```http
GET /api/v1/stats?preset=last_7_days&comparison=period
```

--------------------------------

### Configure self-hosted API URL

Source: https://simplestats.io/docs/filament-plugin.html

Point the plugin to a self-hosted SimpleStats instance using the apiUrl method.

```php
SimplestatsPlugin::make()
    ->apiUrl('https://stats.yourdomain.com/api/v1')
```
Tokens:
Raw