Table of Contents

Getting Started

Authentication

API Structure

Endpoints

Throttling

Getting Started

Ask your Liftoff contact for your publisher API key and password.

Integrate Liftoff’s Ad SDK and confirm it’s working in production following LifotffAds’ SDK integration instructions. Once your app is successfully calling Liftoff ads in production, create a test report following the instructions below.

Reporting API Setup

Create a report request with a ?test=true parameter. This prevents you from running into rate limiting issues.

curl --header "Content-Type: application/json" \
--request POST \
--data
'{
"start_time":"2020-10-01T00:00:00Z","end_time":"2020-11-01T00:00:00Z"}' \
--
user 'username' https://data.liftoff.io/api/publishers/v1/reports?test=true

Check that your request passes without errors.

{"message":"Validation passed without errors."}

After you generate the report without the test parameter, the report response should contain a report id.

{
   "id":
"abc123",
   "created_at":
"2020-11-15T00:00:00Z",
   "state":
"queued",
   "parameters": {
       "start_time":
"2020-10-01T00:00:00Z",
       "end_time":
"2020-11-01T00:00:00Z"
   }
}

You can obtain the report using the following command.

curl --user 'username' 'https://data.liftoff.io/api/publishers/v1/reports/abc123/data'

Authentication

Liftoff’s reporting API supports HTTP basic authentication.

Sample Curl

curl --request GET \
--url
'https://data.liftoff.io/api/publishers/v1/reports' \
--user
'username:password'

API Structure

Base URL

All API URLs start with “https://data.liftoff.io/api/publishers/v1”. Different endpoints can be called by appending to the base url. All available end points are described in the table below:

Endpoints

HTTP Request Method

Usage Description

/reports

GET

Look up metadata around recently submitted reports

/reports

POST

Generate a report

/reports/<id>/status

GET

Get the status of the report

/reports/<id>/data

GET

Download the report in CSV or JSON

/<entity_type>

Entity type = apps, ad_units

GET

Get information around particular entities (e.g. apps, ad units)

Endpoints

/reports

GET

This endpoint allows you to look up metadata of recent reports.

Response:

Name

Type

Description

id

string

ID of the report

created_at

Timestamp (string)

UTC timestamp

parameters

Report parameters

The JSON body that was provided during the initial POST request

state

String

Queued, cancelled, completed, failed

Sample curl

curl --user 'username' 'https://data.liftoff.io/api/publishers/v1/reports'

Sample response body

[
   {
       
"id": "abc123",
       
"created_at": "2020-11-15T00:00:00Z,
       
"state": "completed",
       
"parameters": {
           
"app_ids": ["xy123","yz456"],
           
"start_time": "2020-10-01T00:00:00Z",
           
"end_time": "2020-11-01T00:00:00Z"
       }
   },
   ...
]

POST

Content Type: application/json

Request body:

Name

Type

Description

When value not specified

app_ids

Array of strings

Filters to only the app external_ids provided

IDs of all publisher apps belonging to the account

start_time

Timestamp

UTC

400 bad request, required field

end_time

Timestamp

UTC

400 bad request, required field

group_by

Array of string combinations

Liftoff supports group bys for any combination of the following fields:

  • app_id
  • ad_size
  • country
  • ad_unit_id
  • Is_rewarded

Note: grouping by app_id also implicitly includes “app_name” and “platform” to your report

app_id

format

String

Either CSV or JSON

CSV

callback_url

String

A URL that will be contacted with a GET request once the report is ready.

Null

timezone

String

Specify a TZ database name to use for date groupings

UTC

remove_zero_rows

Boolean

When enabled, all rows whose numeric metrics are equal to 0 will be excluded from output

true

Sample request body

{
   "
app_ids": ["xy123","jkl456"],
   "group_by": [
"apps","ad_unit_id"]
}

Response:

Name

Type

Description

id

string

ID of the report

created_at

Timestamp (string)

UTC timestamp

parameters

Report parameters

JSON body posted during initial request

state

String

Queued, cancelled, completed, failed

