Last modified November 22, 2014 by Gordon Glauser

Swrve Export API Guide

The Swrve Export APIs enable you to export data from the Swrve service. These APIs enable the export of KPI, item sales and event count data.
Never call the Export API from within your app. The Export API is hosted in the Swrve dashboard and not designed for high levels of traffic.

In addition to the app’s API key you must also provide a personal key to access the export APIs. For more information, see Where Do I Find My API Key and Personal Key?

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click the relevant tab based on your app configuration. For more information, see How Do I Configure the Swrve SDK for EU Data Storage?

KPI Export

The Swrve Export API enables you to export KPI data from the Swrve service. All of the KPI data that is displayed in Swrve is available through this REST API. The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call all of the API calls below with HTTP GET. All of the URLs share a common root: https://dashboard.swrve.com/api/1/exporter/kpi (or https://eu-dashboard.swrve.com/api/1/exporter/kpi for EU-configured apps). To get DAU data as JSON, the URL becomes https://dashboard.swrve.com/api/1/exporter/kpi/dau.json (https://eu-dashboard.swrve.com/api/1/exporter/kpi/dau.json), and to get DAU data as HTML, the URL becomes https://dashboard.swrve.com/api/1/exporter/kpi/dau.html (https://eu-dashboard.swrve.com/api/1/exporter/kpi/dau.html).

Common URL Parameters

The following parameters are used by all calls in the KPI Exporter API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The start date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. Only set the end date if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data. The granularities supported by each KPI are listed in the table below. The default granularity is denoted with an asterisk. The granularity 24hour_rolling is calculated over the proceeding 24 hours reported hourly. The granularity 30day_rolling is calculated over the preceding 30 days reported daily.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Extra Parameters

The following parameter is only required for some API calls. The documentation for each call below specifies if these extra parameters are required.

Parameter Presence Description
currency Optional The virtual currency of interest. If no currency is specified, data is fetched from all virtual currencies.

KPIs

Name API Supported Granularity
Default is marked with *
Extra parameters
DAU dau day*, 24hour_rolling
MAU mau 30day_rolling*
DAU / MAU dau_mau day*
New Users new_users hour, day*, 24hour_rolling, month, year
Daily Paying Users dpu day*, 24hour_rolling
Conversion conversion hour, day*, 24hour_rolling, month, year
Revenue dollar_revenue hour, day*, 24hour_rolling, month, year
Currency Spent currency_spent hour, day*, 24hour_rolling, month, year currency
Currency Spent / DAU currency_spent_dau day*, 24hour_rolling currency
Currency Purchased currency_purchased hour, day*, 24hour_rolling, month, year currency
Currency Purchased / DAU currency_purchased_dau day*, 24hour_rolling currency
Currency Given currency_given hour, day*, 24hour_rolling, month, year currency
Items Purchased items_purchased hour, day*, 24hour_rolling, month, year currency
Items Purchased / DAU items_purchased_dau day*, 24hour_rolling currency
Session Count session_count hour, day*, 24hour_rolling, month, year
Avg Session Length avg_session_length hour, day*, 24hour_rolling, month, year
Day N Retention day[N]_retention hour, day*, 24hour_rolling, month, year
ARPU Daily arpu_daily day*, 24hour_rolling
ARPPU Daily arppu_daily day*, 24hour_rolling
ARPU Monthly arpu_monthly 30day_rolling*
ARPPU Monthly arppu_monthly 30day_rolling*
Avg Playtime avg_playtime day*, 24hour_rolling
Day 1 Reengagement day1_reengagement hour, day*, 24hour_rolling, month, year
Day 3 Reengagement day3_reengagement hour, day*, 24hour_rolling, month, year
Day 7 Reengagement day7_reengagement hour, day*, 24hour_rolling, month, year

Examples

Get DAU for a specific time range:

US

EU

Get MAU for the last 60 days (30day_rolling granularity):

US

EU

Get Currency Spent for the coins currency in the TopPlayers segment:

US

EU

Get Avg Session Length in HTML format, transposed and without data labels:

US

EU

Get Day 1 Retention (or Day N Retention):

US

EU

