Libring Reporting API

Say goodbye to multiple API calls and messy data. Libring Reporting API enables you to pull all your clean and normalized data in a single API call to power your BI system.

Libring’s RESTful API has other two methods besides the Reporting API:  

EVENTS API
CONNECTIONS STATUS API

The token to start using the Libring Reporting API is located in the ‘Edit Organization’ page of Edge on the bottom right of the page. Click on the blue box containing the token and copy into your API call.

Request

https://api.libring.com/v2/reporting/get

Method

GET

Required Authorization

Name Example
token ‘Authorization’=>”Token TOKEN_CODE”

Optional Parameters

Parameter Type Description Example
period String Options allowed:

  • yesterday (default)
  • last_week
  • last_month
  • custom_date

By default, it will be yesterday.

 “yesterday”
start_date String When you select “custom_date” you must inform this value. Format YYYY-MM-DD. This is an inclusive date. “2016-04-10”
end_date String When you select “custom_date” you must inform this value. Format YYYY-MM-DD. This is an inclusive date. Must be equal or higher than Start Date. “2016-04-12”
country_format String Default: name
name: returns full country’s name. e.g “United States”
alpha-2: returns country’s abbreviation with two characters. e.g “US”
alpha-3: returns country’s abbreviation with three characters. e.g “USA”
iso_number: returns country’s iso number. e.g “840”		 “United States”
group_by String Segment your data by the following dimensions:

  • date (default)
  • connection
  • app
  • platform
  • ad_type
  • ad_format
  • custom_1
  • custom_2
  • custom_3
  • custom_4
  • campaign
  • ad
  • ctm
  • country

Separate group_by parameters with comma. The reporting data will always be grouped at least by date. Custom dimensions can be configured and renamed in the platform.

 “connection,country”
data_type String Options allowed:

  • all (default)
  • acquisition
  • adnetwork
  • usage
  • appstore

Separate data_type parameters with comma.

 “acquisition”
filter String Default required: name:value;name;valueAllowed names:

  • connection
  • app
  • platform
  • ad_type
  • ad_format
  • custom_1
  • custom_2
  • custom_3
  • custom_4
  • campaign
  • ad
  • ctm
  • country

You may use wildcard character “%” to search for parts of words. If you use more than one expression, the API will search for both values (AND concatenation), for example, “app AND platform” and not “app OR platform”. PS: If you need to use space, use the symbol %20 and not only %, example: filter[]=platform:Apple%20Search

 “filter[]=platform:Android” “filter[]=platform:And%” “filter[]=app:MyApp&filter[]=platform:iOS”
lock_on_collection String Optional Parameter Default:true

  • true – locks the API during data collection not returning any values.
  • false – Partially locks the API returning data for every connection that is not being collected at the time. An array showing the connections being collected at the time.

Metrics (Response)

Field Type Source Description
impressions Integer Adnetwork Total number of impressions.
clicks Integer Adnetwork Total number of clicks.
requests Integer Adnetwork Total number of requests.
conversions Integer Adnetwork Total number of conversions.
completions Integer Adnetwork Total number of conversions.
ad_revenue Decimal Adnetwork Total adnetworks revenue.
ad_gross_revenue Decimal Adnetwork Total of adnetworks gross revenue.
fill_rate Decimal Adnetwork Calculated Fill Rate (Impressions/Requests).
ad_cpm Decimal Adnetwork Calculated CPM (Revenue/(Impressions/1000)).
ctr Decimal Adnetwork Calculated CTR (Clicks/Impressions).
iap_revenue Decimal Appstore Total IAP revenue.
iap_revenue_gross Decimal Appstore Total IAP revenue gross.
downloads Integer Appstore Total number of downloads.
returns Integer Appstore Total number of returns.
updates Integer Appstore Total number of updates.
hits Integer Usage Total number of hits.
user_sessions Integer Usage Total number of user sessions.
new_users Integer Usage Total number of unique new users.
paying_users Integer Usage Total number of paying users.
dau Integer Usage Total number of dau.
mau Integer Usage Total number of mau.
spent Decimal Acquisition Total number of spent.
acq_impressions Integer Acquisition Total number of impressions.
acq_clicks Integer Acquisition Total number of clicks.
acq_requests Integer Acquisition Total number of requests.
acq_installs Integer Acquisition Total number of installs.
acq_completions Integer Acquisition Total number of conversions.

Pagination

If your response has more than 1000 rows the API will return the data in multiple pages following the structure detailed below: First page:

https://api.libring.com/v2/reporting/get
{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1800,
    "current_rows": 1000,
    "total_pages": 2,
    "current_page": 1,
    "next_page_url": "https://api.libring.com/v2/reporting/get?page=2",
    "connections": [
      { ... }
    ]
  }
}

