🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Remove Stats API guide and metric documentation files; update overview documentation to include new structure and references. This streamlines the API documentation and enhances clarity for users.
Bill Yang5588623affe1
diff --git a/docs/content/docs/api/stats/meta.json b/docs/content/docs/api/stats/meta.jsonindex c338ee7c1..ea383fa51 100644--- a/docs/content/docs/api/stats/meta.json+++ b/docs/content/docs/api/stats/meta.json@@ -1,4 +1,4 @@{"title": "Stats",- "pages": ["guide", "overview", "metric"]+ "pages": ["reference", "overview"]}diff --git a/docs/content/docs/api/stats/metric.mdx b/docs/content/docs/api/stats/metric.mdxdeleted file mode 100644index 7c9848e85..000000000--- a/docs/content/docs/api/stats/metric.mdx+++ /dev/null@@ -1,157 +0,0 @@-----title: Get Metric-description: Retrieve dimensional analytics data broken down by a specific parameter------import { TypeTable } from 'fumadocs-ui/components/type-table';--```-GET /api/metric/:site-```--Returns dimensional analytics data broken down by a specific parameter. Supports pagination.--## Path Parameters--<TypeTable- type={{- site: {- description: 'Site ID or site identifier',- type: 'string | number',- required: true,- },- }}-/>--## Query Parameters--Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) plus the following:--<TypeTable- type={{- parameter: {- description: 'The dimension to break down by',- type: 'FilterParameter',- typeDescription: 'e.g., "pathname", "country", "browser", "event_name"',- required: true,- },- limit: {- description: 'Number of results per page',- type: 'number',- default: 100,- },- page: {- description: 'Page number (1-indexed)',- type: 'number',- default: 1,- },- }}-/>--## Response--<TypeTable- type={{- data: {- description: 'Array of metric results',- type: 'MetricItem[]',- typeDescription: 'See MetricItem structure below',- },- totalCount: {- description: 'Total number of unique values across all pages',- type: 'number',- },- }}-/>--### MetricItem Structure--<TypeTable- type={{- value: {- description: 'The dimension value',- type: 'string',- typeDescription: 'e.g., "/blog", "Chrome", "US"',- },- count: {- description: 'Number of sessions for this value',- type: 'number',- },- percentage: {- description: 'Percentage of total sessions',- type: 'number',- typeDescription: 'Range: 0-100',- },- pageviews: {- description: 'Total pageviews (for page-related parameters)',- type: 'number',- required: false,- },- pageviews_percentage: {- description: 'Percentage of total pageviews',- type: 'number',- required: false,- },- time_on_page_seconds: {- description: 'Average time on page (for page-related parameters)',- type: 'number',- required: false,- },- bounce_rate: {- description: 'Bounce rate percentage',- type: 'number',- typeDescription: 'Range: 0-100',- required: false,- },- pathname: {- description: 'Representative pathname (for page_title parameter)',- type: 'string',- required: false,- },- }}-/>--## Example Request--```bash-curl -X GET "https://api.rybbit.com/api/metric/123?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10&page=1" \- -H "Authorization: Bearer your_api_key_here"-```--## Example Response--```json-{- "data": {- "data": [- {- "value": "US",- "count": 8420,- "percentage": 54.63,- "pageviews": 26891,- "pageviews_percentage": 54.96,- "bounce_rate": 41.2- },- {- "value": "GB",- "count": 2150,- "percentage": 13.95,- "pageviews": 6847,- "pageviews_percentage": 13.99,- "bounce_rate": 43.8- }- ],- "totalCount": 87- }-}-```--## Pagination Example--```bash-# Page 1-GET /api/metric/123?parameter=pathname&limit=50&page=1--# Page 2-GET /api/metric/123?parameter=pathname&limit=50&page=2-```diff --git a/docs/content/docs/api/stats/overview.mdx b/docs/content/docs/api/stats/overview.mdxindex eb011acf9..750791f88 100644--- a/docs/content/docs/api/stats/overview.mdx+++ b/docs/content/docs/api/stats/overview.mdx@@ -1,9 +1,41 @@----title: Get Overview+title: Overviewdescription: Retrieve high-level analytics metrics for a site+full: true---import { TypeTable } from 'fumadocs-ui/components/type-table';+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';++See the [API Reference](/docs/api/stats/reference) for authentication, common parameters, and filters.++## Endpoints++<div className="flex flex-col gap-2 my-6">+ <a href="#get-overview" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>+ <code className="text-sm">/api/overview/:site</code>+ </a>+ <a href="#get-overview-time-series" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>+ <code className="text-sm">/api/overview/:site/bucketed</code>+ </a>+ <a href="#get-metric" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>+ <code className="text-sm">/api/metric/:site</code>+ </a>+ <a href="#get-live-visitors" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>+ <code className="text-sm">/api/live-usercount/:site</code>+ </a>+</div>++---++## Get Overview++<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">+<div>```GET /api/overview/:site@@ -11,7 +43,7 @@ GET /api/overview/:siteReturns high-level analytics metrics for a site.-## Path Parameters+### Path Parameters<TypeTabletype={{@@ -23,11 +55,11 @@ Returns high-level analytics metrics for a site.}}/>-## Query Parameters+### Query Parameters-Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) (time and filters).+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) (time and filters).-## Response+### Response<TypeTabletype={{@@ -59,16 +91,52 @@ Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) (time a}}/>-## Example Request+</div>+<div className="flex flex-col gap-4">-```bash-curl -X GET "https://api.rybbit.com/api/overview/123?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \+<Tabs items={['cURL', 'JavaScript', 'Python']}>+ <Tab value="cURL">+```bash title="Request"+curl -X GET "https://api.rybbit.io/api/overview/123?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \-H "Authorization: Bearer your_api_key_here"```+ </Tab>+ <Tab value="JavaScript">+```javascript title="Request"+const response = await fetch(+ 'https://api.rybbit.io/api/overview/123?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',+ {+ headers: {+ 'Authorization': 'Bearer your_api_key_here'+ }+ }+);-## Example Response+const data = await response.json();+```+ </Tab>+ <Tab value="Python">+```python title="Request"+import requests++response = requests.get(+ 'https://api.rybbit.io/api/overview/123',+ params={+ 'start_date': '2024-01-01',+ 'end_date': '2024-01-31',+ 'time_zone': 'America/New_York'+ },+ headers={+ 'Authorization': 'Bearer your_api_key_here'+ }+)-```json+data = response.json()+```+ </Tab>+</Tabs>++```json title="Response"{"data": {"sessions": 15420,@@ -80,3 +148,482 @@ curl -X GET "https://api.rybbit.com/api/overview/123?start_date=2024-01-01&end_d}}```++</div>+</div>++---++## Get Overview (Time Series)++<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">+<div>++```+GET /api/overview/:site/bucketed+```++Returns time-series analytics data broken down by configurable time buckets. Useful for charting trends over time.++### Path Parameters++<TypeTable+ type={{+ site: {+ description: 'Site ID or site identifier',+ type: 'string | number',+ required: true,+ },+ }}+/>++### Query Parameters++Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) plus the following:++<TypeTable+ type={{+ bucket: {+ description: 'Time bucket size for grouping data',+ type: 'TimeBucket',+ typeDescription: '"minute" | "five_minutes" | "ten_minutes" | "fifteen_minutes" | "hour" | "day" | "week" | "month" | "year"',+ required: true,+ },+ }}+/>++#### Bucket Selection Guide++| Bucket | Best For |+|--------|----------|+| `minute` | Real-time monitoring (last hour) |+| `five_minutes` | Short-term analysis (last few hours) |+| `hour` | Daily analysis |+| `day` | Weekly/monthly analysis |+| `week` | Monthly/quarterly analysis |+| `month` | Yearly analysis |++### Response++<TypeTable+ type={{+ time: {+ description: 'Start of the time bucket',+ type: 'string',+ typeDescription: 'ISO 8601 datetime',+ },+ sessions: {+ description: 'Number of sessions in this bucket',+ type: 'number',+ },+ pageviews: {+ description: 'Number of pageviews in this bucket',+ type: 'number',+ },+ users: {+ description: 'Unique users in this bucket',+ type: 'number',+ },+ pages_per_session: {+ description: 'Average pages viewed per session',+ type: 'number',+ },+ bounce_rate: {+ description: 'Percentage of single-page sessions',+ type: 'number',+ typeDescription: 'Range: 0-100',+ },+ session_duration: {+ description: 'Average session duration in seconds',+ type: 'number',+ },+ }}+/>++</div>+<div className="flex flex-col gap-4">++<Tabs items={['cURL', 'JavaScript', 'Python']}>+ <Tab value="cURL">+```bash title="Request"+curl -X GET "https://api.rybbit.io/api/overview/123/bucketed?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \+ -H "Authorization: Bearer your_api_key_here"+```+ </Tab>+ <Tab value="JavaScript">+```javascript title="Request"+const response = await fetch(+ 'https://api.rybbit.io/api/overview/123/bucketed?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',+ {+ headers: {+ 'Authorization': 'Bearer your_api_key_here'+ }+ }+);++const data = await response.json();+```+ </Tab>+ <Tab value="Python">+```python title="Request"+import requests++response = requests.get(+ 'https://api.rybbit.io/api/overview/123/bucketed',+ params={+ 'bucket': 'day',+ 'start_date': '2024-01-01',+ 'end_date': '2024-01-07',+ 'time_zone': 'America/New_York'+ },+ headers={+ 'Authorization': 'Bearer your_api_key_here'+ }+)++data = response.json()+```+ </Tab>+</Tabs>++```json title="Response"+{+ "data": [+ {+ "time": "2024-01-01T00:00:00.000Z",+ "sessions": 1250,+ "pageviews": 3890,+ "users": 1100,+ "pages_per_session": 3.11,+ "bounce_rate": 41.5,+ "session_duration": 165.2+ },+ {+ "time": "2024-01-02T00:00:00.000Z",+ "sessions": 1420,+ "pageviews": 4520,+ "users": 1280,+ "pages_per_session": 3.18,+ "bounce_rate": 39.8,+ "session_duration": 178.4+ },+ {+ "time": "2024-01-03T00:00:00.000Z",+ "sessions": 1380,+ "pageviews": 4210,+ "users": 1190,+ "pages_per_session": 3.05,+ "bounce_rate": 42.1,+ "session_duration": 162.8+ }+ ]+}+```++</div>+</div>++---++## Get Metric++<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">+<div>++```+GET /api/metric/:site+```++Returns dimensional analytics data broken down by a specific parameter. Supports pagination.++### Path Parameters++<TypeTable+ type={{+ site: {+ description: 'Site ID or site identifier',+ type: 'string | number',+ required: true,+ },+ }}+/>++### Query Parameters++Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) plus the following:++<TypeTable+ type={{+ parameter: {+ description: 'The dimension to break down by',+ type: 'FilterParameter',+ typeDescription: 'e.g., "pathname", "country", "browser", "event_name"',+ required: true,+ },+ limit: {+ description: 'Number of results per page',+ type: 'number',+ default: 100,+ },+ page: {+ description: 'Page number (1-indexed)',+ type: 'number',+ default: 1,+ },+ }}+/>++### Response++<TypeTable+ type={{+ data: {+ description: 'Array of metric results',+ type: 'MetricItem[]',+ typeDescription: 'See MetricItem structure below',+ },+ totalCount: {+ description: 'Total number of unique values across all pages',+ type: 'number',+ },+ }}+/>++#### MetricItem Structure++<TypeTable+ type={{+ value: {+ description: 'The dimension value',+ type: 'string',+ typeDescription: 'e.g., "/blog", "Chrome", "US"',+ },+ count: {+ description: 'Number of sessions for this value',+ type: 'number',+ },+ percentage: {+ description: 'Percentage of total sessions',+ type: 'number',+ typeDescription: 'Range: 0-100',+ },+ pageviews: {+ description: 'Total pageviews (for page-related parameters)',+ type: 'number',+ required: false,+ },+ bounce_rate: {+ description: 'Bounce rate percentage',+ type: 'number',+ typeDescription: 'Range: 0-100',+ required: false,+ },+ }}+/>++</div>+<div className="flex flex-col gap-4">++<Tabs items={['cURL', 'JavaScript', 'Python']}>+ <Tab value="cURL">+```bash title="Request"+curl -X GET "https://api.rybbit.io/api/metric/123?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \+ -H "Authorization: Bearer your_api_key_here"+```+ </Tab>+ <Tab value="JavaScript">+```javascript title="Request"+const response = await fetch(+ 'https://api.rybbit.io/api/metric/123?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',+ {+ headers: {+ 'Authorization': 'Bearer your_api_key_here'+ }+ }+);++const data = await response.json();+```+ </Tab>+ <Tab value="Python">+```python title="Request"+import requests++response = requests.get(+ 'https://api.rybbit.io/api/metric/123',+ params={+ 'parameter': 'country',+ 'start_date': '2024-01-01',+ 'end_date': '2024-01-31',+ 'time_zone': 'America/New_York',+ 'limit': 10+ },+ headers={+ 'Authorization': 'Bearer your_api_key_here'+ }+)++data = response.json()+```+ </Tab>+</Tabs>++```json title="Response"+{+ "data": {+ "data": [+ {+ "value": "US",+ "count": 8420,+ "percentage": 54.63,+ "pageviews": 26891,+ "pageviews_percentage": 54.96,+ "bounce_rate": 41.2+ },+ {+ "value": "GB",+ "count": 2150,+ "percentage": 13.95,+ "pageviews": 6847,+ "pageviews_percentage": 13.99,+ "bounce_rate": 43.8+ }+ ],+ "totalCount": 87+ }+}+```++</div>+</div>++---++## Get Live Visitors++<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">+<div>++```+GET /api/live-usercount/:site+```++Returns the count of unique active sessions within the specified time window. Useful for displaying real-time visitor counts.++### Path Parameters++<TypeTable+ type={{+ site: {+ description: 'Site ID or site identifier',+ type: 'string | number',+ required: true,+ },+ }}+/>++### Query Parameters++<TypeTable+ type={{+ minutes: {+ description: 'Time window in minutes to count active sessions',+ type: 'number',+ default: 5,+ typeDescription: 'Sessions with activity within the last N minutes are considered "live"',+ },+ }}+/>++### Response++<TypeTable+ type={{+ count: {+ description: 'Number of unique active sessions',+ type: 'number',+ },+ }}+/>++#### Time Window Guide++| Minutes | Use Case |+|---------|----------|+| `1` | Very active visitors (currently browsing) |+| `5` | Standard "live" count (default) |+| `15` | Recently active visitors |+| `30` | Short-term engagement window |++</div>+<div className="flex flex-col gap-4">++<Tabs items={['cURL', 'JavaScript', 'Python']}>+ <Tab value="cURL">+```bash title="Request"+curl -X GET "https://api.rybbit.io/api/live-usercount/123?minutes=5" \+ -H "Authorization: Bearer your_api_key_here"+```+ </Tab>+ <Tab value="JavaScript">+```javascript title="Request"+const response = await fetch(+ 'https://api.rybbit.io/api/live-usercount/123?minutes=5',+ {+ headers: {+ 'Authorization': 'Bearer your_api_key_here'+ }+ }+);++const { count } = await response.json();+console.log(`Live visitors: ${count}`);+```+ </Tab>+ <Tab value="Python">+```python title="Request"+import requests++response = requests.get(+ 'https://api.rybbit.io/api/live-usercount/123',+ params={'minutes': 5},+ headers={+ 'Authorization': 'Bearer your_api_key_here'+ }+)++data = response.json()+print(f"Live visitors: {data['count']}")+```+ </Tab>+</Tabs>++```json title="Response"+{+ "count": 42+}+```++### Polling Example++```javascript title="Real-time Widget"+async function updateLiveCount() {+ const response = await fetch(+ 'https://api.rybbit.io/api/live-usercount/123?minutes=5',+ {+ headers: {+ 'Authorization': 'Bearer your_api_key'+ }+ }+ );+ const { count } = await response.json();+ document.getElementById('live-visitors')+ .textContent = count;+}++// Update every 15 seconds+setInterval(updateLiveCount, 15000);+```++</div>+</div>diff --git a/docs/content/docs/api/stats/guide.mdx b/docs/content/docs/api/stats/reference.mdxsimilarity index 98%rename from docs/content/docs/api/stats/guide.mdxrename to docs/content/docs/api/stats/reference.mdxindex dc9516960..98bba55b0 100644--- a/docs/content/docs/api/stats/guide.mdx+++ b/docs/content/docs/api/stats/reference.mdx@@ -1,12 +1,10 @@----title: Stats API Guide+title: API Referencedescription: Authentication, common parameters, and best practices for the Rybbit Stats API---import { TypeTable } from 'fumadocs-ui/components/type-table';-The Rybbit API allows you to programmatically access your analytics data. All analytics endpoints are read-only and require authentication via API keys.-## AuthenticationAll API requests must include authentication using one of the following methods:@@ -42,6 +40,8 @@ API keys are user-scoped and grant organization-level access:- **500 requests per 10 minutes** per API key- Keys are tied to your user account and grant access to all sites in your organization(s)+---+## Common ParametersThe following parameters are shared across all analytics endpoints.@@ -415,7 +415,6 @@ The `filters` parameter accepts a JSON-encoded array of filter objects to narrow]```-**URL-encoded:**```?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D