Get Day7 Retention (or Day N Retention):

US

EU

Get Avg Playtime for last two days in 24hour_rolling granularity:

US

EU

Error Codes

If an error occurs while processing the request, you may receive one or more of the the following error codes and need to make sure your integration is equipped to handle error conditions.

Code Text Description
400 Invalid Parameter The request included an invalid parameter, based on the specification.
403 Invalid API Key Check that your API key is correct.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to send the request at a later time, if possible.

Event Export

The Swrve Export API enables you to export event count information from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call all of the API calls below with HTTP GET. All of the URLs share a common root: https://dashboard.swrve.com/api/1/exporter/event/ (https://eu-dashboard.swrve.com/api/1/exporter/event/)

Common URL Parameters

The following parameters are used by all calls in the Event Export API:

Parameter Presence Description
name Required The name of the event to be queried.
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The starting date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. Only set the end date if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data, set to day by default. Event export calls support month, day, and hour only.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Event Count

This API call gets the event count for a named event.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/count

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/count

Example

US

EU

Event List

This API call gets a list of the event names that have been received by Swrve from the event API. This API should be used to enumerate a list of all event names so that they can be passed to the event count API. This API call supports the JSON and HTML formats like all other calls in the export API. The following parameters are not required: history, start, stop, segment, and granularity.

The output is a list of event names (which match the names set in the incoming event API requests), where event API could be a link to the event API.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/list

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/list

Example

US

EU

Payload Count

This API call gets the event payload counts for a named event and payload/key pair. This method enables you to export the data buckets that are displayed on the Events Overview screen.

The only granularity supported by this function is day.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/payload

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/payload

Example

US

EU

Payload Key List

This API call gets a list of the event payload key names that have been received by Swrve from the event API. Use this API to enumerate a list of all event payload key names so that they can be passed to the payload count API. This API supports the JSON and HTML formats like all other calls in the export API. The following parameters are not needed: history, start, stop, segment, and granularity.

The return value is a list of string names that correspond to the payload_key parameter of named events sent to Swrve using the event API.

URL

US

https://dashboard.swrve.com/api/1/exporter/event/payloads

EU

https://eu-dashboard.swrve.com/api/1/exporter/event/payloads

Example

US

EU

Error Codes

See KPI Export.


User Cohorts Export

This API call gets the specified cohort_type data for daily cohorts for the days specified. A user cohort represents a section of users who start using the app on a particular day. You can view data for those users for the 30 days after they joined and compare this to other users starting on other days. You can get the following information for any cohort:

  • Retention – the number of retained users.
  • Avg Sessions – the average number of sessions started per retained user.
  • Avg Playtime – the average session length per retained user.
  • Avg Revenue – the average revenue generated per retained user.
  • Total Revenue – the total revenue generated.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API call below with HTTP GET. The URL has the root: https://dashboard.swrve.com/api/1/exporter/cohorts/daily (https://eu-dashboard.swrve.com/api/1/exporter/cohorts/daily).

Common URL Parameters

The following parameters are used by all calls in the User Cohorts Export API:

Parameter Presence Description
cohort_type Required The type of cohort data to be returned. Must be one of retention, avg_sessions, avg_playtime, avg_revenue and total_revenue.
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
start optional The starting day of the date range from which data is fetched in the format: yyyy-mm-dd. If no start date is specified, the last 30 days are fetched.
stop Optional (required if start is specified) The end date of the date range from which data is fetched in the format: yyyy-mm-dd.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all players is fetched by default.

Example

US

EU

Error Codes

See KPI Export.


Item Sales Export

The Swrve Export API enables you to export item sales data from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API calls below with HTTP GET. All of the URLs will share a common root: https://dashboard.swrve.com/api/1/exporter/item/ (https://eu-dashboard.swrve.com/api/1/exporter/item/).

Common URL Parameters