Second page:

https://api.libring.com/v2/reporting/get?page=2
{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 800,
    "current_page_rows": 300,
    "total_pages": 2,
    "current_page": 2,
    "next_page_url": "",
    "connections": [
      { ... }
    ]
  }
}

Request Example

https://api.libring.com/v2/reporting/get?period=custom_date&start_date=2016-04-10&end_date=2016-04-15&data_type=adnetwork,acquisition&group_by=date,connection

Response Examples

Responses will be in JSON format.

No data found (lock_on_collection false)

{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 0,
    "current_page_rows": 0,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    "connections": []
  }
}

Data found(lock_on_collection false)

{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1,
    "current_page_rows": 3,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    "connections": [
      {
        "date": "2016-04-16",
        "segment": "adnetwork",
        "connection": "AdMob",
        "app": "My Game 1",
        "platform": "iOS",
        "ad_type": "Banner",
        "ad_format": "500x500",
        "country": "Brazil",
        "ad": "",
        "campaign:" "",
        "impressions": 100,
        "clicks": 34,
        "requests": 300,
        "conversions": 2,
        "ad_revenue": 10.56,
        "ad_revenue_gross": 12.56,
        "completions": 34,
        "conversions": 300,
        "fill_rate": 1,
        "ctr": 1,
        "ad_cpm": 1,
        "downloads": 0,
        "updates": 0,
        "returns": 0,
        "iap_revenue": 0,
        "iap_revenue_gross": 0,
        "hits": 0,
        "user_sessions": 0,
        "new_users": 0,
        "spent": 0,
        "acq_requests": 0,
        "acq_clicks": 0,
        "acq_impressions": 0,
        "acq_conversions": 0,
        "acq_completions": 0
      }
    ]
  }
}

No data found (lock_on_collection true)

{
    "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 0,
    "current_page_rows": 0,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    “locked_due_to_collection”: [],
    "connections": []
  }
}

Data found(lock_on_collection true)

{
    "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1,
    "current_page_rows": 3,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    “locked_due_to_collection”: [],
    "connections": [
      {
        "date": "2016-04-16",
        "segment": "adnetwork",
        "connection": "AdMob",
        "app": "My Game 1",
        "platform": "iOS",
        "ad_type": "Banner",
        "ad_format": "500x500",
        "country": "Brazil",
        "ad": "",
        "campaign:" "",
        "impressions": 100,
        "clicks": 34,
        "requests": 300,
        "conversions": 2,
        "ad_revenue": 10.56,
        "ad_revenue_gross": 12.56,
        "completions": 34,
        "conversions": 300,
        "fill_rate": 1,
        "ctr": 1,
        "ad_cpm": 1,
        "downloads": 0,
        "updates": 0,
        "returns": 0,
        "iap_revenue": 0,
        "iap_revenue_gross": 0,
        "hits": 0,
        "user_sessions": 0,
        "new_users": 0,
        "spent": 0,
        "acq_requests": 0,
        "acq_clicks": 0,
        "acq_impressions": 0,
        "acq_conversions": 0,
        "acq_completions": 0
      }
    ]
  }
}

Response

HTTP Status
200 OK Positive response, all fine
400 Bad Request Error – If required parameter not provide
401 Unauthorized Error – When the api_token is not valid

 

Examples

require “net/https”
require “uri”
uri = URI.parse(‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’)
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
req = Net::HTTP::Get.new(uri.request_uri, initheader = {‘Content-Type’ =>’application/json’, ‘Authorization’ => ‘Token 1043tL2eZvKYlo2CSU3Tbnci’})
resp = https.request(req)
$access_token = “VqQGAfdeTNAKYgwOFiaoqGkgCrrI”;
$headers = array(‘Authorization: Token ‘ . $access_token);
$ch_subs = curl_init();
curl_setopt($ch_subs, CURLOPT_URL, ‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’);
curl_setopt($ch_subs, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch_subs, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch_subs, CURLOPT_POST, 0); curl_setopt($ch_subs, CURLOPT_HTTPHEADER, $headers);
echo curl_exec($ch_subs);
curl_close($ch_subs);
import requests
r = requests.get(‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’, headers={‘Authorization’:’Token feasvJ3gLU5cfx7UuzzfEVmhmvRfC’, ‘content-type’: ‘application/json’});
print r.text

Libring Reporting API

Libring Reporting API allows you to retrieve all your normalized data from the Libring Platform via RESTful API. 

Libring RESTful API has other two methods besides Libring Reporting API:  

