Reporting API Guidelines

This is a recommended reporting API example for Partner who wants to integrate with Singular via API and exploring guidelines. 

Description: This API document will highlight what is needed for Singular to retrieve campaign metrics for an advertiser based on the requested breakdowns and filters.

Basic Rules

  • API Response Format: JSON or CSV (the response format that you would support)
  • Method: GET (Singular will retrieve the data from your API)
  • API endpoint: please share with us your API endpoint

Query Parameters

Name

Required

Query Parameter

Description

Examples

start_date

Yes

Date

Start Date

2018-01-01

end_date

Yes

Date

End Date

2018-01-02


Dimensions - Minimum requirements in order to start integration - date(daily breakdown date), campaign name and cost. We support multiple granular dimensions, please find them below.

Name

Description

Examples

date

Date

2018-01-01

app

Advertiser App Name / Site Name

2018-01-02

site_public_id

Site Public ID (Store ID)

 

campaign_name

Campaign name as reported by the Network

 

campaign_id

Campaign ID as reported by the Network

 

campaign_url

Campaign URL (Tracking URL/Store URL)

 

sub_campaign name

Sub-campaign (e.g., Ad Group) name when applicable

 

sub_campaign_id

Sub-campaign (e.g., Ad Group) ID when applicable

 

country

Country

 

platform

Platform (e.g iPhone) for the app

iPhone, iPad

os

Operating system for the app. Non-mobile this would be “web”

iOS, Android, Web

creative_name

Creative Name

 

creative_id

Creative ID

 

creative_url

The URL to the creative assets (Image/Video)

 

creative_text

Text portion of the creative, if there is text

 

creative_width

Creative width in pixels

 

creative_height

Creative height in pixels

 

publisher_site_name

The name of the publisher (app) in which the ad has been displayed. This is only populated in cases where the ad network reports it.

 

publisher_site_id

The public ID of the publisher (app) in which the ad has been displayed. This is only populated in cases where the ad network reports it.

 

publisher_id

The hashed ID of the publisher (app) in which the ad has been displayed

 

currency

Currency

 

adnetwork_name

Ad Network Name (Only for Agencies)

 

 

Metrics

Name

Description

Examples

impressions

Impressions reported by the Network

 

clicks

Clicks

 

installs

Installs or Conversions

 

cost

Cost reported by the Network

 

 

Examples:

Assuming your report API token is 4ru34ur3u4u5i3pteqrt

Request:

GET

https://api.partnername.net/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2018-01-01&end_dat e=2018-04-01

Response is in CSV.

Date,campaign_name,site_public_id,os,creative_name,creative_id,creative_url,Impressions,Clicks,Installs,Cost
2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,3,http://partnername.net/interstitials4.jpg,292088,11244,238,166.6

2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,2,http://partnername.net/banner2.jpg,16444743,86716,4366,3056.2 2018-01-01,Fresh Air iOS Campaign

(US),1195648107,iOS,banner,1,http://partnername.net/banner1.jpg, 802797,40263,1800,3960.0

2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,video,3,http://partnername.net/video3.jpg,398590,17107,763,2479.75

2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,4,http://partnername.net/banner4.jpg,423573,15429,454,317.8

2018-01-02,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,2,http://partnername.net/interstitials2.jpg,1425602,69436,2771,6096.2

 

Request:

GET

https://api.partnername.net/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2018-01-01&end_dat e=2018-04-01 &format=JSON

Response is in JSON.

[ {

"date": "2018-01-01",

"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 3,

"creative_url": http://partnername.net/interstitials4.jpg
"impressions": 292088,
"clicks": 11244,
"installs": 238,
"cost": "166.6"

}, {

"date": "2018-01-01",

"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 2,

"creative_url": http://partnername.net/banner2.jpg
"impressions": 16444743,
"clicks": 86716,
"installs": 4366,
"cost": "3056.2"

}, {

"date": "2018-01-01",

"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 1,

"creative_url": http://partnername.net/banner1.jpg
"impressions": 802797,
"clicks": 40263,
"installs": 1800,
"cost": "3960.0"

}, {

"date": "2018-01-01",

"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 4,

"creative_url": http://partnername.net/banner4.jpg
"impressions": 398590,
"clicks": 17107,
"installs": 763,
"cost": "2479.75"

}, {

"date": "2018-01-01",

"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 2,

"creative_url": http://partnername.net/interstitials2.jpg
"impressions": 423573,
"clicks": 15429,
"installs": 454,
"cost": "317.8"

}]

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.