API
26. May, 2022This document describes the REST endpoints used to interact with Pirsch. The easiest way to get started is through one of the client SDKs. If you’re looking on how you can integrate Pirsch into your backend to monitor traffic, please check out the backend integration.
To use the API, you must create a client. New clients can be created on the settings page or on the account page.
Note that all samples do not necessarily show correct data. IDs from a request might not match the response. You should also be careful not to confuse IDs in their context. Fields are oftentimes just called id, but represent different objects.
Error Handling
In case of an error, Pirsch will return a JSON object in the body describing the issue and what you can do about it together with a meaningful HTTP status code. Errors have the following structure.
|
|
validation
lists errors related to input parameterserror
lists general errors, like when an object could’nt be found. There will usually be only one error message
Getting an Access Token
To make requests to the API, you need to get an access token first. The token must be send with every request in the Authorization
header in the format Bearer <token>
. If you receive a status code 401 (unauthorized), you need to create a new access token and try again. expires_at
timezone is set to UTC.
Client IDs and secrets can be created from the domain settings page (under Developer) or from the account settings page. Domain clients are created for a specific domain and can only access and manipulate the domain they were created for. User clients have more privileges and can access all domains the user has access to (with the same permissions, viewer, or admin).
Single access tokens (starting with pa_
) can only be used to send data (page views, events, and keep alive sessions) and don’t require a client ID, nor do they need to be refreshed. Treat both, client secrets and single access tokens, as passwords and store them securely.
The examples for the other endpoints in this document will omit the header.
Example request
|
|
Example response
|
|
Sending a Page Hit
This endpoint is used to send page hits to Pirsch. It requires you to send information about the request made by the client. How you get these depends on the programming language and framework you’re using. The example shows which fields are required and which are optional. We recommend sending all of them to make the results as accurate as possible.
Example request
|
|
One small optimization you can make is to check the DNT
(Do Not Track) header before you make the request. Check if the header is set to 1
, if true you can ignore the request, otherwise send it.
Sending an Event
This endpoint is used to send events to Pirsch. It requires you to send information about the request made by the client. How you get these depends on the programming language and framework you’re using. The example shows which fields are required and which are optional. We recommend sending all of them to make the results as accurate as possible.
Example request
Fields with underscores are comments.
|
|
Keeping a Session Alive
This endpoint is used to manually keep sessions alive. A session will usually be reset if no request (hit or event) is sent within a 30-minute timeframe. This feature can be used to extend a session indefinitely. It’s not recommended to use this for regular websites, but can be useful to track apps or other custom build software.
Example request
|
|
Statistics
The following endpoints can be used to read statistics from Pirsch. To receive data, you need to set the filter. It will be skipped in the example requests for brevity.
Filter
The following list contains all possible filter options. Only the required fields need to be set when making a request. Set the fields using URL query parameters, like ?from=2021-05-08&to=2021-05-15&language=en
.
Parameter | Required | Example | Format/Description |
---|---|---|---|
id | yes | A5kgYzK14m | The domain ID. Use the list endpoint to get the domain ID for the client. |
from | yes | 2021-05-08 | YYYY-MM-DD |
to | yes | 2021-05-15 | YYYY-MM-DD |
start | no | 600 | Queries data for the past seconds (10 minutes in this example). The date range filters will be ignored if set. The maximum is one hour (3600 seconds). |
scale | no | week | The scale to group results. Can either be day (default), week, month, or year. |
path | no | /home | The page path. |
entry_path | no | /home | The entry page path. |
exit_path | no | /yte | The exit page path. |
pattern | no | (?i)^\/path/[^\/]+$ | A regular expression to filter and group pages. This option is used with conversion goals |
event | no | Button clicked | The name of an event to filter for. |
event_meta_key | no | Clicks | The event meta key to filter for. This field is used to break down a single event. |
meta_(key) | no | meta_key0=value0&meta_key1=value1 |
The event metadata key and values to filter for. Multiple keys can be set by prefixing them using meta_ and appending them to the URL. Only events with all key-value pairs will be returned. |
language | no | en | ISO-639-1 language code, like en for English. |
country | no | jp | ISO-3166 Alpha-2 country code, like jp for Japan. |
city | no | London | Name of a city. |
referrer | no | https://referring-website.com/ | The referrer, usually a URL or name (note that the Pirsch dashboard does trim the protocol). |
referrer_name | no | referring-website.com | The referrer name, usually the hostname. |
os | no | Windows | The operating system. |
browser | no | Firefox | The browser. |
platform | no | desktop | The platform, desktop, mobile, or unknown (not set). |
screen_class | no | XXL | The screen class, XXL, XL, L, M, S. |
screen_width | no | 1920 | The screen width. Note that this is a string and not a number! |
screen_height | no | 1080 | The screen height. Note that this is a string and not a number! |
utm_source | no | Newsletter | The UTM source. |
utm_medium | no | The UTM medium. | |
utm_campaign | no | Summer Sale | The UTM campaign. |
utm_content | no | Header | The UTM content. |
utm_term | no | search terms | The UTM term. |
limit | no | 20 | Limits the number of results, note that this is hard limited to 100. |
include_avg_time_on_page | no | true | Set to true, to include the average time on page when reading page statistics. |
sort | no | visitors | Sort results by given field. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics. |
direction | no | desc | Sort results in ascending (asc) or descending (desc) order. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics. |
search | no | /home | Search the primary field for given string (contains). For pages this will be the path, for browsers the browser name, and so on. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics. |
Getting the Domain ID
Before you can make requests, you need to know the domain ID for the client. Make a request to the following endpoint and store the ID for the domain. Note that the domain will be returned in an array. The endpoint usually returns all domains a user has access to, but in this case it will always have one entry (except there is some permission error, then it will be empty).
Example request
GET /api/v1/domain
Example response
|
|
Session Duration
Example request
GET /api/v1/statistics/duration/session
Example response
Which time component is set depends on the scale
filter. Setting it to day
(default) sets the day
field. Otherwise the corresponding field will be set.
|
|
Time on Page
Example request
GET /api/v1/statistics/duration/page
Example response
Which time component is set depends on the scale
filter. Setting it to day
(default) sets the day
field. Otherwise the corresponding field will be set.
|
|
UTM Source
Example request
GET /api/v1/statistics/utm/source
Example response
|
|
UTM Medium
Example request
GET /api/v1/statistics/utm/medium
Example response
|
|
UTM Campaign
Example request
GET /api/v1/statistics/utm/campaign
Example response
|
|
UTM Content
Example request
GET /api/v1/statistics/utm/content
Example response
|
|
UTM Term
Example request
GET /api/v1/statistics/utm/term
Example response
|
|
Total Visitors
This endpoint returns the total visitor count, views, sessions, bounces, and bounce rate. The difference to the visitors’ endpoint (see below) is that the results are not grouped by day. Manually summing up the visitors for multiple days will return a different result, as returning visitors will be counted multiple times that way.
Example request
GET /api/v1/statistics/total
Example response
|
|
Visitors
Example request
GET /api/v1/statistics/visitor
Example response
Which time component is set depends on the scale
filter. Setting it to day
(default) sets the day
field. Otherwise the corresponding field will be set.
|
|
Pages
Example request
GET /api/v1/statistics/page
Example response
|
|
Entry Pages
Example request
GET /api/v1/statistics/page/entry
Example response
|
|
Exit Pages
Example request
GET /api/v1/statistics/page/exit
Example response
|
|
Conversion Goals
Example request
GET /api/v1/statistics/goals
Example response
|
|
pattern
is the regex pattern stored for the conversion goal and can be used as the pattern
parameter in the filter. path_pattern
is the path pattern as configured by the user on the dashboard. The pattern
will be generated from it.
Events
This endpoint lists all events and their metadata keys. You can use the event metadata endpoint to receive the values for the event and a key.
Example request
GET /api/v1/statistics/events
Example response
|
|
Event Metadata
This endpoint will break down the event meta keys and values for a single event. You must filter for an event name and meta key in order for this to work.
Example request
GET /api/v1/statistics/event/meta
Example response
|
|
Listing Events
This endpoint will list all events including metadata. Note that this can be an expensive operation if you select events without filtering. The events will be grouped by name and metadata. We recommend filtering by path (“all events on this page”) and optionally metadata key-value pairs.
Example request
GET /api/v1/statistics/event/list
Example response
|
|
Growth Rates
Example request
GET /api/v1/statistics/growth
Example response
|
|
Active Visitors
Returns active visitors and pages for the past n seconds. n can be defined by passing the start
query parameter and will be set to 10 minutes by default.
Example request
Return the active visitors for the past minute.
GET /api/v1/statistics/active?start=60
Example response
|
|
Visitors by Time of Day
Example request
GET /api/v1/statistics/hours
Example response
|
|
Languages
Example request
GET /api/v1/statistics/language
Example response
|
|
Referrer
Example request
GET /api/v1/statistics/referrer
Example response
|
|
Operating System
Example request
GET /api/v1/statistics/os
Example response
|
|
Operating System Version
Example request
GET /api/v1/statistics/os
Example response
|
|
Browser
Example request
GET /api/v1/statistics/browser
Example response
|
|
Browser Version
Example request
GET /api/v1/statistics/browser/version
Example response
|
|
Country
Example request
GET /api/v1/statistics/country
Example response
|
|
City
Example request
GET /api/v1/statistics/city
Example response
|
|
Platform
Example request
GET /api/v1/statistics/platform
Example response
|
|
Screen Classes
Example request
GET /api/v1/statistics/screen
Example response
|
|
Keywords
This endpoints requires the Google Search Console integration. We recommend using the Search Console API directly instead of calling it through Pirsch.
Example request
GET /api/v1/statistics/keywords
Example response
|
|
Managing Domains
Domains can be managed by creating a user client (on the account settings page).
Creating a Domain
This endpoint adds a new domain.
Example request
POST /api/v1/domain
|
|
Example response
|
|
Deleting a Domain
This endpoint deletes a domain.
Example request
DELETE /api/v1/domain?id=A5kgYzK14m
Listing Domains
This endpoint is described in the statistics section. The only difference is that it will return all domains if you use a user client.
Resetting the Identification Code
This endpoint will reset the identifcation code for the domain and returns a new one.
Example request
PUT /api/v1/domain
|
|
Example response
|
|
Updating the Subdomain
This endpoint will update the subdomain for your dashboard (on your-sub-domain.pirsch.io
).
Example request
POST /api/v1/domain/subdomain
|
|
Toggle the Visiblity of Your Dashboard
This endpoint will toggle the visibility of your dashboard from private to public or vise-versa.
Example request
POST /api/v1/domain/subdomain
|
|
Toggle Grouping by Title
This endpoint will toggle if statistics are grouped by page title.
Example request
POST /api/v1/domain/title
|
|
Changing the Timezone
This endpoint will change the timezone for the dashboard.
Example request
POST /api/v1/domain/timezone
|
|
Managing Access Links
Listing Access Links
This endpoint lists all access links.
Example request
GET /api/v1/domain/link?domain_id=A5kgYzK14m
Example response
|
|
The code can be used to create a URL with read access to a domain. To do that, replace <subdomain>
and <code
for the domain in the following URL: https://<subdomain>.pirsch.io/?access=<code>
Creating an Access Link
This endpoint creates a new access link.
Example request
POST /api/v1/domain/link
|
|
Example response
|
|
Updating an Access Link
This endpoint updates an existing access link.
Example request
PUT /api/v1/domain/link
|
|
Deleting an Access Link
This endpoint deletes an access link.
Example request
DELETE /api/v1/domain/link?id=0DJ0mo934
Managing Members and Permissions
Listing Members
This endpoint lists all members.
Example request
GET /api/v1/member?id=A5kgYzK14m
Example response
|
|
Inviting Members
This endpoints invites new member to a domain by email. New members will have the Viewer role.
Example request
POST /api/v1/member
|
|
id
is the domain ID.
Updating the Role of a Member
This endpoint will update the role of a single member. Valid roles are Viewer and Admin (the Owner role requires a domain transfer).
Example request
PUT /api/v1/member
|
|
id
is the member ID.
Removing a Member
This endpoints removes a member from a domain.
Example request
DELETE /api/v1/member?id=0DJ0mo934
Managing Alternative Domains
Alternative domains need to be created when you send statistics to multiple dashboards or create rollup views.
Listing Alternative Domains
This endpoint returns all alternative domains belonging to a website.
Example request
GET /api/v1/domain/alternative?domain_id=0DJ0mo934
Example response
|
|
Creating Alternative Domains
This endpoint creates a new alternative domain for a website.
Example request
POST /api/v1/domain/alternative
|
|
Example response
|
|
Updating Alternative Domains
This endpoint updates the hostname for an alternative domain.
Example request
PUT /api/v1/domain/alternative
|
|
Deleting Alternative Domains
This endpoint deletes an alternative domain by ID.
Example request
DELETE /api/v1/domain/alternative?id=A5kgYzK14m
Managing Clients
It’s possible to manage domain clients with a user client.
Listing Clients
This endpoint will list all clients.
Example request
GET /api/v1/client?id=0DJ0mo934
Example response
|
|
Creating a Client
This endpoint will create a new client.
Example request
POST /api/v1/client
|
|
Scopes can give read or write access. The table below shows which values are possible for available scopes.
Scope | Read | Write |
---|---|---|
hit | x | |
event | x | |
statistics | x | |
domains | x | x |
The domains
scope has two different meanins, depending on if it’s used for a domain or user client:
- for user clients, it will give access to most of the user actions, like creating or deleting domains and settings
- for domain clients, it will give access to domain specific settings, like the subdomain or access links
Example response
|
|
Updating a Client
This endpoint will update the description for a client.
Example request
POST /api/v1/client
|
|
Example response
|
|
Deleting a Client
This endpoint will delete a client.
DELETE /api/v1/client?id=A5kgYzK14m
Managing Email Reports
Listing Email Reports
This endpoint will list all email reports.
Example request
GET /api/v1/report?id=0DJ0mo934
Example response
|
|
Creating Email Reports
This endpoint will create a new email report.
Example request
POST /api/v1/report
|
|
Example response
|
|
Updating an Email Report
This endpoint will update an existing email report.
Example request
PUT /api/v1/report
|
|
Example response
|
|
Deleting an Email Report
This endpoint will delete an email report.
Example request
DELETE /api/v1/report?id=A5kgYzK14m
Managing Conversion Goals
Listing Conversion Goals
This endpoint will list all conversion goals.
Example request
GET /api/v1/goal?id=0DJ0mo934
Example response
|
|
Creating a Conversion Goal
This endpoint will create a new conversion goal.
Example request
POST /api/v1/goal
|
|
Example response
|
|
Updating a Conversion Goal
This endpoint will update an existing converion goal.
Example request
PUT /api/v1/goal
|
|
Example response
|
|
Deleting a Conversion Goal
This endpoint will delete a conversion goal.
Example request
DELETE /api/v1/goal?id=A5kgYzK14m
Testing the Regular Expression for a Conversion Goal
This endpoint will test if a regular expression is valid for a conversion goal. Use it to see if you can use an expression before creating or updating a conversion goal fist.
Example request
POST /api/v1/goal/regex
|
|
Example response
|
|
An error will be returned in case the expression is invalid. Otherwise it will return if the regular expression matches the sample.