406 lines
8.7 KiB
Plaintext
406 lines
8.7 KiB
Plaintext
---
|
|
title: Insights
|
|
description: The Insights API provides access to website analytics data including metrics, page views, visitor statistics, and detailed breakdowns by various dimensions.
|
|
---
|
|
|
|
## Authentication
|
|
|
|
To authenticate with the Insights API, you need to use your `clientId` and `clientSecret`. Make sure your client has `read` or `root` mode. The default client does not have access to the Insights API.
|
|
|
|
For detailed authentication information, see the [Authentication](/docs/api/authentication) guide.
|
|
|
|
Include the following headers with your requests:
|
|
- `openpanel-client-id`: Your OpenPanel client ID
|
|
- `openpanel-client-secret`: Your OpenPanel client secret
|
|
|
|
## Base URL
|
|
|
|
All Insights API requests should be made to:
|
|
|
|
```
|
|
https://api.openpanel.dev/insights
|
|
```
|
|
|
|
## Common Query Parameters
|
|
|
|
Most endpoints support the following query parameters:
|
|
|
|
| Parameter | Type | Description | Default |
|
|
|-----------|------|-------------|---------|
|
|
| `startDate` | string | Start date (ISO format: YYYY-MM-DD) | Based on range |
|
|
| `endDate` | string | End date (ISO format: YYYY-MM-DD) | Based on range |
|
|
| `range` | string | Predefined date range (`7d`, `30d`, `90d`, etc.) | `7d` |
|
|
| `filters` | array | Event filters to apply | `[]` |
|
|
| `cursor` | number | Page number for pagination | `1` |
|
|
| `limit` | number | Number of results per page (max: 50) | `10` |
|
|
|
|
### Filter Configuration
|
|
|
|
Filters can be applied to narrow down results. Each filter has the following structure:
|
|
|
|
```json
|
|
{
|
|
"name": "property_name",
|
|
"operator": "is|isNot|contains|doesNotContain|startsWith|endsWith|regex",
|
|
"value": ["value1", "value2"]
|
|
}
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Get Metrics
|
|
|
|
Retrieve comprehensive website metrics including visitors, sessions, page views, and engagement data.
|
|
|
|
```
|
|
GET /insights/{projectId}/metrics
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Description | Example |
|
|
|-----------|------|-------------|---------|
|
|
| `startDate` | string | Start date for metrics | `2024-01-01` |
|
|
| `endDate` | string | End date for metrics | `2024-01-31` |
|
|
| `range` | string | Predefined range | `7d` |
|
|
| `filters` | array | Event filters | `[{"name":"path","operator":"is","value":["/home"]}]` |
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/metrics?range=30d&filters=[{"name":"path","operator":"contains","value":["/product"]}]' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"metrics": {
|
|
"bounce_rate": 45.2,
|
|
"unique_visitors": 1250,
|
|
"total_sessions": 1580,
|
|
"avg_session_duration": 185.5,
|
|
"total_screen_views": 4230,
|
|
"views_per_session": 2.67
|
|
},
|
|
"series": [
|
|
{
|
|
"date": "2024-01-01T00:00:00.000Z",
|
|
"bounce_rate": 42.1,
|
|
"unique_visitors": 85,
|
|
"total_sessions": 98,
|
|
"avg_session_duration": 195.2,
|
|
"total_screen_views": 156,
|
|
"views_per_session": 1.59
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get Live Visitors
|
|
|
|
Get the current number of active visitors on your website in real-time.
|
|
|
|
```
|
|
GET /insights/{projectId}/live
|
|
```
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/live' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"visitors": 23
|
|
}
|
|
```
|
|
|
|
### Get Top Pages
|
|
|
|
Retrieve the most visited pages with detailed analytics including session count, bounce rate, and average time on page.
|
|
|
|
```
|
|
GET /insights/{projectId}/pages
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Description | Example |
|
|
|-----------|------|-------------|---------|
|
|
| `startDate` | string | Start date | `2024-01-01` |
|
|
| `endDate` | string | End date | `2024-01-31` |
|
|
| `range` | string | Predefined range | `7d` |
|
|
| `filters` | array | Event filters | `[]` |
|
|
| `cursor` | number | Page number | `1` |
|
|
| `limit` | number | Results per page (max: 50) | `10` |
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/pages?range=7d&limit=20' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"title": "Homepage - Example Site",
|
|
"origin": "https://example.com",
|
|
"path": "/",
|
|
"sessions": 456,
|
|
"bounce_rate": 35.2,
|
|
"avg_duration": 125.8
|
|
},
|
|
{
|
|
"title": "About Us",
|
|
"origin": "https://example.com",
|
|
"path": "/about",
|
|
"sessions": 234,
|
|
"bounce_rate": 45.1,
|
|
"avg_duration": 89.3
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Referrer Data
|
|
|
|
Retrieve referrer analytics to understand where your traffic is coming from.
|
|
|
|
```
|
|
GET /insights/{projectId}/referrer
|
|
GET /insights/{projectId}/referrer_name
|
|
GET /insights/{projectId}/referrer_type
|
|
```
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/referrer?range=30d&limit=15' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "google.com",
|
|
"sessions": 567,
|
|
"bounce_rate": 42.1,
|
|
"avg_session_duration": 156.7
|
|
},
|
|
{
|
|
"name": "facebook.com",
|
|
"sessions": 234,
|
|
"bounce_rate": 38.9,
|
|
"avg_session_duration": 189.2
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get UTM Campaign Data
|
|
|
|
Analyze your marketing campaigns with UTM parameter breakdowns.
|
|
|
|
```
|
|
GET /insights/{projectId}/utm_source
|
|
GET /insights/{projectId}/utm_medium
|
|
GET /insights/{projectId}/utm_campaign
|
|
GET /insights/{projectId}/utm_term
|
|
GET /insights/{projectId}/utm_content
|
|
```
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/utm_source?range=30d' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "google",
|
|
"sessions": 890,
|
|
"bounce_rate": 35.4,
|
|
"avg_session_duration": 178.9
|
|
},
|
|
{
|
|
"name": "facebook",
|
|
"sessions": 456,
|
|
"bounce_rate": 41.2,
|
|
"avg_session_duration": 142.3
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Geographic Data
|
|
|
|
Understand your audience location with country, region, and city breakdowns.
|
|
|
|
```
|
|
GET /insights/{projectId}/country
|
|
GET /insights/{projectId}/region
|
|
GET /insights/{projectId}/city
|
|
```
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/country?range=30d&limit=20' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "United States",
|
|
"sessions": 1234,
|
|
"bounce_rate": 38.7,
|
|
"avg_session_duration": 167.4
|
|
},
|
|
{
|
|
"name": "United Kingdom",
|
|
"sessions": 567,
|
|
"bounce_rate": 42.1,
|
|
"avg_session_duration": 145.8
|
|
}
|
|
]
|
|
```
|
|
|
|
For region and city endpoints, an additional `prefix` field may be included:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"prefix": "United States",
|
|
"name": "California",
|
|
"sessions": 456,
|
|
"bounce_rate": 35.2,
|
|
"avg_session_duration": 172.1
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Device & Technology Data
|
|
|
|
Analyze visitor devices, browsers, and operating systems.
|
|
|
|
```
|
|
GET /insights/{projectId}/device
|
|
GET /insights/{projectId}/browser
|
|
GET /insights/{projectId}/browser_version
|
|
GET /insights/{projectId}/os
|
|
GET /insights/{projectId}/os_version
|
|
GET /insights/{projectId}/brand
|
|
GET /insights/{projectId}/model
|
|
```
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/abc123/browser?range=7d' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "Chrome",
|
|
"sessions": 789,
|
|
"bounce_rate": 36.4,
|
|
"avg_session_duration": 162.3
|
|
},
|
|
{
|
|
"name": "Firefox",
|
|
"sessions": 234,
|
|
"bounce_rate": 41.7,
|
|
"avg_session_duration": 148.9
|
|
}
|
|
]
|
|
```
|
|
|
|
For version-specific endpoints (browser_version, os_version), a `prefix` field shows the parent:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"prefix": "Chrome",
|
|
"name": "118.0.0.0",
|
|
"sessions": 456,
|
|
"bounce_rate": 35.8,
|
|
"avg_session_duration": 165.7
|
|
}
|
|
]
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The API uses standard HTTP response codes. Common error responses:
|
|
|
|
### 400 Bad Request
|
|
|
|
```json
|
|
{
|
|
"error": "Bad Request",
|
|
"message": "Invalid query parameters",
|
|
"details": {
|
|
"issues": [
|
|
{
|
|
"path": ["range"],
|
|
"message": "Invalid enum value"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 401 Unauthorized
|
|
|
|
```json
|
|
{
|
|
"error": "Unauthorized",
|
|
"message": "Invalid client credentials"
|
|
}
|
|
```
|
|
|
|
### 429 Too Many Requests
|
|
|
|
Rate limiting response includes headers indicating your rate limit status.
|
|
|
|
## Rate Limiting
|
|
|
|
The Insights API implements rate limiting:
|
|
- **100 requests per 10 seconds** per client
|
|
- Rate limit headers included in responses
|
|
- Implement exponential backoff for retries
|
|
|
|
## Notes
|
|
|
|
- All dates are returned in ISO 8601 format
|
|
- Durations are in seconds
|
|
- Bounce rates and percentages are returned as decimal numbers (e.g., 45.2 = 45.2%)
|
|
- Session duration is the average time spent on the website
|
|
- All timezone handling is done server-side based on project settings
|