Export events API

Download PDF

If you want to export raw events you can do so via our CSV export. You can define a date range and it pull out the data via streaming (very fast).

Want to use a simple interface to export your data? See our video on how to export data.

For this API features you’ll need to authenticate. You can do this with an Api-Key-header where the key starts with sa_api_key_... and with a User-Id header starting with sa_user_id_.... You can create them in your account settings.

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_homepage

See live example of output.

Export raw events

To export your events you can use this URL format:

https://simpleanalytics.com/api/export/datapoints?version=5&format=csv&hostname=simpleanalytics.com&start=2022-09-05&end=2022-10-05&robots=false&timezone=Europe%2FAmsterdam&fields=added_iso,country_code,datapoint,device_type,path,query,query_and_path,session_id,utm_source,utm_campaign,utm_content,utm_medium&type=events

The fields parameter can contain all fields listed here: added_iso,country_code,datapoint,device_type,path,query,query_and_path,session_id,utm_source,utm_campaign,utm_content,utm_medium and the ones you find in our UI. You can use our UI to generate the URL for you. See API helpers on how this works.

To test if your request is correct, 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-09-05&end=2022-10-05&robots=false&timezone=Europe%2FAmsterdam&fields=&type=events" \
     -H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
     -H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     -H 'Content-Type: text/csv'

It will export something like this (in CSV format):

added_iso	country_code	datapoint	device_type	path	session_id	utm_campaign	utm_medium	utm_source
2022-10-04T10:19:52.100Z	US	visit_homepage	desktop	/	1e5aad53-c734-40ac-b060-426a70d1c104	ads1		duckduckgo
2022-10-05T08:45:37.100Z	UK	visit_homepage	desktop	/	7b03aa29-612d-4aa8-b147-72c13986c4ae		newsletter
2022-10-05T08:49:37.200Z	UK	popup_show	desktop	/	7b03aa29-612d-4aa8-b147-72c13986c4ae
2022-10-05T09:27:42.100Z	NL	visit_homepage	desktop	/	928e4f2f-1f16-4900-9ad8-0a1965e689a3			google
2022-10-05T09:28:02.200Z	NL	popup_show	desktop	/	928e4f2f-1f16-4900-9ad8-0a1965e689a3
2022-10-05T09:28:32.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-10-04T10:19:52.100Z,US,visit_homepage,desktop,/,1e5aad53-c734-40ac-b060-426a70d1c104,ads1,,,duckduckgo
2022-10-05T08:45:37.100Z,UK,visit_homepage,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,newsletter,
2022-10-05T08:49:37.200Z,UK,popup_show,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,,
2022-10-05T09:27:42.100Z,NL,visit_homepage,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,google
2022-10-05T09:28:02.200Z,NL,popup_show,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
2022-10-05T09:28:32.300Z,NL,popup_close,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,

Legacy events endpoint

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/events?hostname=example.com&start=2022-09-05&end=2022-10-05" \
     -H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
     -H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     -H 'Content-Type: text/csv'

Unlike the visits export you can’t specify a time zone with the events export. Because of privacy reasons we store events with only a date (YYYY-MM-DD) in the UTC time zone. The time zone will always be UTC and can’t be changed.

The export will look like this:

date,events,referrer
2022-10-05,visit_homepage.open_signup_modal,duckduckgo.com
2022-10-04,visit_homepage
2022-10-03,visit_homepage.open_signup_modal,twitter.com

Do note that the events are exported per session. If two events happen in the same session (the same page or the session in a single page application) they are stored in one row. This way you can calculate conversions between events. We separate them with a dot (e.g.: visit_homepage.open_signup_modal).

For privacy reasons we hide events when they only happen once per day. To get all events in your export, ask us to whitelist your events. We manually make sure personal identifiers in events are excluded.

If you have any problems, drop us a line via our contact page.