Skip to content

Commit afdab0c

Browse files
macobomacobo
committed
Add more content
1 parent e9ab2cd commit afdab0c

File tree

1 file changed

+120
-6
lines changed

1 file changed

+120
-6
lines changed

‎docs/stats-api-v2.md

+120-6
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: Stats API v2 reference
33
---
44

55
import ApiV2Example from '../src/js/apiv2-example.js';
6+
import {Required, Optional} from '../src/js/api-helpers.js';
67

78

89
:::warning
@@ -13,7 +14,7 @@ Please be advised that this feature is currently in its beta stage. Some functio
1314

1415
The Plausible Stats API offers a way to retrieve your stats programmatically. It's a read-only interface to present historical and real-time stats only. Take a look at our [events API](events-api.md) if you want to send pageviews or custom events to our backend and our [sites API](sites-api.md) if you want to manage your sites through the API.
1516

16-
The API accepts POST requests with query parameters and returns standard HTTP responses along with a JSON-encoded body. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
17+
`/api/v2/query` endpoint accepts POST requests with query parameters and returns standard HTTP responses along with a JSON-encoded body. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
1718

1819
## Authentication
1920

@@ -33,13 +34,126 @@ curl \
3334

3435
API keys have a rate limit of 600 requests per hour by default. If you have special needs for more requests, please contact us to request more capacity.
3536

