Publisher Reporting API

Overview

A Publisher Reporting API is available to our Publishers who wish to access their site/app performance data from outside the Conversant Publisher Portal.

Reporting API access is available upon publisher request and can only be enabled by contacting Conversant Support.

Supply-Side Partners working with our Publishers will require approval by our Publishers to retrieve Conversant site/app data on their behalf.

Reporting API Intended Use

The Reporting API is designed to be used by Publishers who wish to view their Conversant app and mobile website data in:

  • a Mediation Layer's Publisher Portal Reports or Dashboard section (requires Publisher opt-in)
  • a 3rd Party Supply-Side Platform's Reports or Dashboard (requires Publisher opt-in)
  • a custom Report and/or Dashboard developed by the Publisher

A full list of 3rd Party Supply-Side Platforms and Mediation Layers which currently support the Publisher Reporting API is available here.


1: Obtaining an Account

1.1: Request a Reporting API account

Contact support_mobile@conversantmedia.com to request a Reporting API account.

The Publisher Reporting API account will be a separate username and password from the Publisher Portal login account for security purposes.

Account Request Guidelines

  • A Conversant Publisher Account and an approved site or app are prerequisites for connecting to the Reporting API.
  • Publisher requests must be made from one of the following email addresses:
    • An email account associated with the Conversant Publisher Portal account
    • An email associated with the company website domain, i.e. email@yourcompany.com
  • Mediation Layer requests must cc the publisher on any request.

1.2: API Access Approval

API account processing may take up to 2 business days to be fulfilled.

An API username, password and publisher id will be issued once the API account has been processed.


2: Authentication

An authentication token is required to be passed with all Reporting API data requests. The token can be obtained by calling the /login URI with a valid login name, password and publisher id.

2.1: Endpoint

http://api.valueclickmedia.com/login

2.2: Request Parameters

Parameter NameRequired/OptionalFormatParameter ValuesDescription
userRequiredStringExample:
greystripe
Reporting API login name assigned by Greystripe.*
passwordRequiredStringExample:
Conversant123
Reporting API password assigned by Greystripe.*
publisher_idRequiredIntegerExample:
35001
The Publisher's Account ID or "PID" assigned by Greystripe in the Publisher Portal.
formatOptionalStringAccepted values:
xml
json
Formats the response data in XML or JSON. Defaults to XML format.
* For security purposes, the Publisher Reporting API login and password will be different from the Publisher's Portal login and password credentials.
Sample POST Request
POST /login HTTP/1.1
Host: api.valueclick.com
Content-Length: 70
Content-Type: application/x-www-form-urlencoded

user=greystripe&password=Conversant123&publisher_id=35001&format=xml

2.3: Response Data

Response DataFormatDescription
auth_tokenStringUse the auth_token for all Reporting API calls.
XML Sample
<?xml version='1.0' standalone='yes'?>
<auth_token>53616c7465645f5f3e2d48f94df2c9e97f960a577141235f02542a5ce19a33adf0cf72e00bdbe0f4eed3e982b3e903cbe2bfa3599bd77f443c97181cad23a501</auth_token>
JSON Sample
{"auth_token":"53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1"}

3: Site & App Metadata

Returns metadata for all sites and apps configured by the publisher in the Conversant Publisher Portal. Can be useful for retrieving an individual site_id or app_id.

3.1: Endpoint

http://api.valueclickmedia.com/pub/sites

3.2: Request Parameters

Parameter NameRequired/OptionalFormatParameter ValuesDescription
auth_tokenRequiredStringExample:
See section 2.3 "Authentication Response"
The authentication token generate by the /login endpoint
formatOptionalStringAccepted values:
xml
json
Formats the response data in XML or JSON. Defaults to XML format.
Sample POST Request
POST /sites HTTP/1.1
Host: api.valueclick.com
Content-Length: 150
Content-Type: application/x-www-form-urlencoded

auth_token=53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1&format=xml

3.3: Response Data

Response DataFormatDescription
app_idStringApp ID value for an app.
site_idStringSite ID value for a website.
site_type_idStringSite Type ID value. See table in Section 3.4 for more details
titleStringThe title of the Site or App in the Publisher Portal.
Note: Mobile Optimized Websites will return both app_id and site_id for legacy reasons. For querying purposes in Section 4 and 5, use site_id for this site type.

XML Sample

