Reporting API
Introduction
This page describes the LoopMe Reporting API. The LoopMe Reporting API allows 3rd party servers to retrieve app&site and campaign statistics of LoopMe user accounts via REST APIs. The following sections describe the various aspects of the API and steps involved with a successful integration.
If you have questions please contact us at support@loopmemedia.com.
Getting Started
Authentication
An API Authentication token is required for all Reporting API requests. The token is a 16-character string generated by LoopMe.
The API Authentication token should be used as get parameter api_auth_token, and is verified by the system on each request.
Retrieving the API Authentication token
Reporting API access needs to be enabled by the user. While enabling Reporting API access, an unique API Authentication token is provided for his account.
To enable Reporting API access:
API Versioning
The API version should be provided in every API request. The API version is a part of the request URL.
The example URL below contains version number v1:
```
https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7
```API Formats and Naming Conventions
The Publisher APIs conform to the REST specifications. JSON is the only format supported.
Naming conventions for elements throughout the API will appear in snake-case. For example, api_auth_token.
API Base URLs
The reporting API for advertisers or publishers use different base URLs.
Publisher Reporting API URL
Example base URL for publisher reporting API:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7&app_key=12345abcde
```Advertiser Reporting API URL
Example base URL for advertising reporting API:
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=days7&campaign_id=1
```Data Formats
The following sections explain the formats used to enter data.
Date and Time
Any reference to dates and times in the API request and response is defined in the following format: YYYY-MM-DD and hh:mm:ss.
NOTE: All times are returned in UTC. The API developer should adjust the time as required.
Depending on the date_range and granularity, the dates are represented in the format as shown in the table below. For example, if the date_range in the request contains today’s date, the response contains data grouped by hour in the format YYYY-MM-DD hh:mm:ss.
| Date Range | date_range value | Supported granularities | Default granularity | Response Date Format |
|---|---|---|---|---|
| Today | today | hour | hour | YYYY-MM-DD hh:mm:ss |
| Yesterday | yesterday | hour | hour | YYYY-MM-DD hh:mm:ss |
| Last 7 days | days7 | day | day | YYYY-MM-DD |
| Last 30 days | days30 | day, week | week | YYYY-MM-DD |
| Last 90 days | days90 | day, week, month | month | YYYY-MM-DD |
| Custom | In from_date:to_date format.Dates should match the pattern YYYY-MM-DD | Depends on date_range | Depends on date_range | YYYY-MM-DD hh:mm:ss |
For custom date ranges:
| Date Range | Granularity |
|---|---|
| < 2 days | hour |
| 2 - 14 days | day |
| 2 weeks - 2 months | week |
| > 2 months | month |
Currency
The only currency supported in the system is the United States Dollars. Any reference to currency is represented as a string containing decimal values. No location specific formatting is applied to the decimal values. For example, 1554.67.
Using API Parameters
Generic Parameters
Date Range
The date_range parameter defines the date range for which the report is requested. Date range parameter supports these predefined values: today, yesterday, days7, days30, days90. date_range in custom format should match the pattern from_date:to_date (YYYY-MM-DD:YYYY-MM-DD)
The date_range is mandatory.
Example with predefined date range:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7
```Example with custom date range:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=2013-09-01:2013-09-02
```Granularity
There are 4 values supported for granularity: hour, day, week, month.
The granularity parameter is not mandatory. If it is not specified default parameter will be used. If granularity is not supported for a particular date_range it will be adjusted.
Example:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days30&granularity=day
```Country Code
The country_code parameter is used to filter data for specified country in the format in three-letter format (ISO 3166-1 alpha-3). For example GBR for United Kingdom.
The country_code parameter is not mandatory. If it is not specified this filter won't be applied. This means sum data for all countries will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7&country_code=USA
```Platform
The platform parameter is used to filter publisher's app/sites by platform. There are 3 values supported: ios, android, website.
The platform parameter is not mandatory. If it is not specified this filter won't be applied. As a result sum data for all platforms will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7&platform=ios
```Grouping
The group_by parameter is used to group results by several parameters like date, country, app, campaign and creative. The group_by parameter is not mandatory. If it is not specified date will be used by default. Multiple group_by dimensions can selected by added them comma separated.
Supported values for publishers: date, country, app, os, ad_format_name, bundle_id,Format. Supported values for advertisers: date, country, campaign, line_item, creative, os, ad_format_name, bundle_id.
Example for publishers:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7&group_by=date,country,app,os,ad_format_name,bundle_id
```Example for advertisers:
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=yesterday&group_by=date,country,campaign,line_item,creative,os,ad_format_name,bundle_id
```Publisher Parameters
App Key
The app_key is a unique key for the publisher's application or website. It is used to get data for specified app/site.
The app_key is not mandatory. If app_key is not specified sum data for all publisher's applications will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=days7&app_key=12345abcde
```Advertiser Parameters
An advertisement campaign booked via the LoopMe dashboard is split in three hierarchical levels:
Campaign Id
The campaign_id is needed to retrieve advertiser statistics for specific campaigns. Parameter accepts integer value.
The campaign_id parameter is not mandatory. If it is not specified this filter won't be applied and as a result the data for all campaigns will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=days7&campaign_id=1
```Line Item Id
The line_item_id is needed to retrieve advertiser statistics for specific line items for a campaign. Parameter accepts integer value.
The line_item_id parameter is not mandatory. If it is not specified this filter won't be applied, the data for all line items will be retrieved. If a campaign_id is specified, the data for all the line items for the campaign will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=days7&campaign_id=1&line_item_id=1
```Creative Id
The creative_id is needed to show advertiser's report for specific creative. Parameter accepts integer value.
The creative_id parameter is not mandatory. If it is not specified this filter won't be applied, the data for creatives will be retrieved. If a line_item_id is specified, the data for all the creatives for the line item will be retrieved.
Example:
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=days7&campaign_id=1&line_item_id=1&creative_id=1
```Examples
Valid Publisher Reporting API Request
Notes:
Request
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=2013-09-01:2013-09-02
```Response
{
"granularity": "day",
"series": [
{
"date": "2013-09-01 00:00:00 UTC",
"totals": {
"CTR, %": "0",
"Clicks": "0",
"Earnings, $": "0",
"Fill Rate, %": "0",
"Requests": "0",
"Views": "0",
"eCPM, $": "0"
}
},
{
"date": "2013-09-02 00:00:00 UTC",
"totals": {
"CTR, %": "0",
"Clicks": "0",
"Earnings, $": "0",
"Fill Rate, %": "0",
"Requests": "0",
"Views": "0",
"eCPM, $": "0"
}
}
]
}Valid Advertiser Reporting API Request
Notes:
Request
```
get https://reports.loopme.com/api/v1/reports/campaigns?api_auth_token=1234567890abcdef&date_range=2013-09-01:2013-09-02&campaign_id=1'
```Response
{
"granularity": "day",
"series": [
{
"date": "2013-08-01 02:00:00 +0200",
"totals": {
"CONV": "0",
"CTR, %": "3.85",
"CV, %": "0",
"Clicks": "1",
"Dislikes": "0",
"Likes": "0",
"OptOut": "0",
"Shares": "0",
"Social Refs": "0",
"Spend, $": "1.00",
"Views": "26",
"eCPA, $": "0",
"eCPC, $": "1.00",
"eCPM, $": "38.46"
}
},
{
"date": "2013-08-02 00:00:00 UTC",
"totals": {
"CONV": "0",
"CTR, %": "0",
"CV, %": "0",
"Clicks": "0",
"Dislikes": "0",
"Likes": "0",
"OptOut": "0",
"Shares": "0",
"Social Refs": "0",
"Spend, $": "0",
"Views": "0",
"eCPA, $": "0",
"eCPC, $": "0",
"eCPM, $": "0"
}
}
]
}Invalid API Request and Error Responses
Description: Any error encountered while processing an API request will cause a failure of the entire operation. The API caller has to take the responsibility of parsing the content of the response to handle errors.
Request
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=1234567890abcdef&date_range=wrond_date_range
```Response
{
"errors": {
"2002": "Date range is in wrong format. Use predefined values or custom date range format."
}
}Invalid API Request with many wrong parameters
Request
```
get https://reports.loopme.com/api/v1/reports/apps?api_auth_token=4ee8933c98f4820c&date_range=wrong_date_range&country_code=WRONG
```Response
{
"errors": {
"2002": "Date range is in wrong format. Use one of the predefined values or custom date range format.",
"5001": "Country code is wrong. Three-letter code should be used."
}
}Error Codes
A list of error codes and their descriptions are given in the table below.
| Error Codes | Description |
|---|---|
| 1001 | Missing or invalid api_auth_token. |
| 2001 | Date range is not specified. |
| 2002 | Date range is in wrong format. Use one of the predefined values (today, yesterday, days7, days30, days90) or custom date range format. |
| 2003 | Custom date range should match the pattern from_date:to_date (YYYY-MM-DD:YYYY-MM-DD). |
| 3001 | Granularity is in wrong format. Supported values: hour, day, week, month. |
| 4001 | App is not found. Might be wrong app_key. |
| 4002 | Campaign is not found. Might be wrong campaign_id. |
| 4003 | LineItem is not found. Might be wrong line_item_id. |
| 4004 | Creative is not found. Might be wrong creative_id. |
| 5001 | Country code is wrong. Three-letter code should be used. |
| 6001 | Platform is wrong. Supported values: ios, android and website. |
| 7001 | Group_by field is in wrong format. Supported values: date, country and app for application reports. And date, country, campaign and creative for campaign reports.' |
Zero Responses
If some of the parameters are mutually exclusive this will result an empty report.
For example: Publisher has apps for ios and android. For iOS in USA only. For Android in UK only. If he requests a report with country_code=GBR and platform=ios system will generate a report with all 0-s.