36-
## Query API specification
37+
## Request structure
38+
39+
`/api/v2/query` endpoint accepts a `query` object. The following keys can be passed with a request.
40+
41+
### site_id <Required />
42+
43+
Domain of your site on Plausible to be queried.
44+
45+
### date_range <Required />
46+
47+
Date range to be queried.
48+
49+
| Option | Description |
50+
| --- | --- |
51+
| `["2024-01-01", "2024-07-01"]` | Custom date range (ISO8601) |
52+
| `"day"` | Current day (e.g. 2024-07-01) |
53+
| `"7d"` | Last 7 days relative to today |
54+
| `"30d"` | Last 30 days relative to today |
55+
| `"month"` | Since the start of the current month |
56+
| `"6mo"` | Last 6 months relative to start of this month |
57+
| `"12mo"` | Last 12 months relative to start of this month |
58+
| `"year"` | Since the start of this year |
59+
| `"all"` | Since the start of stats in Plausible |
60+
61+
### metrics <Required />
62+
63+
Metrics represent values to be calculated with the query.
64+
65+
Valid metrics are:
66+
67+
| Metric name | Description |
68+
| --- | --- |
69+
| `visitors` | The number of unique visitors |
70+
| `visits` | The number of visits/sessions |
71+
| `pageviews` | The number of pageview events |
72+
| `views_per_visit` | The number of pageviews divided by the number of visits. Returns a floating point number. |
73+
| `bounce_rate` | Bounce rate percentage |
74+
| `visit_duration` | Visit duration in seconds |
75+
| `events` | The number of events (pageviews + custom events). When filtering by a goal, this metric corresponds to "Total Conversions" in the dashboard. |
76+
| `percentage` | The percentage of visitors of total who fall into this category: Requires: dimension list |
77+
| `conversion_rate` | The percentage of visitors who completed the goal. Requires: dimension list passed, an event:goal filter or event:goal dimension |
78+
| `group_conversion_rate` | The percentage of visitors who completed the goal with the same dimension. Requires: dimension list passed, an event:goal filter or event:goal dimension |
79+
80+
### dimensions <Optional />
81+
82+
Default: `[]`
83+
84+
List of dimensions to group by.
85+
86+
Dimensions are attributes of your dataset. Using them in queries enables analyzing and compare multiple groups against each other.
87+
Think of them as `GROUP BY` in SQL.
88+
89+
Valid dimensions include:
90+
91+
| Dimension | Example | Description |
92+
| --- | --- | --- |
93+
| `event:goal` | Register | A custom action that you want your users to take. To use this dimension, you first need to configure some goals in the site settings, or via the Sites API. Learn more about goals here. |
94+
| `event:page` | /blog/remove-google-analytics | Pathname of the page where the event is triggered. You can also use an asterisk to group multiple pages (/blog*) |
95+
| `event:hostname` | example.com | Hostname of the event. |
96+
| `visit:entry_page` | /home | Page on which the visit session started (landing page). |
97+
| `visit:exit_page` | /home | Page on which the visit session ended (last page viewed). |
98+
| `visit:source` | Twitter | Visit source, populated from an url query parameter tag (utm_source, source or ref) or the Referer HTTP header. |
99+
| `visit:referrer` | t.co/fzWTE9OTPt | Raw Referer header without http://, http:// or www.. |
100+
| `visit:utm_medium` | social | Raw value of the utm_medium query param on the entry page. |
101+
| `visit:utm_source` | twitter | Raw value of the utm_source query param on the entry page. |
102+
| `visit:utm_campaign` | profile | Raw value of the utm_campaign query param on the entry page. |
103+
| `visit:utm_content` | banner | Raw value of the utm_content query param on the entry page. |
104+
| `visit:utm_term` | keyword | Raw value of the utm_term query param on the entry page. |
105+
| `visit:device` | Desktop | Device type. Possible values are Desktop, Laptop, Tablet and Mobile. |
106+
| `visit:browser` | Chrome | Name of the browser vendor. Most popular ones are Chrome, Safari and Firefox. |
107+
| `visit:browser_version` | 88.0.4324.146 | Version number of the browser used by the visitor. |
108+
| `visit:os` | Mac | Name of the operating system. Most popular ones are Mac, Windows, iOS and Android. Linux distributions are reported separately. |
109+
| `visit:os_version` | 10.6 | Version number of the operating system used by the visitor. |
110+
| `visit:country` | US | ISO 3166-1 alpha-2 code of the visitor country. |
111+
| `visit:region` | US-MD | ISO 3166-2 code of the visitor region. |
112+
| `visit:city` | 4347778 | GeoName ID of the visitor city. |
113+
| `visit:country_name` | United States | Name of the visitor country. |
114+
| `visit:region_name` | California | Name of the visitor region. |
115+
| `visit:city_name` | San Francisco | Name of the visitor city. |
116+
| `time` | 2024-01-01 | Time or date to group by. Automatically figures out the appropriate time:bucket value from date range. Response is a valid ISO8601 date or timestamp |
117+
| `time:hour` | 2021-01-27T23:43:10Z | Time grouped by hour. ISO8601 |
118+
| `time:day` | 2021-01-27 | Time grouped by date |
119+
| `time:week` | 2021-01-04 | Time grouped by start of the week |
120+
| `time:month` | 2021-01-01 | Time grouped by start of month |
121+
122+
:::warning
123+
124+
Mixing session metrics `bounce_rate`, `views_per_visit` and `visit_duration` with event dimensions is not allowed.
125+
:::
126+
127+
#### Custom properties
128+
129+
[Custom properties](/custom-props/introduction) can also be used as dimensions with the form `event:props:<custom_prop_name>`. [See example](#custom-properties-example)
130+
131+
### filters <Optional />
132+
133+
Default: `[]`
134+
135+
Filters allow limiting the data analyzed in a query. Each filter takes the form of `[operator, dimension, list_of_values]`. See [example](#filtering-basic).
136+
137+
#### operators
138+
139+
The following operators are supported
140+
141+
| Operator | Example | Explanation |
142+
| -- | -- | -- |
143+
| `is` | `["is", "visit:country_name", ["Germany", "Poland"]]` | Sessions originating from Germany or Poland. |
144+
| `is_not` | `["is_not", "event:page", ["/pricing"]]` | Events that did not visit /pricing page |
145+
| `matches` | `["matches", "visit:browser_version", ["88.*", "89.*"]]` | Sessions from browser versions starting with 88 or 89 |
146+
| `does_not_match` | `["does_not_match", "event:page", ["/login*"]]` | Events that did not visit any page starting with /login |
147+
148+
`matches` and `does_not_match` uses XXX system for matching. TODO
149+
150+
### include <Optional />
37151

38152
## Examples
39153

40-
:::warning
154+
:::tip
41155

42-
The following example queries are interactive and can be edited as needed.
156+
The following example queries are interactive and can be edited and run against your own data.
43157
:::
44158

45159
### Simple aggregate query {#aggregate}
@@ -52,7 +166,7 @@ The following example queries are interactive and can be edited as needed.
52166

53167
### Best-performing UTM tags
54168

55-
### Filtering by utm
169+
### Filtering by utm and country {#filtering-basic}
56170

57171
Event, visit and custom properties
58172

@@ -68,7 +182,7 @@ Event, visit and custom properties
68182

69183
### Timeseries query with labels
70184

71-
185+
### Using custom properties {#custom-properties-example}
72186

73187
### Multiple dimensions
74188

0 commit comments

Comments
 (0)