Integrating with Singular Analytics via API (Partners)

Follow
Avatar
Sapir Sultan
Updated

This guide is for Singular analytics partners who want to integrate with Singular by providing access to their reporting API. Learn more in the Integrating with Singular Analytics FAQ.

If you are a Singular customer, see Guide to the Singular Reporting API and the Reporting API Reference instead.

Minimum Requirements

To integrate with Singular, your API must provide the following:

    • Method: GET or POST
    • API response format: JSON or CSV
    • Data:
      • App / Brand Name + Platform OR App Store ID (to identify individual apps)
      • Campaign Name
      • Cost
      • The data must be broken down by day (date)
    • Query parameters: Singular should be able to request data by Start Date and End Date
    • Filtering: Singular should be capable of filtering data for individual clients.

Notes on Filtering: Kindly note that if your API requires unique credentials for each client, there is no necessity to implement additional filtering mechanisms.

Additional Data (Recommended)

To provide our shared clients with the highest reporting granularity, we encourage you to provide as many additional dimensions and metrics as possible fron the list below:

Dimensions (Breakdowns)

Dimension Description
app The name of the app or brand
site_public_id The app's ID in the Apple App Store or Google Play
campaign_name  
campaign_id  
campaign_url The campaign URL, a.k.a tracking URL/store URL
sub_campaign_name The name of the ad group/ad set, if applicable
sub_campaign_id The ID of the ad group/ad set, if applicable
country  
platform The app's platform, e.g., iOS
os The app's operating system. For non-mobile products, this is "web"
creative_name The name of the creative or ad
creative_id The ID of the creative or ad
creative_url The URL to the creative assets (Image/Video)
creative_text The text portion of the creative, if any
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
publisher_site_id The public ID of the publisher (app) in which the ad has been displayed
publisher_id The hashed ID of the publisher (app) in which the ad has been displayed
currency  
adnetwork_name The name of the ad network (if you are an agency and you are providing campaign data from multiple ad networks)

Metrics

Metric Description
impressions  
clicks  
installs App installs or conversions

Implementation Examples

Here are examples of API requests and responses that Singular can work with.

Request (GET):

https:///api.examplepartner.com/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2022-01-01&end_date=2022-04-01

The response in CSV:

Date,campaign_name,site_public_id,os,creative_name,creative_id,creative_url,Impressions,Clicks,Installs,Cost
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,3,http://examplepartner.com/interstitials4.jpg,292088,11244,238,166.6 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,2,http://examplepartner.com/banner2.jpg,16444743,86716,4366,3056.2 2022-01-01,Fresh Air iOS Campaign 
(US),1195648107,iOS,banner,1,http://examplepartner.com/banner1.jpg, 802797,40263,1800,3960.0 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,video,3,http://examplepartner.com/video3.jpg,398590,17107,763,2479.75 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,4,http://examplepartner.com/banner4.jpg,423573,15429,454,317.8 
2022-01-02,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,2,http://examplepartner.com/interstitials2.jpg,1425602,69436,2771,6096.2

Request (GET):

https:///api.examplepartner.com/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2022-01-01&end_date=2022-04-01&format=JSON

The response in JSON:

[ { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 3,
"creative_url": http://examplepartner.com/interstitials4.jpg
"impressions": 292088,
"clicks": 11244,
"installs": 238,
"cost": "166.6" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 2,
"creative_url": http://examplepartner.com/banner2.jpg
"impressions": 16444743,
"clicks": 86716,
"installs": 4366,
"cost": "3056.2" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 1,
"creative_url": http://examplepartner.com/banner1.jpg
"impressions": 802797,
"clicks": 40263,
"installs": 1800,
"cost": "3960.0" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 4,
"creative_url": http://examplepartner.com/banner4.jpg
"impressions": 398590,
"clicks": 17107,
"installs": 763,
"cost": "2479.75" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 2,
"creative_url": http://examplepartner.com/interstitials2.jpg
"impressions": 423573,
"clicks": 15429,
"installs": 454,
"cost": "317.8" 
}]