CONNECTIONS STATUS API
LTV API

The token to start using the Libring Reporting API is located in the ‘Edit Organization’ page of Edge on the bottom right of the page. Click on the blue box containing the token and copy into your API call.

Request

https://api.libring.com/v2/reporting/get

Method

GET

Required Authorization

Name Example
token ‘Authorization’=>”Token TOKEN_CODE”

Optional Parameters

Parameter Type Description Example
period String Options allowed:

  • yesterday (default)
  • last_week
  • last_month
  • custom_date

By default, it will be yesterday.

 “yesterday”
start_date String When you select “custom_date” you must inform this value. Format YYYY-MM-DD. This is an inclusive date. “2016-04-10”
end_date String When you select “custom_date” you must inform this value. Format YYYY-MM-DD. This is an inclusive date. Must be equal or higher than Start Date. “2016-04-12”
country_format String Default: name
name: returns full country’s name. e.g “United States”
alpha-2: returns country’s abbreviation with two characters. e.g “US”
alpha-3: returns country’s abbreviation with three characters. e.g “USA”
iso_number: returns country’s iso number. e.g “840”		 “United States”
group_by String Segment your data by the following dimensions:

  • date (default)
  • connection
  • app
  • platform
  • ad_type
  • ad_format
  • custom_1
  • custom_2
  • custom_3
  • custom_4
  • campaign
  • ad
  • ctm
  • country

Separate group_by parameters with comma. The reporting data will always be grouped at least by date. Custom dimensions can be configured and renamed in the platform.

 “connection,country”
data_type String Options allowed:

  • all (default)
  • acquisition
  • adnetwork
  • usage
  • appstore

Separate data_type parameters with comma.

 “acquisition”
filter String Default required: name:value;name;valueAllowed names:

  • connection
  • app
  • platform
  • ad_type
  • ad_format
  • custom_1
  • custom_2
  • custom_3
  • custom_4
  • campaign
  • ad
  • ctm
  • country

You may use wildcard character “%” to search for parts of words. If you use more than one expression, the API will search for both values (AND concatenation), for example, “app AND platform” and not “app OR platform”. PS: If you need to use space, use the symbol %20 and not only %, example: filter[]=platform:Apple%20Search

 “filter[]=platform:Android” “filter[]=platform:And%” “filter[]=app:MyApp&filter[]=platform:iOS”
lock_on_collection String Optional Parameter Default:true

  • true – locks the API during data collection not returning any values.
  • false – Partially locks the API returning data for every connection that is not being collected at the time. An array showing the connections being collected at the time.

Metrics (Response)

Field Type Source Description
impressions Integer Adnetwork Total number of impressions.
clicks Integer Adnetwork Total number of clicks.
requests Integer Adnetwork Total number of requests.
conversions Integer Adnetwork Total number of conversions.
completions Integer Adnetwork Total number of conversions.
ad_revenue Decimal Adnetwork Total adnetworks revenue.
ad_gross_revenue Decimal Adnetwork Total of adnetworks gross revenue.
fill_rate Decimal Adnetwork Calculated Fill Rate (Impressions/Requests).
ad_cpm Decimal Adnetwork Calculated CPM (Revenue/(Impressions/1000)).
ctr Decimal Adnetwork Calculated CTR (Clicks/Impressions).
iap_revenue Decimal Appstore Total IAP revenue.
iap_revenue_gross Decimal Appstore Total IAP revenue gross.
downloads Integer Appstore Total number of downloads.
returns Integer Appstore Total number of returns.
updates Integer Appstore Total number of updates.
hits Integer Usage Total number of hits.
user_sessions Integer Usage Total number of user sessions.
new_users Integer Usage Total number of unique new users.
paying_users Integer Usage Total number of paying users.
dau Integer Usage Total number of dau.
mau Integer Usage Total number of mau.
spent Decimal Acquisition Total number of spent.
acq_impressions Integer Acquisition Total number of impressions.
acq_clicks Integer Acquisition Total number of clicks.
acq_requests Integer Acquisition Total number of requests.
acq_installs Integer Acquisition Total number of installs.
acq_completions Integer Acquisition Total number of conversions.

Pagination

If your response has more than 1000 rows the API will return the data in multiple pages following the structure detailed below: First page:

https://api.libring.com/v2/reporting/get
{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1800,
    "current_rows": 1000,
    "total_pages": 2,
    "current_page": 1,
    "next_page_url": "https://api.libring.com/v2/reporting/get?page=2",
    "connections": [
      { ... }
    ]
  }
}

Second page:

