Export API 
With this API you can export raw data points (without sampling). Data points are both page views and events combined. Define a date range and it pulls out the data. The response will only include the selected fields.
Want to use a simple interface to export your data? See our video on exporting data.
When using the API, it’s recommended to generate the export URL via the export your data interface. It has a simple UI where fields can be selected without any coding or technical knowledge.
Available fields in export
| Field | Type | Description |
|---|---|---|
| added_unix | number | The time of the page view in unix time format |
| added_iso | date | The time of the page view in ISO8601 format |
| hostname | string | The hostname of the website |
| hostname_original | string | When the hostname is overwritten, we store the original hostname |
| path | string | The path of the page view |
| query | string | The query parameters of the URL |
| is_unique | boolean | Is this page view unique |
| is_robot | boolean | Is page view visited by a robot or crawler |
| document_referrer | string | The JavaScript document.referrer of the page |
| utm_source | string | UTM source (specify via ref= or utm_source in your URL) |
| utm_medium | string | UTM medium (specify via utm_medium in your URL) |
| utm_campaign | string | UTM campaign (specify via utm_campaign in your URL) |
| utm_content | string | UTM content (specify via utm_content in your URL) |
| utm_term | string | UTM term (specify via utm_term in your URL) |
| scrolled_percentage | number | How far did a visitor scroll on the page (in steps of 5%) |
| duration_seconds | number | How many seconds did a visitor stay on this page (we stop the counter when a page is hidden) |
| viewport_width | number | Viewport width in pixels |
| viewport_height | number | Viewport height in pixels |
| screen_width | number | Screen width in pixels |
| screen_height | number | Screen height in pixels |
| user_agent | string | The navigator.userAgent of a browser (in case of a fake one we don’t store it. |
| device_type | string | Either desktop, mobile, tablet, or tv. |
| country_code | string | 2 letter country code |
| browser_name | string | Browser name |
| browser_version | string | Browser version (do note this is a string) |
| os_name | string | OS name |
| os_version | string | OS version (do note this is a string) |
| lang_region | string | The region part of navigator.language |
| lang_language | string | The language part of navigator.language |
| uuid | string | A UUID v4 of the page view (this is not always unique) |
| metadata.*** | N/A | Metadata are your own specified fields followed by a type (e.g. project_text) |
Data like scrolled_percentage and duration_seconds is not always added because it depends on the browser features of the visitor. Metadata is found in metadata.*** fields. They will only be exported when specified by key (e.g.: metadata.dark_mode_bool).
Deprecated fields
These fields are deprecated but we keep them for backward compatibility. It’s recommended to not use it for new projects.
| Field | Description |
|---|---|
| url | Please use hostname and path to get the full URL |
| referrer | We replaced this with document_referrer |
| referrer_raw | We replaced this with document_referrer |
| device_width_pixels | We replaced this with viewport_width |
| device_width | We replaced this with viewport_width |
| source | What is the source of this page view, mostly js from our JavaScript |
Authenticate
For this API features you’ll need to authenticate. See the authenticate page on how to authenticate.
In short: apply an Api-Key-header where the key starts with sa_api_key_... and a User-Id header starting with sa_user_id_....
Selecting fields
You can specify all fields you like to export. Add them as a comma seperated list (e.g.: &fields=added_iso,hostname,path).
Request example (for developers)
To test if your API key works correctly you can replace the example values of this cURL example with your own.
curl "https://simpleanalytics.com/api/export/datapoints?version=5&format=csv&hostname=simpleanalytics.com&start=2024-10-06&end=2024-11-05&robots=false&timezone=Europe%2FAmsterdam&fields=added_iso,path&type=pageviews" \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: text/csv'
If you choose to export in the CSV format, it will export something like this:
| added_iso | country_code | datapoint | device_type | path | session_id | utm_campaign | utm_content | utm_medium | utm_source |
|---|---|---|---|---|---|---|---|---|---|
| 2024-11-04T09:13:04.100Z | US | visit_homepage | desktop | / | 1e5aad53-c734-40ac-b060-426a70d1c104 | ads1 | duckduckgo | ||
| 2024-11-05T07:38:49.100Z | UK | visit_homepage | desktop | / | 7b03aa29-612d-4aa8-b147-72c13986c4ae | newsletter | |||
| 2024-11-05T07:42:49.200Z | UK | popup_show | desktop | / | 7b03aa29-612d-4aa8-b147-72c13986c4ae | ||||
| 2024-11-05T08:20:54.100Z | NL | visit_homepage | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 | ||||
| 2024-11-05T08:21:14.200Z | NL | popup_show | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 | ||||
| 2024-11-05T08:21:44.300Z | NL | popup_close | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 |
The above export in CSV format
added_iso,country_code,datapoint,device_type,path,session_id,utm_campaign,utm_content,utm_medium,utm_source
2024-11-04T09:13:04.100Z,US,visit_homepage,desktop,/,1e5aad53-c734-40ac-b060-426a70d1c104,ads1,,,duckduckgo
2024-11-05T07:38:49.100Z,UK,visit_homepage,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,newsletter,
2024-11-05T07:42:49.200Z,UK,popup_show,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,,
2024-11-05T08:20:54.100Z,NL,visit_homepage,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,google
2024-11-05T08:21:14.200Z,NL,popup_show,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
2024-11-05T08:21:44.300Z,NL,popup_close,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
Metadata fields
Because metadata fields are defined by the user, we don’t know the fields upfront. The export UI gives a good overview of all metadata fields available for a certain period. Use those fields in the export API.
Fields in the API and exporter have a type appended to them. You can see fields like metadata.fieldname_text, metadata.fieldname_date, metadata.fieldname_bool, or metadata.fieldname_int (where fieldname is a user-defined name). Some metadata fields can have both, for example, metadata.projectID_text and metadata.projectID_int. If a text looks like a number, we convert it to an integer and we keep the text version.
When you see something prefixed with metadata.sa_urlparam_, it’s a paramter from the allowed URL parameters feature.
Event counts
If you are only interested in how many certain events happened, you can use our Stats API. It has a simple request and response with event totals.
https://simpleanalytics.com/simpleanalytics.com.json?version=5&start=yesterday&end=today&timezone=Europe/Amsterdam&events=visit_pricing
See live example of output.
Performance
For us it does not matter how much data you export. We stream the data directly out of our database to your server or computer. No heavy load required.
To make the export size smaller only select the fields you need.
If you have any problems, drop us a line via our contact page.