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:

• Login to the LoopMe dashboard
• Go to the Account/Settings section
• Go to the "Reporting API Settings
• Choose to enable the Reporting API
• Provide the API Authentication token to the party who wants to retrieve your application data.

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.

For custom date ranges:

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:

1. Campaign: Campaign level is the high aggregation level and typically resembles a complete Insertion Order.
2. Line Item: Each campaign may contain one or multiple line items. Line items allow advertiser to target specific parts of the overall IO budget to for example certain countries.
3. Creative: Each line item may contain one or multiple creatives. Different creatives may be used to display for difference ad placement sizes e.g. a banner creative or a fullscreen creative.

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:

• A valid auth_token is required to authenticate any API request.
• The request is a GET request.

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:

• A valid auth_token is required to authenticate any API request.
• The request is a GET request.

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.

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.