plausible-analytics

从 Plausible Analytics 查询和分析网站分析。当您需要检查实时访问者、获取一段时间内的页面浏览量和访问者统计数据、分析流量来源或热门页面、检查地理分布或为通过合理分析跟踪的网站生成分析报告和见解时使用。

# Plausible Analytics

## Overview

Retrieve and analyze website analytics data from Plausible Analytics API. Supports real-time visitor tracking, historical statistics, traffic source analysis, and detailed breakdowns by page, source, or country.

## Quick Start

All scripts require `PLAUSIBLE_API_KEY` environment variable. Site ID can be provided via `PLAUSIBLE_SITE_ID` environment variable or as a script argument.

```bash
# Set API key
export PLAUSIBLE_API_KEY="your-api-key"

# Quick example: Get today's stats
node scripts/stats.mjs example.com --period day
```

## Real-Time Visitors

Check how many people are currently viewing your site:

```bash
node scripts/realtime.mjs <site-id>
```

Example output:
```json
{
  "visitors": 42
}
```

## Statistics

Get page views, visitors, bounce rate, and visit duration for a time period:

```bash
node scripts/stats.mjs <site-id> [--period day|7d|30d|month|6mo|12mo] [--date YYYY-MM-DD]
```

Parameters:
- `period` - Time period to query (default: `day`)
- `date` - Specific date for the period (default: today)

Example:
```bash
# Get today's stats
node scripts/stats.mjs example.com

# Get last 7 days
node scripts/stats.mjs example.com --period 7d

# Get stats for a specific month
node scripts/stats.mjs example.com --period month --date 2026-02-01
```

Example output:
```json
{
  "results": {
    "visitors": {
      "value": 1234
    },
    "pageviews": {
      "value": 5678
    },
    "bounce_rate": {
      "value": 45
    },
    "visit_duration": {
      "value": 180
    }
  }
}
```

## Detailed Breakdown

Analyze traffic by specific dimensions (pages, sources, countries, etc.):

```bash
node scripts/breakdown.mjs <site-id> <property> [--period day|7d|30d] [--limit N]
```

Properties:
- `visit:source` - Traffic sources (Google, Twitter, direct, etc.)
- `visit:referrer` - Referring URLs
- `visit:utm_medium` / `visit:utm_source` / `visit:utm_campaign` - UTM parameters
- `visit:device` - Desktop vs Mobile
- `visit:browser` - Browser breakdown
- `visit:os` - Operating system
- `visit:country` - Countries
- `event:page` - Top pages

Example:
```bash
# Top 10 pages in the last 7 days
node scripts/breakdown.mjs example.com event:page --period 7d --limit 10

# Traffic sources today
node scripts/breakdown.mjs example.com visit:source

# Countries in the last 30 days
node scripts/breakdown.mjs example.com visit:country --period 30d
```

Example output:
```json
{
  "results": [
    {
      "page": "/",
      "visitors": 542,
      "pageviews": 1024
    },
    {
      "page": "/about",
      "visitors": 123,
      "pageviews": 145
    }
  ]
}
```

## Environment Variables

- `PLAUSIBLE_API_KEY` (required) - Your Plausible API key
- `PLAUSIBLE_SITE_ID` (optional) - Default site ID to use

## Resources

### scripts/

- `stats.mjs` - Aggregate statistics for a time period
- `realtime.mjs` - Current visitor count
- `breakdown.mjs` - Detailed breakdown by dimension

---

## 中文说明

# Plausible Analytics

## 概览

从 Plausible Analytics API 检索和分析网站分析数据。支持实时访问者跟踪、历史统计、流量来源分析，以及按页面、来源或国家/地区的详细细分。

## 快速开始

所有脚本都需要 `PLAUSIBLE_API_KEY` 环境变量。Site ID 可通过 `PLAUSIBLE_SITE_ID` 环境变量提供，或作为脚本参数提供。

```bash
# 设置 API 密钥
export PLAUSIBLE_API_KEY="your-api-key"

# 快速示例：获取今天的统计数据
node scripts/stats.mjs example.com --period day
```

## 实时访问者

查看当前有多少人正在浏览你的网站：

```bash
node scripts/realtime.mjs <site-id>
```

示例输出：
```json
{
  "visitors": 42
}
```

## 统计数据

获取某时间段内的页面浏览量、访问者数、跳出率和访问时长：

```bash
node scripts/stats.mjs <site-id> [--period day|7d|30d|month|6mo|12mo] [--date YYYY-MM-DD]
```

参数：
- `period` - 要查询的时间段（默认：`day`）
- `date` - 该时间段的特定日期（默认：今天）

示例：
```bash
# 获取今天的统计数据
node scripts/stats.mjs example.com

# 获取最近 7 天
node scripts/stats.mjs example.com --period 7d

# 获取特定月份的统计数据
node scripts/stats.mjs example.com --period month --date 2026-02-01
```

示例输出：
```json
{
  "results": {
    "visitors": {
      "value": 1234
    },
    "pageviews": {
      "value": 5678
    },
    "bounce_rate": {
      "value": 45
    },
    "visit_duration": {
      "value": 180
    }
  }
}
```

## 详细细分

按特定维度（页面、来源、国家/地区等）分析流量：

```bash
node scripts/breakdown.mjs <site-id> <property> [--period day|7d|30d] [--limit N]
```

属性：
- `visit:source` - 流量来源（Google、Twitter、direct 等）
- `visit:referrer` - 引荐 URL
- `visit:utm_medium` / `visit:utm_source` / `visit:utm_campaign` - UTM 参数
- `visit:device` - 桌面端 vs 移动端
- `visit:browser` - 浏览器细分
- `visit:os` - 操作系统
- `visit:country` - 国家/地区
- `event:page` - 热门页面

示例：
```bash
# 最近 7 天的前 10 个页面
node scripts/breakdown.mjs example.com event:page --period 7d --limit 10

# 今天的流量来源
node scripts/breakdown.mjs example.com visit:source

# 最近 30 天的国家/地区
node scripts/breakdown.mjs example.com visit:country --period 30d
```

示例输出：
```json
{
  "results": [
    {
      "page": "/",
      "visitors": 542,
      "pageviews": 1024
    },
    {
      "page": "/about",
      "visitors": 123,
      "pageviews": 145
    }
  ]
}
```

## 环境变量

- `PLAUSIBLE_API_KEY`（必需）- 你的 Plausible API 密钥
- `PLAUSIBLE_SITE_ID`（可选）- 要使用的默认 site ID

## 资源

### scripts/

- `stats.mjs` - 某时间段的聚合统计数据
- `realtime.mjs` - 当前访问者数
- `breakdown.mjs` - 按维度的详细细分