Export API edit

Download PDF

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=2022-10-25&end=2022-11-24&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
2022-11-23T17:55:22.100Z US visit_homepage desktop / 1e5aad53-c734-40ac-b060-426a70d1c104 ads1     duckduckgo
2022-11-24T16:21:07.100Z UK visit_homepage desktop / 7b03aa29-612d-4aa8-b147-72c13986c4ae     newsletter  
2022-11-24T16:25:07.200Z UK popup_show desktop / 7b03aa29-612d-4aa8-b147-72c13986c4ae        
2022-11-24T17:03:12.100Z NL visit_homepage desktop / 928e4f2f-1f16-4900-9ad8-0a1965e689a3       google
2022-11-24T17:03:32.200Z NL popup_show desktop / 928e4f2f-1f16-4900-9ad8-0a1965e689a3        
2022-11-24T17:04:02.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
2022-11-23T17:55:22.100Z,US,visit_homepage,desktop,/,1e5aad53-c734-40ac-b060-426a70d1c104,ads1,,,duckduckgo
2022-11-24T16:21:07.100Z,UK,visit_homepage,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,newsletter,
2022-11-24T16:25:07.200Z,UK,popup_show,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,,
2022-11-24T17:03:12.100Z,NL,visit_homepage,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,google
2022-11-24T17:03:32.200Z,NL,popup_show,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
2022-11-24T17:04:02.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.