Skip to main content
Oath Inc.

1 How to Use the Public Reporting API

Prerequisites

Before you can start working with our public reporting API, 3 things need to be prepared:

  • Get Analytics Reports access: You need to be set-up with Analytics Reports access already. 
  • Get an application account: You need to be set-up with an Application account from the Oath Ad Platformss team. 
  • Link your application account to your Analytics Reports user: Once you have your application account with your public client id, that application account needs to be assigned to your Analytics Reports user. Email video.support@oath.com, provide your public client id, and make a request to have your application account added as the "Central Application id".

How to Use the Public Reporting API

Step Action
1

Obtain a token

To use the public API, you will need a token to each API request. For full instructions on how to create a token, see here: https://api.onereporting.aol.com/v4/docs.html

2

Create a report

Send a HTML POST request to https://api.stage.onereporting.aol.com/v4/report-management/report.

Example:

{
  "name": "New Report",
  "platformAlias": "O2",
  "archived": false,
  "shared": false,
  "mainFilter": "publisherCompanyWithAffiliates",
  "blocks": [
    {
      "title": "Report Section 1",
      "blockType": "TABLE",
      "withTotal": false,
      "metrics": [
        "billableImpressions"
      ],
      "dimensions": [
        "adCampaignId"
      ],
      "order": [
        {
          "columnId": "billableImpressions",
          "direction": "DESC"
        }
      ],
      "trendingTimeOption": "NONE",
      "forecasting": false
    }
  ]
}
3

Request data for a report

Follow the possible operations outlined here: https://api.onereporting.aol.com/v4/index.html#/.

To generate data you will need two basic things:

  • Report id: from the API response, the id of the report that you will be using
  • Report parameters: these will define the filters on your report including the desired time range, organization id, and any other filters that are configured for the report
4

Update report

Send a HTML PUT request to https://api.onereporting.aol.com/v4/report-management/report with updated body, that contains all required fields including id of the template and each of the existing blocks.

Example:

{
  "id": "01234567890abcdef",
  "name": "Pawel's Report - updated",
  "platformAlias": "O2",
  "createdOn": 1512404503050,
  "archived": false,
  "shared": false,
  "mainFilter": "publisherCompanyWithAffiliates",
  "blocks": [
    {
      "id": "01234567890abcdef",
      "title": "Report Section 1",
      "blockType": "TABLE",
      "withTotal": false,
      "metrics": [
        "billableImpressions"
      ],
      "dimensions": [
        "adCampaignId"
      ],
      "order": [
        {
          "columnId": "billableImpressions",
          "direction": "DESC"
        }
      ],
      "trendingTimeOption": "NONE",
      "forecasting": false
    }
  ]
}

Report ID

To use the Analytics Reports API, you will need to know the relevant Report ID.  There are a few ways to get it:

1) You can use the reporting API to get a list of possible reports: https://api.onereporting.aol.com/v4/index.html#!/report/list 

2) When you edit a report, the report id will be listed in the deep link 

3) When you view a report, the report id will be listed as the "first" id in the deep link

Report Parameters

Each report has a set of "parameters". These parameters correspond to filters on the Analytics Reports user interface:

Reports API_1 How_to_Use_the_Public_Reporting_API, Report_Parameters, FilterAndRefine.png

There are two ways to see all the filters / parameters and their potential values:

  1. Deep link on Analytics Reports UI: Whenever you run a report, it will generate a deep link with the reporting parameters attached.  You can use these same parameters with our reporting API.
    1. Sample deep link:https://one.aol.com/publisher/reporting/index.html#/report/59a570d1159c350001f55b89?sd=2017-09-19T00&ed=2017-09-20T00&tz=US%2FEastern&ocOrgId=7878062793
    2. Report template id: 59a570d1159c350001f55b89
    3. Start date parameter: sd=2017-09-19T00
    4. End date parameter: ed=2017-09-20T00
    5. Timezone parameter: tz=US%2FEastern
    6. Organization id parameter: ocOrgId=7878062793
  2. GET request for report template id: You can issue a GET request with the report template id.  This will return information about the contents of the report as well as all parameters.
    1. Here's the structure of the parameters section:  "parameters": [ { "id": "string", "optional": true, "defaultValue": "string" } ] 
    2. You get the id of each parameter
    3. Whether or not that parameter is mandatory or optional
    4. Any default values assigned to that parameter (e.g. reports will default to yesterday as the date range)

Now that you know the parameters and structure of them, you are ready to go and run your report with POST report task

  • If all parameters in your report have default values (based on your GET request), then you can make a POST request with just the report template id (and our API will fetch data with those defaults)
  • If some parameters do NOT have defaults OR if you wish to override those defaults, you will need to provide all mandatory parameters in your POST request along with the report template id.