Sample curl

curl --header "Content-Type: application/json" \
--request
POST \
--
data
'{
"start_time":"2020-10-01T00:00:00Z","end_time":"2020-11-01T00:00:00Z"}' \
--user 'username' https://
data.liftoff.io/api/publishers/v1/reports

Sample Response: header

...
content-
type: application/json;charset=utf-8
x-rate-limit-max: 5
x-rate-limit-remaining: 0

Sample Response: body

{
   "id":
"abc123",
   "created_at":
"2020-11-15T00:00:00Z",
   "state":
"queued",
   "parameters": {
       "app_ids": [
"xyz123","jkl456"],
       "group_by": [
"app_name","ad_unit_id”],
       "start_time":
"2020-10-01T00:00:00Z",
       "end_time":
"2020-11-01T00:00:00Z"
   }
}

/reports/<report_id>/status

This endpoint provides the status of the report.

Sample curl

curl --user 'username'
'https://data.liftoff.io/api/publishers/v1/reports/abc123/status'

Sample response

{
   "id":
"abc123",
   "created_at":
"2020-11-15T00:00:00Z",
   "state":
"failed",
}

/reports/<report_id>/data

GET

This endpoint allows you to download the report. The report can either be a JSON or a CSV, depending on which format option was chosen when the report was created.

Response:

Name

Type

Description

date

date

yyyy-mm-dd

app_id

string

ID of the application showing Liftoff ads

app_name

string

App title

Implicitly included from grouping by app_id

platform

string

iOS

Implicitly included from grouping by app_id

country_code

string

2 letter country code (e.g. “US”)

ad_size

string

Size of the ad unit (e.g. “320x50”)

is_rewarded

bool

Whether or not the ad unit is rewarded

ad_unit_id

string

The app’s ad unit id

ad_unit_name

string

The ad unit’s display name

Implicitly included from grouping by ad_unit_id

impressions

int

Number of ad impressions shown

clicks

int

Number of clicks on the ads

ctr

float

Click through rate

revenue

float

Revenue from the ads shown, in USD

ecpm

float

Effective cost per thousand impressions

requests

int

Number of times the app requested an ad

fill_rate

float

Impressions divided by requests

Sample Response (CSV)

date, app_id, ad_unit_id, ad_size, impressions, clicks, revenue, ecpm, requests, fill_rate
2020-11-15, xy123, def12345, 320x480, 2000, 20, 3, 1.5, 4000, 0.75

/apps

This endpoint allows you to query metadata about apps.

Name

Type

Description

id

string

ID of the application showing Liftoff ads

name

string

App title

bundle_id

string

App’s bundle ID

app_store_id

string

App’s Apple store ID

platform

string

iOS

Sample curl

curl --user 'username' 'https://data.liftoff.io/api/publishers/v1/apps'

Sample response body

[
   {
       "
id": "xyz123",
       "name":
"Sample App",
       "app_store_id":
"io.liftoff.sample",
       "bundle_id":
"io.liftoff.sample",
       "title":
"Sample",
       "platform":
"iOS",
   },
   ...

]

/ad_units

This endpoint allows you to query metadata about ad units.

Name

Type

Description

id

string

ID of the ad unit

name

string

Ad unit display name

app_id

string

ID of the app that this ad unit belongs to

Sample curl

curl --user 'username' 'https://data.liftoff.io/api/publishers/v1/ad_units'

Sample response body

[
   {
       "
id": "abc456",
       "name":
"Sample Ad Unit",
       "app_id":
"xyz123",
   },
   ...

]

Throttling

All endpoints are rate limited:

Endpoint

HTTP Method

Rate limit (requests per hour)

/api/v1/reports

GET

60

/api/v1/reports

POST

30

/api/v1/reports?test=true

POST

60

/api/v1/reports/<id>/status

GET

1000

/api/v1/reports/<id>/data

GET

10

/api/v1/<entity_type>

GET

60

Note: responses to any rate-limited endpoints will have x-rate-limit-max and x-rate-limit-remaining headers.