<?xml version='1.0' standalone='yes'?>
<sites>
  <site>
    <app_id>8b9e03e2-72e7-4ec3-bf60-eecf99a5144f</app_id>
    <site_id>74740</site_id>
    <site_type_id>5</site_type_id>
    <title>Mobile Web Test Ads</title>
  </site>
  <site>
    <app_id>5f750a48-7e73-42e7-bede-839fda15f367</app_id>
    <site_id>73947</site_id>
    <site_type_id>9</site_type_id>
    <title>iOS Test Ads</title>
  </site>
</sites>

JSON Sample

{"site":[{"site_type_id":"5","app_id":"8b9e03e2-72e7-4ec3-bf60-eecf99a5144f","site_id":"74740","title":"Mobile Web Test Ads"},{"site_type_id":"9","app_id":"5f750a48-7e73-42e7-bede-839fda15f367","site_id":"73947","title":"iOS Test Ads"}]}

3.4: Site Type ID Key

This table describes what the values in the /sites response data for site_type_id xml/json represents. The query id is useful for getting specific site/app data from endpoints in Sections 4 and 5.

Site Type IDSite Type NameSite TypeQuery ID
1Web SiteSitesite_id
2Browser PluginSitesite_id
3Peer to Peer Sitesite_id
4Multiple SitesSitesite_id
5Mobile Optimized Web SiteSitesite_id
6Android App - Amazon AppstoreAppapp_id
7iOS app - iPadAppapp_id
8iOS app - iPhoneAppapp_id
9iOS app - UniversalAppapp_id
10Android App - Google PlayAppapp_id

4: Site & App Performance Data

4.1: Endpoint

http://api.valueclickmedia.com/pub/earnings

4.2: Request Parameters

Parameter NameRequired/OptionalFormatParameter ValuesDescription
auth_tokenRequiredStringExample:
See section 2.3 "Authentication Response"
The authentication token generate by the /login endpoint
site_idOptionalIntegerExample:
74740
Use to return data for a specific Site ID. Do not use in same query as App ID.
app_idOptionalStringExample:
5f750a48-7e73-42e7-bede-839fda15f367
Use to return data for a specific App ID. Do not use in same query as Site ID.
start_dateOptionalStringExample:
2014-01-31
Beginning of date range to include data. Format YYYY-MM-DD
end_dateOptionalStringExample:
2014-01-31
End of date range to include data. Format YYYY-MM-DD
group_byOptionalStringAccepted values:
date
site
media_type
supply_type
country
Provide a way of grouping the results together for reporting. Comma separate values to include several for sorting like so: group_by=data,media_type. "site" works for both apps and sites.
country_cdOptionalStringExamples:
us
CA
Filters the request by country. Query using ISO 3166-1 alpha 2 codes. Uppercase or lowercase codes accepted. One country accepted per query.
formatOptionalStringAccepted values:
xml
json
Formats the response data in XML or JSON. Defaults to XML format.
Note: Accurate same day reporting is a known issue. This occurs when start_date and end_date are not added to the POST query. Best practice is to query for yesterday's full data after 1am GMT by including both the start_date and end_date for the previous day.
Sample POST Request - App ID
POST /sites HTTP/1.1
Host: api.valueclick.com
Content-Length: 236
Content-Type: application/x-www-form-urlencoded

auth_token=53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1&format=xml&app_id=5f750a48-7e73-42e7-bede-839fda15f367&start_date=2014-04-01&end_date=2014-04-01
Sample POST Request - Site ID
POST /sites HTTP/1.1
Host: api.valueclick.com
Content-Length: 206
Content-Type: application/x-www-form-urlencoded

auth_token=53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1&format=xml&site_id=74740&start_date=2014-04-01&end_date=2014-04-01

4.3: Response Data

Response DataFormatDescriptionQuery Dependency
requestsIntegerThe total requests based on the query.
deliveriesIntegerThe total deliveries (pre-impressions) based on the query.
impressionsIntegerThe total impressions based on the query.
clicksIntegerThe total clicks based on the query.
earningsFloatThe total earnings based on the query
currency_codeStringThe currency of the earnings for the app/site.
dayStringThe day the above data represents.group_by=date
media_typeStringThe media type the above data represents.group_by=media_type
media_type_idIntegerThe media type id the above data represents.group_by=media_type
app_idStringApp ID value for an app.group_by=site
site_idIntegerSite ID value for a website.group_by=site
titleStringThe title of the Site or App in the Publisher Portal.group_by=site
supply_type String Name of the supply type group_by=supply_type
supply_type_id String ID for the supply type group_by=supply_type
Note: Response data that requires a query dependency is data that will only return when the group_by parameter is sent with the request. The data returned depends on the query supplied. Data that does not have this dependency always is returned.
XML Sample
<?xml version='1.0' standalone='yes'?>
<earnings>
  <row>
    <clicks>9</clicks>
    <currency_code>USD</currency_code>
    <deliveries>93</deliveries>
    <earnings>.000203</earnings>
    <impressions>44</impressions>
    <requests>93</requests>
  </row>
