With Showpad’s Reports API, you're able to generate and download everything you see in the Reports section of Showpad's Online Platform. When was an asset viewed, how long is it viewed for? Who shared which asset and with whom? Who participates in a Shared Space?
Showpad’s Reports API will let you download the raw data as a CSV or a JSON file, so you can use it in your own BI solution, combine it with other data sources in your organization, and run custom analysis on it. The Reports API also respects the anonymization of usernames and IDs. You can still join tables to analyze the data.
Note: There can be a difference between the data returned by the API export and the Reports in Showpad's Online Platform.
The CSV returned by the API is more granular and gives you all the raw data. The tabulated data in our Online Platform for the View Totals and Top Content can diverge from the raw API data export. This is explained in detail below.
See how it's structured
Use the Events endpoint to return the sharing data you need to relate with other Export endpoints. More detailed information on all tables and fields underneath.
- Download granular data in CSV and JSON format
- Import the data in your custom tools once it's exported
- Customize the maximum limit of returned responses
- Only GET is possible to receive analytics data
- If activated, we respect anonymization of the usernames and IDs in the results
You need this to succeed
- Showpad's Ultimate pricing plan
- Access to Showpad's Online Platform
- Showpad's API Explorer, REST Clients, and command lines are no mystery to you
Working with the exported data
- Only the events export can be filtered by date, all other exports will return all data there is.
- To export the data in CSV format, change the JSON extension with CSV in your curl command. This will return a CSV file you can use in your custom tools.
- For Experience Apps, we don't track any events except channel-used; The app developers can implement tracking themselves to store in the event table. These events will have event_type experience_tracked_event
Control returned items with the X-Showpad-Scroll-Id header
- By default, the maximum number of returned items in the Events API endpoint is set to 500. You can change the limit and set a range between 50 and 1000 responses.
The response will come with a header called X-Showpad-Scroll-Id that contains a token. If you make the same request again but set this header on your request, you will get the second batch of events. You get back another X-Showpad-Scroll-Id that you can use to fetch the third batch of events etc.
This way, you can do a loop in the application until they fetched all events they want. When no events return in the response, this indicates the end. There are millions of events in the database and it's not possible to return everything in one go, therefore you can scroll until you have all events you need.
- The results of the Events API export are limited and you'll need to use the X-Showpad-Scroll-Id header to continue receiving data.
- The X-Showpad-Scroll-Id header is not changed with every call/response. It remains valid for x-amount of time, so always use the X-Showpad-scroll-id header from the response for the next request.
The header gives the API a reference to who is making the call and will return the next batch of reports. It's comparable with an authentication key.
Important facts about the received event data
When comparing export data with reports in the Online Platform, it's possible that the numbers differ for several reasons:
- When examining Asset View data, it's possible that the numbers in the Reports section of our Online Platform and those from the API export are different.
In the Online Platform Top Content report, shares are tabulated as the number of times a piece of content is shared with someone. A document shared with 2 people at the same time will count as 2 shares. If you check the Top Content report, it will say, for example, 100 shares. This shows which users in the app shared content. That 100 stands for 100 different users. In the API export, it will show the granular data, so if added correctly, you get the same numbers.
- You can export details per page. In case page-level details are exported you need to be careful when summing the view events on an asset per user as there is one event for every page and one event for the whole document. For asset analytics, you can obtain the same result as the OP by executing the filter where page = NULL.
- Users, user groups, assets, etc can be deleted. OP reporting will exclude all events related to users that are deleted and/or inactive. You can obtain identical results by also filtering out these users or groups based on the deletedAt field in the relevant tables.
- For date filtering, use the start date of the events.
- Divisions: Assets belong to a library (which is a division). Instances can have one or more divisions; Personal files of users are also a division, only accessible by the users. There is a division field on events for certain use cases but it is safest to join divisions with asset tables and not with event tables.
- Showpad apps also track events when offline, and send data to the server when back online. These events have the original timestamp as event timestamp. There is, however, a loggedAt timestamp to detect when the data was received at the server. So, there is a possibility you get different results for the same date/time, if you execute queries on the API on different moments; We call these late-arriving events.
Note: See an overview of the Event Types in this article.