The following parameters are used by all calls in the Item Sales Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
history Required (if start is not used) This parameter is used in conjunction with the specified granularity to fetch the N last data points starting from the current date. For example, if history is set to 8 and the hour granularity is specified, then the data points of the last 8 hours are fetched.
start Required (if history is not used) The starting date of the date range from which data is fetched. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app.
stop Optional The end date of the date range from which data is fetched. The end date should only be set if a start date is specified. The following date formats are supported: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-dd-hh. All dates use the local timezone of the app. If no end date is specified, the current time is used by default.
segment Optional The segment from which data is to be fetched. If no segment is specified, data from all users is fetched by default.
granularity Optional The temporal granularity of the fetched data, set to day by default. Item sales export calls support year, month, and day only.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Extra Parameters

The following parameters are only required for some API calls. The documentation for each call below specifies whether these extra parameters are required.

Parameter Presence Description
uid Optional The UID of the item that you want to fetch data from. If no UID or tag is specified, all items are returned.
tag Optional The tag of the items that you want to fetch data from. If no UID or tag is specified, all items are returned.
currency Optional The virtual currency of interest. If no currency is specified, data is fetched from all virtual currencies.

Item Sales

This API call gets the sales data of a particular item.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/sales

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/sales

Extra Parameters

uid, tag, currency

Example

US

EU

Item Revenue

This API call gets the revenue data of a particular item.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/revenue

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/revenue

Extra Parameters

uid, tag, currency

Example

US

EU

Item Tag

This API call gets the UIDs of all items that are associated with a particular tag.

URL

US

https://dashboard.swrve.com/api/1/exporter/item/tag

EU

https://eu-dashboard.swrve.com/api/1/exporter/item/tag

Extra Parameters

tag

Example

US

EU

Error Codes

See KPI Export.


Segment Export

The Swrve Export API enables you to export segment information from the Swrve service.

The data is available in JSON and HTML format. The HTML data produces a table, which is especially useful for performing Excel web queries or for import into Google Spreadsheets. To request JSON data, add .json to the end of the URL. To request HTML data, add .html.

Call the API call below with HTTP GET. The URL has the root: https://dashboard.swrve.com/api/1/exporter/segment/ (https://eu-dashboard.swrve.com/api/1/exporter/segment/).

Common URL Parameters

The following parameters are used by all calls in the Segment Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.
transpose Optional This parameter is only relevant for the .html version of this call. If set to true, the columns and rows of the generated table are switched. This parameter is set to false by default.
only_data Optional This parameter is only relevant for the .html version of this call. If set to true, the row and column headers of the generated table are removed. This parameter is set to false by default.

Segment List

This API call gets a list of the segment names that have been created for this app. This API supports the JSON and HTML formats like all other calls in the export API. The return value is a list of string names that correspond to the name parameter of segments created for this app.

URL

US

https://dashboard.swrve.com/api/1/exporter/segment/list

EU

https://eu-dashboard.swrve.com/api/1/exporter/segment/list

Example

US

EU

Error Codes

See KPI Export.


User DB Export

The User DB Downloads screen enables you to download data sets reflecting different properties of your users. For apps with a large number of users, these data sets are further split into multiple files. The export API for user DB downloads provides a list of all the available data and schema files, enabling you to automate the download of the data sets in which you are interested. For more information about the User DB Downloads screen, see Manually Downloading User DBs.

Call this API call with HTTP GET. The URL has the root: https://dashboard.swrve.com/api/1/userdbs.json (https://eu-dashboard.swrve.com/api/1/userdbs.json).

Common URL Parameters

The following parameters are used by all calls in the User DB Export API:

Parameter Presence Description
api_key Required The API key for the given app.
personal_key Required The personal key for your user login.

File List

This API call returns a JSON object that lists the URLs of the various data and schema files for the different data sets. This JSON takes the following format:

where:

  • DATA_URL_* is the URL of a Gzipped CSV data file.
  • SCHEMA_URL is the URL of an SQL definition file.
  • DATE is the date of the latest update.

For example, to download the custom events fired for all users, loop through the data URLs referred to in this JSON contained list:

You must append your app ID, personal key and API key to the URL of each file request. For example:

US

EU

URL

US

https://dashboard.swrve.com/api/1/userdbs.json

EU

https://eu-dashboard.swrve.com/api/1/userdbs.json

Example

US

EU

Error Codes

See KPI Export.