https://api.libring.com/v2/reporting/get?page=2
{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 800,
    "current_page_rows": 300,
    "total_pages": 2,
    "current_page": 2,
    "next_page_url": "",
    "connections": [
      { ... }
    ]
  }
}

Request Example

https://api.libring.com/v2/reporting/get?period=custom_date&start_date=2016-04-10&end_date=2016-04-15&data_type=adnetwork,acquisition&group_by=date,connection

Response Examples

Responses will be in JSON format.

No data found (lock_on_collection false)

{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 0,
    "current_page_rows": 0,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    "connections": []
  }
}

Data found(lock_on_collection false)

{
  "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1,
    "current_page_rows": 3,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    "connections": [
      {
        "date": "2016-04-16",
        "segment": "adnetwork",
        "connection": "AdMob",
        "app": "My Game 1",
        "platform": "iOS",
        "ad_type": "Banner",
        "ad_format": "500x500",
        "country": "Brazil",
        "ad": "",
        "campaign:" "",
        "impressions": 100,
        "clicks": 34,
        "requests": 300,
        "conversions": 2,
        "ad_revenue": 10.56,
        "ad_revenue_gross": 12.56,
        "completions": 34,
        "conversions": 300,
        "fill_rate": 1,
        "ctr": 1,
        "ad_cpm": 1,
        "downloads": 0,
        "updates": 0,
        "returns": 0,
        "iap_revenue": 0,
        "iap_revenue_gross": 0,
        "hits": 0,
        "user_sessions": 0,
        "new_users": 0,
        "spent": 0,
        "acq_requests": 0,
        "acq_clicks": 0,
        "acq_impressions": 0,
        "acq_conversions": 0,
        "acq_completions": 0
      }
    ]
  }
}

No data found (lock_on_collection true)

{
    "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 0,
    "current_page_rows": 0,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    “locked_due_to_collection”: [],
    "connections": []
  }
}

Data found(lock_on_collection true)

{
    "data": {
    "request_time": "2016-04-10 20:30:10",
    "total_rows": 1,
    "current_page_rows": 3,
    "total_pages": 1,
    "current_page": 1,
    "next_page_url": "",
    “locked_due_to_collection”: [],
    "connections": [
      {
        "date": "2016-04-16",
        "segment": "adnetwork",
        "connection": "AdMob",
        "app": "My Game 1",
        "platform": "iOS",
        "ad_type": "Banner",
        "ad_format": "500x500",
        "country": "Brazil",
        "ad": "",
        "campaign:" "",
        "impressions": 100,
        "clicks": 34,
        "requests": 300,
        "conversions": 2,
        "ad_revenue": 10.56,
        "ad_revenue_gross": 12.56,
        "completions": 34,
        "conversions": 300,
        "fill_rate": 1,
        "ctr": 1,
        "ad_cpm": 1,
        "downloads": 0,
        "updates": 0,
        "returns": 0,
        "iap_revenue": 0,
        "iap_revenue_gross": 0,
        "hits": 0,
        "user_sessions": 0,
        "new_users": 0,
        "spent": 0,
        "acq_requests": 0,
        "acq_clicks": 0,
        "acq_impressions": 0,
        "acq_conversions": 0,
        "acq_completions": 0
      }
    ]
  }
}

Response

HTTP Status
200 OK Positive response, all fine
400 Bad Request Error – If required parameter not provide
401 Unauthorized Error – When the api_token is not valid

 

Examples

require “net/https”
require “uri”
uri = URI.parse(‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’)
https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
req = Net::HTTP::Get.new(uri.request_uri, initheader = {‘Content-Type’ =>’application/json’, ‘Authorization’ => ‘Token 1043tL2eZvKYlo2CSU3Tbnci’})
resp = https.request(req)
$access_token = “VqQGAfdeTNAKYgwOFiaoqGkgCrrI”;
$headers = array(‘Authorization: Token ‘ . $access_token);
$ch_subs = curl_init();
curl_setopt($ch_subs, CURLOPT_URL, ‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’);
curl_setopt($ch_subs, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch_subs, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch_subs, CURLOPT_POST, 0); curl_setopt($ch_subs, CURLOPT_HTTPHEADER, $headers);
echo curl_exec($ch_subs);
curl_close($ch_subs);
import requests
r = requests.get(‘https://api.libring.com/v2/reporting/get?start_date=2018-02-10&end_date=2018-02-15&period=custom_date&group_by=date,connection,app,platform,country’, headers={‘Authorization’:’Token feasvJ3gLU5cfx7UuzzfEVmhmvRfC’, ‘content-type’: ‘application/json’});
print r.text

Contact Us

210 Broadway #201,
Cambridge, MA 02139

+1 617 858 6051
contact@libring.com

Follow Us