</earnings>
JSON Sample
{"row":[{"earnings":".000203","impressions":"44","currency_code":"USD","clicks":"9","requests":"93","deliveries":"93"}]}

5: Site & App Performance Data by Placement

Placement level reporting is currently only available through our MoPub Mediation Integration.

This API can be called via GET.

This API will always return the data as a CSV.

You do not need to get an auth-token from /login first for this endpoint.

5.1: Endpoint

http://api.valueclickmedia.com/pub/placement_earnings

5.2: Request Parameters

Parameter NameRequired/OptionalFormatParameter ValuesDescription
auth_tokenRequiredStringExample:
See section 2.3 "Authentication Response"
The authentication token generate by the /login endpoint
appidOptionalStringExample:
108060
Use to return data for a specific App ID.
fromDateOptionalStringExample:
2014-01-31
Beginning of date range to include data. Format YYYY-MM-DD
toDateOptionalStringExample:
2014-01-31
End of date range to include data. Format YYYY-MM-DD
groupByOptionalStringAccepted values:
date
appid
country
adunitid
Provide a way of grouping the results together for reporting. Comma separate values to include several for sorting like so: group_by=data,adunitid
Note: Accurate same day reporting is a known issue. This occurs when fromDate and toDate are not added to the POST query. Best practice is to query for yesterday's full data after 1am GMT by including both the start_date and end_date for the previous day.
Sample GET Request
GET /pub/placement_earnings?toDate=2017-05-17&format=json&fromDate=2017-05-01&user=[USER]&pass=[PASS]&country_cd=US&groupBy=date%2Cappid%2Cadunitid%2Ccountry HTTP/1.1
Host: api.valueclickmedia.com
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: /
User-Agent: python-requests/2.12.3

5.3: Response Data

Response DataFormatDescriptionQuery Dependency
requestsIntegerThe total requests based on the query.
impressionsIntegerThe total impressions based on the query.
clicksIntegerThe total clicks based on the query.
revenueFloatThe total earnings based on the query
dateStringThe day the above data represents.group_by=date
appidStringApp ID value for an app.group_by=appid
adunitidIntegerPlacement ID for the app.group_by=adunitid
countryIntegerCountry code.group_by=country
Note: Response data that requires a query dependency is data that will only return when the groupBy parameter is sent with the request. The data returned depends on the query supplied. Data that does not have this dependency always is returned.
Sample
date,appid,adunitid,country,requests,impressions,clicks,revenue
2017-05-15,11111,6b7364e0-055a-44af-931d-0b5d8af95c56,US,15,15,0,.00001

6: Countries

Retuns info on countries including their country ID and their ISO 3166-1 alpha 2 code. No reporting data is returned.

6.1: Endpoint

http://api.valueclickmedia.com/pub/countries

6.2: Request Parameters

Parameter Name Required/Optional Format Parameter Values Description
auth_tokenRequiredStringExample:
See section 2.3 "Authentication Response"
The authentication token generate by the /login endpoint
format Optional String Accepted values:
xml
json
Formats the response data in XML or JSON. Defaults to XML format.
Sample POST Request
POST /pub/countries HTTP/1.1
Host: api.valueclickmedia.com
Content-Length: 150
Content-Type: application/x-www-form-urlencoded
auth_token=53616c7465645f5f871acb38783017c9cc0adf62fd602bb360ccd62e9 6cb9fd5c90e891f25685a918c9706a9a1b73ed8c6041c0314c0cc573edcd9b04b366d26&format=xml

6.3: Response Data

