Remerge is an app retargeting platform. In addition to our dashboard and analytical capabilities, clients can pull JSON-based reports from the Remerge Reporting API for their active campaigns to their internal BI on the basis of daily granularity.
General
Please note:
- The Remerge Reporting API can ONLY be accessed via the Terminal (or by an API client) as follows:
- Terminal - This option requires employing a data transfer tool, Curl, as per the Sign-In Request (credentials should be provided to you by your Remerge Account Manager) and Post Request examples found below.
- API - Clients may employ their internal API and data transfer tools.
- The Reporting API is NOT accessible from a web browser.
- Remerge stores your data for a limited time frame of six months ONLY. Therefore, to mitigate a potential scenario in which you wish to obtain data older than the said time frame, we encourage you to maintain your own data log.
Dimensions
A client's performance is broken down into six dimensions: Timestamp, Country, App, Campaign, Campaign Type, and Related Ads. Therefore, the results can be easily imported, split into smaller parts, and distributed according to the provided dimensions to any Business Intelligence platform chosen by the client. Please refer to the Index section below for further information on specific parameters and fields.
Endpoint
The API is accessible via the following endpoint:
https://api.remerge.io/reportRequest & Response
Request Parameters
Remerge Reporting API provides a simple interface to query data. A start and end date are the only parameters required.
Please note: To obtain yesterday's data, you must ensure to select today's date as your end_date (e.g., to receive 2021-12-08's data, set 2021-12-08 as your start_date and 2021-12-09 as your end_date).
| Name | Content | Examples | Mandatory |
|---|---|---|---|
| *start_date | Report start date (YYYY-MM-DD) | 2021-12-08 | x |
| *end_date | Report end date (YYYY-MM-DD) | 2021-12-09 | x |
| dimensions |
A comma-separated list of dimensions to split the aggregates by default to an audience, country, campaign,campaign_type, and ad if not passed. Possible dimensions: audience, country, campaign, campaign_type, ad, ad_label, or platform. |
country, platform | |
| filter |
It is possible to filter the request per campaign type, e.g. https://api.remerge.io/report?start_date=2022-01-01&end_date=2022-01-02&campaign_type=retargeting |
retargeting |
A valid request would look as follows: https://api.remerge.io/report?start_date=2017-01-10&end_date=2017-01-11&dimensions=campaign,ad
Note:
- We recommend that you utilize a text editing program (such as Sublime or Atom) to ensure that all of the symbols in your query are transferred to the terminal correctly.
- Unless you limit the dimensions in your request URL, the response will generate all potential dimensions.
Authorization
Example
Sign-in Request
curl -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST
-d '{"user" : { "email" : "your@email.com", "password": "password"}}' https://api.remerge.io/users/sign_in
Returning the needed token as JSON
{"email":"your@email.com","token":"J-QeJxyza7JH19QUDb4","user_id":1234,"user_name":"Peter Example","user_token":"J-QeJ49Yasdf219QUDb4"}
Mandatory Request Headers for a Valid Reporting Request
| Name | Content | Example | Mandatory |
|---|---|---|---|
| Request Header | Content-Type | 'Content-Type: application/json' | x |
| Request Header | Acceptance | 'Accept: application/json' | x |
| Request Header | Authorization Token | 'Authorization: Token user_token="HJn4OYViZv", email="example@mydomain.com"' | x |
| Request Type | POST | POST | x |
Example Request
Below is an example of a POST request to the Remerge Reporting API using the data transfer tool curl:
curl -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Token user_token="xxXxxXXXXXXx-xXxxXXX", email="example@mydomain.com"' -X POST "https://api.remerge.io/report?start_date=2022-01-01&end_date=2022-01-02&dimensions=audience%2Ccountry%2Ccampaign%2Cad%2Cad_label%2Cplatform"
Response Fields
The response returns a JSON object containing a results array and an element count. Each array element consists of the following fields:
| Name | Content | Example | |
|---|---|---|---|
| timestamp | UTC Timestamp | 2017-01-11T00:00:00.000Z | |
| event.platform | Platform (iOS /Android) | ios | |
| event.country | RTB Geo-Information | de | |
| event.campaign | Internal Remerge Campaign ID | 42 | |
| event.campaign_name | External Remerge Campaign Name | Test Campaign | |
| event.campaign_type | Campaign Type | Install/Impact/Retargeting | |
| **event.cost_currency | Internal Remerge Campaign Currency | EUR | |
| ***event.audience | App Store Reference | 12345678 | |
| event.ad_id | Creative ID | 1406561 | |
| event.ad_name | The unsanitized file name of the image/video asset | banner_300_50.png | |
| event.ad_label_id | Creative Label ID | 18304 | |
| event.ad_label_name | Creative Label Name | non_purchasers_it | |
| ****event.ad_creative_url | Creative URL | https://assets.remerge.io/ad_assets/files/000/006/696/original/banner_300_50.png?1478088208 | |
| event.impressions | Daily Impression Counter on App.Country.Campaign.Ad Level | 2 | |
| event.clicks | Daily Click Counter on App.Country.Campaign.Ad Level | 1 | |
| event.app_open_rate | Counted App-Opens for Clicks in percent | 83.57 | |
| event.cost | Cost in Customer Currency on App.Country.Campaign.Ad Level | 0.12 | |
| event.conversions | Daily Target Conversion Event Counter on App.Country.Campaign.Ad Level | 1 | |
| event.ap_conversions | Daily Attributed Target Conversion Event Counter on App.Country.Campaign.Ad Level | 5 | |
| event.unique_user | Daily Unique User Counter on App.Country.Campaign.Ad Level | 2 |
Example JSON Response (two display options of the same query)
Option 1:
Option 2:
In case of no existing data for the given interval, the request returns an empty results array and counts: 0
List of Potential Errors
| Status | Message | Explanation |
|---|---|---|
| 200 | OK | Query results returned as JSON |
| 401 | Unauthorized | The provided Authorization token was invalid |
| 422 | start_date: Format YYYY-MM-DD required | Start Date ill-formed |
| 422 | end_date: Format YYYY-MM-DD required | End Date ill-formed |
| 422 | start_date: must be a valid date | No real date provided, e.g., 2015-33-09 |
| 422 | end_date: must be a valid date | No real date provided, e.g., 2015-33-09 |
| 422 | end_date: end date must be greater or equal to the start date | The end date is earlier than the start date |
| 422 | queryID: queryId already exists | The user has already sent a request which is still processed by the API, i.e., the query rate limit per user is 1. |
| 504 | Gateway Timeout | The request took too long for the webserver to process. This error typically occurs due to too broad of a query interval. In this case, please try again with a shorter interval, of 14 days, at the most. |
Index
* API Timestamp - The start_date and end_date are, by default, set to 00:00 midnight of that day. This means that if, for instance, you would like to query exactly one day, use that day as start_date and the next day as end_date. Make sure to request one day of data at a time ONLY (e.g., each day, request yesterday's data and store it in your internal database).
** Ensure to split your report by campaign upon employing different currencies for different campaigns.
*** Remerge uses the term Audience as a reference to your entire application (unlike in some contexts, where an audience refers to a segment). Upon pulling a report, Remerge Reporting API will give back a field called Audience. This means that the said report contains static data for your entire app.
**** In the case of Dynamic Ads, the creative URL displayed is only a placeholder as the actual creative URLs are dynamically taken from the feed. Unfortunately, they cannot be displayed in this reporting.