Response Data Format Description
country_id Integer The Country ID.
country_name String The name of the country.
country_cd String The ISO 3166-1 alpha 2 code.
XML Sample
<?xml version='1.0' standalone='yes'?> <countries>
<country>
<country_cd>AE</country_cd> <country_id>252</country_id>
<country_name>United Arab Emirates</country_name>
</country> <country>
<country_cd>GB</country_cd> <country_id>253</country_id> <country_name>United Kingdom</country_name>
</country> <country>
<country_cd>US</country_cd> <country_id>254</country_id> <country_name>United States</country_name>
</country> </countries>
Note: This is only a subset of the data that will be returned.
JSON Sample
{"country":[{"country_name":"Afghanistan","country_cd":"AF","cou
ntry_id":"1"},{"country_name":"Albania","country_cd":"AL","count
ry_id":"2"},{"country_name":"Algeria","country_cd":"DZ","country
_id":"3"},{"country_name":"American
Samoa","country_cd":"AS","country_id":"4"},{"country_name":"Zimb
abwe","country_cd":"ZW","country_id":"274"},{"country_name":"Occ
upied Palestinian
Territory","country_cd":"PS","country_id":"275"}]}
Note: This is only a subset of the data that will be returned.

7: Site & App Performance Data

7.1: Endpoint

https://api.valueclickmedia.com/pub/default_impressions

7.2: Request Parameters

Parameter Name Required/Optional Format Parameter Values Description
auth_token Required String Example:
See section 2.3 "Authentication Response"
The authentication token generate by the /login endpoint
site_id Optional Integer Example:
74740
Use to return data for a specific Site ID. Do not use in same query as App ID.
app_id Optional String Example:
5f750a48-7e73-42e7-bede-839fda15f367
Use to return data for a specific App ID. Do not use in same query as Site ID.
start_date Optional String Example:
2014-01-31
Beginning of date range to include data. Format YYYY-MM-DD
end_date Optional String Example:
2014-01-31
End of date range to include data. Format YYYY-MM-DD
group_by Optional String Accepted values:
date
site
media_type
supply_type
Provide a way of grouping the results together for reporting. Comma separate values to include several for sorting like so: group_by=data,media_type. "site" works for both apps and sites.
country_cd Optional String Examples:
us
CA
Filters the request by country. Query using ISO 3166-1 alpha 2 codes. Uppercase or lowercase codes accepted. One country accepted per query.
format Optional String Accepted values:
xml
json
Formats the response data in XML or JSON. Defaults to XML format.
Note: Accurate same day reporting is a known issue. This occurs when start_date and end_date are not added to the POST query. Best practice is to query for yesterday's full data after 1am GMT by including both the start_date and end_date for the previous day.
Sample POST Request - App ID
POST /sites HTTP/1.1
Host: api.valueclick.com
Content-Length: 236
Content-Type: application/x-www-form-urlencoded

auth_token=53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1&format=xml&app_id=5f750a48-7e73-42e7-bede-839fda15f367&start_date=2014-04-01&end_date=2014-04-01
Sample POST Request - Site ID
POST /sites HTTP/1.1
Host: api.valueclick.com
Content-Length: 206
Content-Type: application/x-www-form-urlencoded

auth_token=53616c7465645f5fb5d45a974c1cdc89aea10832be01db98ee88740453736d8c021ad71128151b39b04d9e5adc14f91c4427743067ce44ac45fe5f7609d765a1&format=xml&site_id=74740&start_date=2014-04-01&end_date=2014-04-01

7.3: Response Data

Response Data Format Description Query Dependency
default_impressions Integer The total default impressions based on the query.
day String The day the above data represents. group_by=date
media_type String The media type the above data represents. group_by=media_type
media_type_id Integer The media type id the above data represents. group_by=media_type
app_id String App ID value for an app. group_by=site
site_id Integer Site ID value for a website. group_by=site
title String The title of the Site or App in the Publisher Portal. group_by=site
country_id Integer Country ID for reporting. group_by=country
country_cd String Country CD group_by=country using ISO 3166-1 alpha 2 codes. group_by=country
country String Country name. group_by=country
supply_type String Name of the supply type group_by=supply_type
supply_type_id String ID for the supply type group_by=supply_type
Note: Response data that requires a query dependency is data that will only return when the group_by parameter is sent with the request. The data returned depends on the query supplied. Data that does not have this dependency always is returned.
XML Sample
<?xml version='1.0' standalone='yes'?> 
<default_impressions>
   <row>
        <day>2016-05-02</day> <default_impressions>44</default_impressions>
    </row>
</default_impressions>
JSON Sample
{
   "row":
   [
      {
          "day":"2016-05-02",
           "default_impressions":"44”
      }
]
}

8: Exception Handling

It is possible to receive a timeout when waiting for a response to a request especially at peak times when processing a large number of requests. The API may also return any of the following exception responses:

8.1: Response Data on Error

Response DataFormatDescription
errorsStringDate range is limited to 180 days
errorsStringUnknown publisher
XML Sample
<?xml version=’1.0’ standalone=’yes’?>
<errors>Date range is limited to 180 days</errors>
JSON Sample
{"errors":["start_date is limited to 180 days ago"]}