Custom Reporting

Overview

Custom reports provide a more flexible way to get the data you need.

The flow is similar to other Gemini reports:

  1. The API is asynchronous: Upon submitting a request, a status message is received containing a request token.

  2. If the initial response status was not ‘completed’, then the client must periodically make additional requests (passing in the request token) to poll the status.

  3. Consider the data that you own and poll for downloads at reasonable intervals.

  4. Once a report has completed, the status response will contain the URL from which the report can be fetched.


Important

This is a time-limited URL and needs to be downloaded within 6 hours of the report generation.

How cubes and dimensions work

Custom reports allow you to query cubes, which are pre-defined collections of fields that define the context of your report. When you query cubes, you can choose the rollup aggregation level, apply various filters, and select which fields you would like the report to include. All fields within a cube are classified as either Fact or Dimension fields. Fact fields are effectively metrics that can be rolled up and aggregated, while dimension fields provide entity details and metadata.

You can use dimensions to request additional entity metadata that is not provided by default in the cube table. If you want attributes from a certain dimension to be included in the report then you must include the dimension’s ID field in the field list. For example, if you would like to include “Ad Landing URL” in a report from the performance_stats cube, then the “Ad ID” must also be requested along with the “Ad Landing URL” field.

Endpoint

Resource URI

https://api.gemini.yahoo.com/v2/rest/reports/custom

Submit a new job

Call: To request a new report, make a POST call to /reports/custom with a request body similar to the following:

 { "cube": "performance_stats",
"fields": [
    { "field": "Ad ID" },
    { "field": "Day" },
    { "alias": "My dummy column", "value": "" },
    { "field": "Impressions" },
    { "field": "Ad Image URL", "alias": "url" }
  ],
"filters": [
    { "field": "Advertiser ID", "operator": "=", "value": 12345 },
    { "field": "Campaign ID", "operator": "IN", "values": [10,20,30] },
    { "field": "Day", "operator": "between", "from": "2014-04-01", "to": "2014-04-30" }
  ]
}

Request JSON structure

A typical request will include the following attributes:

  • cube: A pre-defined collection of fields. The cube defines the context of your report and controls the fields you can query across. Note that all fields within a cube are classified as either Fact or Dimension fields. Fact fields are effectively metrics that can be rolled up and aggregated, while dimension fields provide entity details and metadata.

  • fields: The fields list specifies the fields the report will include. The following are guidelines for working with the fields attribute:

  • Rollup is implicitly defined by the level of the requested dimension fields. For example, if your request includes Ad ID as the lowest level, all the fact fields will be aggregated to the ad level.

  • A date field must always be included. You can select either Day, Week or Month as field values, depending on the date rollup you require.

  • The value of the “field” attribute should be the name of a field in the requested cube.

  • The optional “alias” attribute allows the field to be renamed. The value provided in the “alias” attribute is what will be displayed in the reporting header.

  • You can provide “alias” and “value” attributes and no “field” attribute if you want to add a fixed value column to the report.

  • The order of the fields in the “fields” list is significant - it determines their order in the generated report.

  • You can only ask for a named field once - requesting duplicate fields will result in an error. All alias names must also be unique and distinct from the other named fields in the report.

  • At least one ID field must always be included. It is not possible, for example, to request fact fields to be rolled up to Pricing Type.

  • If you want attributes from a certain dimension to be included in the report, then you must include the dimension’s ID field in the field list too. For example, if you would like to include “Keyword Value” in a report, then you must also request “Keyword ID”.


  • filters: The following are guidelines to working with filters:

  • Each cube has certain fields that can be used to filter the report data - refer to the cube fields section for more details.

  • “Advertiser ID” and “Day” filters are required in every report request.

  • supported filter operations are “=”, “IN” and “between”.

  • The Advertiser ID filter must always be “=”.

  • No more than 999 values can be specified in the “values” list of an “IN” operator. Note that the Campaign ID filter must always be “IN” to the above list.

  • Regardless of which date field was requested - Day, Week, or Month - you must alway filter using “Day”. The results will be displayed broken down by the date rollup level that was requested - each row in the report will show the first day of that period. For example, if Month is requested as the date rollup level, then the data will be aggregated for the month, including only the days specified by the filter. So if the Day filter is for 2014-04-02 to 2014-04-03, then the total for those two days will be reported in one row with a Month value of 2014-04-01, indicating the first day of the month.

  • Day, Week and Month values should be in ‘YYYY-MM-DD’ format.


Similar to other Gemini API reports, upon successfully submitting a job request for a custom report, the response will include a token that you will use to poll the job’s status:

{
      "errors": null,
      "response": {
      "jobId": "628cf1c0cd1c5d8a6c1765f618b7a0be34c50bc1564618",
      "status": "submitted",
      "jobResponse": null
      }
}

Selecting Response Format

Custom reports are provided in CSV format by default but you can choose to receive reports in JSON format by passing in ?reportFormat=json in the reporting job request.

Get job status

Call: To query the status of your report request, make a GET call to /reports/custom/{token}?advertiserId={advertiserId}

Response: The response would be one of the following:

  • 404 Not Found: if {token} is invalid or unknown

  • 200 (with the following fields): { “jobId”: “the report request token”, “status”: “submitted|running|failed|completed|killed”, “response”: “” }


The meaning of the possible statuses is detailed below:

Status

Description

submitted

The job is in queue but work on it has yet to commence.

running

The job is running.

failed

The job ran but unexpectedly failed.

killed

The job was killed, typically due to failure to complete in a timely manner.

completed

The job completed successfully.


When the job is completed, you will receive a URL you will use to download the report data:

 {
      "errors": null,
      "response": {
      "jobId": "628cf1c0cd1c5d8a6c1765f618b7a0be34c50bc1564618",
      "status": "completed",
      "jobResponse": "https://nads.zenfs.com/nads/reportGeneration/628cf1c0cd1c5d8a6c1765f618b7a0be34c50bc1564618.csv"
      }
}

Job response

CSV response: Reports in CSV format will consist of one header row that lists the field names as specified in the request in the order they were requested, and zero or more data rows.

JSON response: When reports are requested in JSON format, the JSON response structure would be as follows:

{ "header":
 { "cube": "cube-name-as-per-the-request"
   "fields": [
       { "fieldName": "Field name as given in the request JSON"
         "fieldType": "DIM|FACT|CONSTANT"
       },
       ...
   ]
 }
 "rows": [
   row-1-json,
   ...
   row-N-json
 ]
}

Cubes

The following cubes are available for querying using the custom reports endpoint:

performance_stats

This cube has performance stats for all levels down to the ad level. It is recommended to use this cube when querying for native ads campaign data. The cube does not include keyword level metrics. Data for both search and native campaigns is provided - you can use the “Source” field to filter for a specific channel. Note that the cube does not include any over delivery spend adjustments which are available in the adjustment_stats cube.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Ad Group ID

Dimension

Can be filtered

The ID of the ad group.

Ad ID

Dimension

Can be filtered

The ID of the ad.

Month

Dimension

Month will be represented as the first day of the month in YYYY-MM-DD’ format. Either Day, Week or Month must be queried.

Week

Dimension

Week will be represented as the first day of the week in YYYY-MM-DD’ format. This will always be Monday. Either Day, Week or Month must be queried.

Day

Dimension

Must be filtered

The date in YYYY-MM-DD format. Either Day, Week or Month must be queried.

Hour

Dimension

Can be filtered

The hour in integer format. For example, 1 means reporting stats between 1am and 2am.

Pricing Type

Dimension

Can be filtered

CPC, CPM

Source

Dimension

Can be filtered

Source=1 represents native traffic. Source=2 represents search traffic.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Post Click Conversions

Fact

The total number of post click conversions.

Post Impression Conversions

Fact

The total number of post view conversions.

Conversions

Fact

The total number of conversions, includes both post click and post view conversions. For app install campaigns the default conversion windows are 7 days post-click and 1 day post view. For website conversions the default windows are 30 days post-click and 2 days post-view.

Total Conversions

Fact

A synonym for the Conversions field (is kept for backwards compatibility).

Spend

Fact

The unadjusted spend amount. Please note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Average Position

Fact

Impression weighted average position.

Max Bid

Fact

The maximum bid value.

Call Conversion

Fact

The total number of calls received.

Ad Extn Impressions

Fact

Total impressions for which an ad extension was displayed.

Ad Extn Clicks

Fact

Total clicks on an ad extension link (rather than on the ad landing URL).

Ad Extn Conversions

Fact

Total conversions which were attributed back to an ad extension link click.

Ad Extn Spend

Fact

The spend resulting from clicking on an ad extension link.

Average CPC

Fact

The average CPC bid value.

Average CPM

Fact

The average CPM bid value.

CTR

Fact

The clickthrough rate.

Video Starts

Fact

The number of video starts.

Video Views

Fact

The number of video views.

Video 25% Complete

Fact

Number of times the video played to 25% of its length.

Video 50% Complete

Fact

Number of times the video played to 50% of its length.

Video 75% Complete

Fact

Number of times the video played to 75% of its length.

Video 100% Complete

Fact

Number of times the video played to 100% of its length.

Cost Per Video View

Fact

Average cost per video view.

Video Closed

Fact

The number of times the video was closed.

Video Skipped

Fact

The number of times the video was skipped.

Video after 30 seconds view

Fact

The number of times the video played longer than 30 seconds.

In App Post Click Conversions

Fact

Total Post Click Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to clicks made on an ad outside of the app.

In App Post View Conversions

Fact

Total Post View Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to impressions made on an ad outside of the app.

In App Post Install Conversions

Fact

Total Post Install Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to the installation made on an ad outside of the app.


Sample performance_stats cube report request:

{
   "cube": "performance_stats",
   "fields": [
       {
           "field": "Ad ID"
       },
       {
           "field": "Day"
       },
       {
           "field": "Impressions"
       },
       {
           "field": "Clicks"
       },
       {
           "field": "CTR"
       },
       {
           "field": "Ad Image URL",
           "alias": "URL"
       }
   ],
   "filters": [
       {
           "field": "Advertiser ID",
           "operator": "=",
           "value": 11610
       },
       {
           "field": "Campaign ID",
           "operator": "IN",
           "values": [
               336986136,
               336986133
           ]
       },
       {
           "field": "Day",
           "operator": "between",
           "from": "2014-09-01",
           "to": "2014-09-08"
       }
   ]
}

adjustment_stats

This cube provides performance metrics for over delivery adjustments for spend, which are not available in other cubes.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Day

Dimension

Must be filtered

The date in YYYY-MM-DD format.

Pricing Type

Dimension

Can be filtered

CPC, CPM

Source

Dimension

Can be filtered

Source=1 represents native traffic. Source=2 represents search traffic.

Is Adjustment

Dim

Can be filtered

For adjustment rows (‘Is Adjustment’ = ‘Y’) all fact values other than Spend are always blank. Pricing Type and Source values are also blank.

Adjustment Type

Dim

Can be filtered

If you request a report at Campaign ID granularity (‘Campaign ID’ is in your fields list), then you will get only campaign adjustment rows (plus unadjusted rows). If you request a report at Advertiser ID granularity (‘Advertiser ID’ is in your fields list), then you will potentially get both account adjustments (Adjustment Type = ‘Account’) and rolled up campaign adjustment (Adjustment Type = ‘Campaign’), as well as unadjusted rows (Adjustment Type = ‘None’).

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Conversions

Fact

The total number of conversions includes both post click and post view conversions.

Spend

Fact

The spend amount.

Average Position

Fact

Impression weighted average position.


Sample adjustment_stats cube report request:

{
   "cube": "adjustment_stats",
   "fields": [
       {
           "field": "Advertiser ID"
       },
       {
           "field": "Campaign ID"
       },
       {
           "field": "Source",
           "alias": "Channel"
       },
       {
           "field": "Clicks"
       },
       {
           "field": "CTR"
       },
       {
           "field": "Is Adjustment"
       },
       {
           "field": "Adjustment Type"
       },
       {
           "field": "Spend"
       }
   ],
   "filters": [
       {
           "field": "Advertiser ID",
           "operator": "=",
           "value": 929757
       },
       {
           "field": "Campaign ID",
           "operator": "IN",
           "values": [
               331195036,
               331273097
           ]
       },
       {
           "field": "Day",
           "operator": "between",
           "from": "2014-09-01",
           "to": "2014-09-08"
       }
   ]
}

keyword_stats

This cube provides standard performance metrics at all entity levels of the account down to the keyword level. Only search data is provided, and therefore the “Source” field is not available. This cube does not include any over delivery adjustments for spend. Use this for getting metrics around keyword performance. Note that the cube does not include any over delivery spend adjustments which are available in the adjustment_stats cube.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Ad Group ID

Dimension

Can be filtered

The ID of the ad group.

Ad ID

Dimension

Can be filtered

The ID of the ad.

Keyword ID

Dimension

Can be filtered

The ID of the keyword. Must be included in any query.

Destination URL

Dimension

The actual served URL post macro-expansion. Can only be requested if both Ad ID and Keyword ID are requested. Note that requesting Destination URL granularity will result in considerably longer report generation times - only request this data if you really need it.

Day

Dimension

Must be filtered

The date in YYYY-MM-DD format. Must be included in every query.

Device Type

Dimension

Smartphone, Tablet or Desktop. Note that Device Type data is only available after the field is launched. If you run it for a previous date, it will return NONE in the Device Type column.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Post Click Conversions

Fact

The total number of post click conversions.

Post Impression Conversions

Fact

The total number of post view conversions.

Conversions

Fact

The total number of conversions, includes both post click and post view conversions. For app install campaigns the default conversion windows are 7 days post-click and 1 day post view. For website conversions the default windows are 30 days post-click and 2 days post-view.

Total Conversions

Fact

A synonym for the Conversions field (is kept for backwards compatibility).

Spend

Fact

The unadjusted spend amount. Please note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Average Position

Fact

Impression weighted average position

Max Bid

Fact

Impression weighted average position.

Average CPC

Fact

The average CPC bid value.

Average CPM

Fact

The average CPM bid value.

CTR

Fact

The clickthrough rate.


Sample keyword_stats cube report request:

{
   "cube": "keyword_stats",
   "fields": [
       {
           "field": "Day"
       },
       {
           "field": "Ad Group ID"
       },
       {
           "field": "Ad ID"
       },
       {
           "field": "Keyword ID"
       },
       {
           "field": "Keyword Value",
           "alias": "Keyword"
       },
       {
           "field": "Keyword Match Type"
       },
       {
           "field": "Impressions"
       },
       {
           "field": "Clicks"
       },
       {
           "field": "Spend"
       }
   ],
   "filters": [
       {
           "field": "Advertiser ID",
           "operator": "=",
           "value": 929757
       },
       {
           "field": "Campaign ID",
           "operator": "IN",
           "values": [
               331195036,
               331273097
           ]
       },
       {
           "field": "Day",
           "operator": "between",
           "from": "2014-09-01",
           "to": "2014-09-08"
       }
   ]
}

search_stats

This cube contains keyword level performance data, and also allows querying for the search queries that triggered keywords and ads, as well as for keyword level performance by device. Note that the cube does not include any over delivery spend adjustments which are available in the adjustment_stats cube.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Ad Group ID

Dimension

Can be filtered

The ID of the ad group.

Ad ID

Dimension

Can be filtered

The ID of the ad.

Keyword id

Dimension

Can be filtered

The id of the keyword.

Delivered Match Type

Dimension

Match type set the keyword delivered on.

Search Term

Dimension

The phrase canon user search query.

Device

Dimension

Smartphone, Tablet or Desktop.

Destination URL

Dimension

The actual served URL post macro-expansion. Can only be requested if both Ad ID and Keyword ID are requested. Note that requesting Destination URL granularity will result in considerably longer report generation times - only request this data if you really need it.

Day

Dimension

Must be filtered

The date in in YYYY-MM-DD’ format. Must be included in every query.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Spend

Fact

The unadjusted spend amount. Please note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Conversions

Fact

The total number of conversions, includes both post click and post view conversions. For app install campaigns the default conversion windows are 7 days post-click and 1 day post view. For website conversions the default windows are 30 days post-click and 2 days post-view.

Post Click Conversions

Fact

The total number of post click conversions.

Post Impression Conversions

Fact

The total number of post view conversions.

Average Position

Fact

Impression weighted average position.

Max Bid

Fact

Maximum bid for the requested time interval.

Average CPC

Fact

The average CPC value.

CTR

Fact

The clickthrough rate.

Impression Share

Fact

Share of Impressions that the Advertiser or Campaign served to a given Keyword, after factoring in Targeting. For example, if Campaign X served 10 impressions to the keyword ‘basketball,’ and a total of 100 bidded searches occurred on ‘basketball’ during the time period selected, then Campaign X has an Impression Share of 10% for the term ‘basketball’.

Click Share

Fact

Share of Clicks that the Advertiser or Campaign received on a given Keyword, after factoring in Targeting. For example, if Campaign X had 10 Clicks to the keyword ‘basketball,’ and a total of 100 Clicks occurred on ‘basketball’ during the time period selected, then Campaign X has a Click Share of 10% for the term ‘basketball’

Conversion Share

Fact

Share of Conversions that the Advertiser or Campaign received on a given Keyword, after factoring in Targeting. For example, if Campaign X had 10 Conversions to the keyword ‘basketball,’ and a total of 100 Conversions occurred on ‘basketball’ during the time period selected, then Campaign X has a Conversion Share of 10% for the term ‘basketball’.


Sample search_stats cube report request:

 {
  "cube": "search_stats",
  "fields": [
      {
          "field": "Day"
      },
      {
          "field": "Keyword ID"
      },
      {
          "field": "Keyword Value",
          "alias": "Keyword"
      },
      {
          "field": "Search Term"
      },
      {
          "field": "Clicks"
      },
      {
          "field": "Conversions"
      },
      {
          "field": "Spend"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              331195036,
              331273097
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2014-09-01",
          "to": "2014-09-08"
      }
   ]
}

ad_extension_details

This cube only contains search performance data that resulted from an ad extension impression. Note that the cube does not include any over delivery spend adjustments which are available in the adjustment_stats cube. Use this for getting metrics on ad extension performance.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Ad Group ID

Dimension

Can be filtered

The ID of the ad group.

Ad ID

Dimension

Can be filtered

The ID of the ad.

Keyword ID

Dimension

Can be filtered

The ID of the keyword.

Ad Extn ID

Dimension

Can be filtered

The ID of the ad extension.

Device

Dimension

Can be filtered

Desktop, Smartphone, Tablet.

Month

Dimension

Month will be represented as the first day of the month in YYYY-MM-DD’ format.

Week

Dimension

Week will be represented as the first day of the week in YYYY-MM-DD’ format.

Day

Dimension

Must be filtered

The date in YYYY-MM-DD format.

Pricing Type

Dimension

Can be filtered

The pricing type.

Destination URL

Dimension

The actual served URL post macro-expansion. Can only be requested if both Ad ID and Keyword ID are requested. Note that requesting Destination URL granularity will result in considerably longer report generation times - only request this data if you really need it.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Conversions

Fact

The total number of conversions includes both post click and post view conversions.

Spend

Fact

The unadjusted spend amount. Please note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Average CPC

Fact

The average CPC bid value.

CTR

Fact

The clickthrough rate.


Important

The destination url in the report for a given ad extension id is not the definitive url that was served. One url is picked to be representative of the group.

Sample ad_extension_details cube report request:

{
  "cube": "ad_extension_details",
  "fields": [
      {
          "field": "Advertiser ID"
      },
      {
          "field": "Campaign ID"
      },
      {
          "field": "Ad Extn ID",
          "alias": "Ad Extension ID"
      },
      {
          "field": "Impressions"
      },
      {
          "field": "Clicks"
      },
      {
          "field": "CTR"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              331195036,
              331273097
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2014-09-01",
          "to": "2014-09-08"
      }]
 }

audience

This cube provides a breakdown of performance by various targeting attributes such as device, geo (country, city, state, DMA, zip), and gender. Data is available for all entity levels down to the ad level for both search and native campaigns. Keywords are not included. Over delivery spend adjustments are not included.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

The ID of the advertiser.

Campaign ID

Dimension

Can be filtered

The ID of the campaign.

Ad Group ID

Dimension

Can be filtered

The ID of the ad group.

Ad ID

Dimension

Can be filtered

The ID of the ad.

Audience Type

Dimension

See table below for Supported Audience ID values.

Audience ID

Dimension

See table below for Supported Audience ID values.

Day

Dimension

Must be filtered

The date in YYYY-MM-DD format.

Pricing Type

Dimension

Can be filtered

The pricing type.

Source

Dimension

Can be filtered

Source=1 represents native traffic. Source=2 represents search traffic.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Post Click Conversions

Fact

The total number of post click conversions.

Post Impression Conversions

Fact

The total number of post view conversions.

Conversions

Fact

The total number of conversions, includes both post click and post view conversions. For app install campaigns the default conversion windows are 7 days post-click and 1 day post view. For website conversions the default windows are 30 days post-click and 2 days post-view.

Total Conversions

Fact

A synonym for the Conversions field (is kept for backwards compatibility).

Spend

Fact

The unadjusted spend amount. Please note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Video Starts

Fact

The number of video starts.

Video Views

Fact

The number of video views.

Video 25% Complete

Fact

Number of times the video played to 25% of its length.

Video 50% Complete

Fact

Number of times the video played to 50% of its length.

Video 75% Complete

Fact

Number of times the video played to 75% of its length.

Video 100% Complete

Fact

Number of times the video played to 100% of its length.

Cost Per Video View

Fact

Average cost per video view.

Video Closed

Fact

The number of times the video was closed.

Video Skipped

Fact

The number of times the video was skipped.

Video after 30 seconds view

Fact

The number of times the video played longer than 30 seconds.


Supported Audience Type and Audience ID values:

Audience Type

Audience ID values

device

MOBILE, OTHER

gender

M,F,U

geo_city

A WOEID value

geo_country

A WOEID value

geo_dma

A WOEID value

geo_state

A WOEID value

geo_zip

A WOEID value


Sample audience cube report request:

{
  "cube": "audience",
  "fields": [
      {
          "field": "Advertiser ID"
      },
      {
          "field": "Campaign ID"
      },
      {
          "field": "Audience Type"
      },
      {
          "field": "Audience ID"
      },
      {
          "field": "Day"
      },
      {
          "field": "Impressions"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              331195036,
              331273097
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2014-09-01",
          "to": "2014-09-08"
      }
  ]
}

user_stats

The user_stats cube is the next iteration of the audiences _stats cube, and provides a breakdown across various targeting attributes, such as age, gender, device, geo (country, state, dma, city, zip), both for the physical location of the user and the location of his or her interest.

Field

Type

Attributes

Description

Advertiser ID

Dimension

Must be filtered

ID of the advertiser.

Campaign ID

Dimension

Can be filtered

ID of the campaign.

Ad Group ID

Dimension

Can be filtered

ID of the ad group.

Day

Dimension

Must be filtered

The date in in YYYY-MM-DD format.

Pricing Type

Dimension

Can be filtered

The pricing type.

Source

Dimension

Can be filtered

Source=1 represents native traffic. Source=2 represents search traffic.

Gender

Dimension

Can be filtered

The gender of the user: F, M, or U.

Age

Dimension

Can be filtered

Age group of the user: 18-24, 25-34, 35-44, 45-54, 55-64.

Device

Dimension

Can be filtered

Device of the user: Desktop, Tablet, Phone, Unknown.

Country

Dimension

Can be filtered

Name of the user’s country.

State

Dimension

Can be filtered

Name of the user’s state.

City

Dimension

Can be filtered

Name of the user’s City.

Zip

Dimension

Can be filtered

Zip code of the user.

DMA WOEID

Dimension

Can be filtered

The Where on Earth ID associated with the DMA.

City WOEID

Dimension

Can be filtered

The Where on Earth ID associated with the City.

State WOEID

Dimension

Can be filtered

The Where on Earth ID associated with the State.

Zip WOEID

Dimension

Can be filtered

The Where on Earth ID associated with the Zip Code.

Country WOEID

Dimension

Can be filtered

The Where on Earth ID associated with the Country.

Location Type

Dimension

Can be filtered

Flags whether the location listed in the report indicates the physical location of the user or the location of their intent (for Search).

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Post Click Conversions

Fact

The total number of post click conversions.

Post Impression Conversions

Fact

The total number of post view conversions.

Conversions

Fact

The total number of conversions, which includes both post click and post view conversions. For app install campaigns, the default conversion windows are 7 days post-click and 1 day post view. For website conversions, the default windows are 30 days post-click and 2 days post-view.

Total Conversions

Fact

A synonym for the Conversions field (maintained for backwards compatibility).

Spend

Fact

The unadjusted spend amount. Note that adjustments - meaning any corrections due to issues like overcharging - can be queried using the adjustment_stats cube.

Reblogs

Derived Fact

The count of Tumblr Reblogs.

Reblog Rate

Derived Fact

The rate of Tumblr Reblogs (over Impressions).

Likes

Derived Fact

The count of Tumblr Likes.

Like Rate

Derived Fact

Rate of Tumblr Likes (over Impressions).

Follows

Derived Fact

The count of Tumblr Follows.

Follow Rate

Derived Fact

The rate of Tumblr Follows (over Impressions).

Engagements

Derived Fact

The count of total Tumblr Engagements.

Paid Engagements

Derived Fact

Total of revenue-bearing Impressions.

Engagement Rate

Derived Fact

The rate of total Tumblr Engagements (over Impressions).

Paid Engagement Rate

Derived Fact

The rate of revenue-bearing Engagements (over Impressions).”

Video Starts

Fact

The number of video starts.

Video Views

Fact

The number of video views.

Video 25% Complete

Fact

The number of times the video played to 25% of its length.

Video 50% Complete

Fact

The number of times the video played to 50% of its length.

Video 75% Complete

Fact

The number of times the video played to 75% of its length.

Video 100% Complete

Fact

The number of times the video played to 100% of its length.

Cost Per Video View

Fact

The average cost per video view.

Video Closed

Fact

The number of times the video was closed.

Video Skipped

Fact

The number of times the video was skipped.

Video after 30 seconds view

Fact

The number of times the video played longer than 30 seconds.

Ad Extn Impressions

Fact

Total impressions for which an ad extension was displayed.

Ad Extn Clicks

Fact

Total clicks on an ad extension link (rather than the main link).

Ad Extn Spend

Fact

Total spend associated to an ad extension.

Average Position

Fact

The average position of the ad.

Sample user_stats cube report request:

{
  "cube": "user_stats",
  "fields": [
      {
          "field": "Advertiser ID"
      },
      {
          "field": "Campaign ID"
      },
      {
          "field": "Source"
      },
      {
          "field": "Country"
      },
      {
          "field": "Device"
      },
      {
          "field": "Day"
      },
      {
          "field": "Impressions"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              331195036,
              331273097
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2015-12-01",
          "to": "2015-12-08"
      }
  ]
}

product_ads

This data is available to advertisers who are running Gemini Product Ads campaigns. Use this to get product group as well as product level reporting. Over delivery spend adjustments are not included

Field

Type

Attributes

Description

Advertiser ID

Dim

canFilterOn

ID of the advertiser.

Campaign ID

Dim

canFilterOn

ID of the shopping campaigns.

Ad Group ID

Dim

canFilterOn

ID of the ad group.

Offer ID

Dim

canFilterOn

ID of the offer, same value as the id field in the product feed. This is the merchant-side ID of the product.

Category ID

Dim

canFilterOn

ID of the product category, foreign key to the product_categories dimension.

Category Name

Dim

The name associated with the Category ID.

Device

Dimension

Smartphone, Tablet or Desktop.

Product Type

Dim

canFilterOn

The merchant’s own product category string, same value as the “product type” field in the product feed.

Brand

Dim

canFilterOn

Brand of the offer, same value as the “brand” field in the product feed.

Offer Group ID

Dim

canFilterOn

The id of the leaf product group node that won the auction.

Product ID

Dim

canFilterOn

The id of the product. This is the Yahoo-side ID given to the product.

Product Name

Dim

canFilterOn

The Name of the product.

Custom Label 0

Dim

canFilterOn

One of 5 different custom labels that can be applied to a Product.

Custom Label 1

Dim

canFilterOn

One of 5 different custom labels that can be applied to a Product.

Custom Label 2

Dim

canFilterOn

One of 5 different custom labels that can be applied to a Product.

Custom Label 3

Dim

canFilterOn

One of 5 different custom labels that can be applied to a Product.

Custom Label 4

Dim

canFilterOn

One of 5 different custom labels that can be applied to a Product.

Month

Dim

canFilterOn

Month will be represented as the first day of the month in YYYY-MM-DD’ format.

Week

Dim

canFilterOn

Week will be represented as the first day of the week in YYYY-MM-DD’ format.

Day

Dim

mustFilterOn

The date in in YYYY-MM-DD’ format.

Impressions

Fact

The number of impressions.

Clicks

Fact

The number of clicks.

Post View Conversions

Fact

The total number of post view conversions.

Post Click Conversions

Fact

The total number of post click conversions.

Total Conversions

Fact

Total number of conversions.

Spend

Fact

Total spend.

Average CPC

Fact

The average CPC value.

CTR

Fact

The clickthrough rate.


Sample product_ads cube report request:

{
  "cube": "product_ads",
  "fields": [
      {
          "field": "Advertiser ID"
      },
      {
          "field": "Campaign ID"
      },
      {
          "field": "Product Group ID"
      },
      {
          "field": "Item ID"
      },
      {
          "field": "Day"
      },
      {
          "field": "Impressions"
      },
      {
          "field": "Clicks"
      },
      {
          "field": "Average CPC"
      },
      {
          "field": "Spend"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              3311225,
              3311447
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2014-04-15",
          "to": "2014-04-16"
      }
  ]
}

conversion_rules_stats

This cube provides a breakdown of stats by conversion rules, conversion categories, and other conversion-related info. See the Conversion Rules section for more details on creating and managing conversion rules.

Field

Type

Attributes

Description

Advertiser ID

Dim

Must be filtered

The ID of the advertiser.

Campaign ID

Dim

Can be filtered

The ID of the campaign.

Ad Group ID

Dim

Can be filtered

The ID of the ad group.

Rule ID

Dimension

Can be filtered

The id associated with the conversion rule.

Rule Name

Dimension

Can be filtered

The name associated with the conversion.

Category Name

Dimension

Can be filtered

The category associated with conversion.

Conversion Device

Dimension

Can be filtered

Smartphone, Tablet or Desktop. This is the device the conversion event occurred on, and it can be different from the device associated with the impression or click. Device on other reports is the device associated with the impression, click events.

Keyword ID

Dimension

Can be filtered

The Id of the keyword. This will be blank for Native Campaigns.

Keyword Value

Dimension

The actual keyword.

Source

Dimension

Can be filtered

Source=1 represents native traffic. Source=2 represents search traffic.

Price Type

Dimension

Can be filtered

The pricy type.

Day

Dimension

Must be filtered

The date in in YYYY-MM-DD’ format. Must be included in every query.

Post View Conversions

Fact

The total number of post view conversions.

Post Click Conversions

Fact

The total number of post click conversions.

Conversion Value

Fact

The actual value associated with the conversion event.

Conversions

Fact

The total number of conversions, includes both post click and post view conversions. For app install campaigns the default conversion windows are 7 days post-click and 1 day post view. For website conversions the default windows are 30 days post-click and 2 days post-view.

In App Post Click Conversions

Fact

Total Post Click Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to clicks made on an ad outside of the app.

In App Post View Conversions

Fact

Total Post View Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to impressions made on an ad outside of the app.

In App Post Install Conversions

Fact

Total Post Install Conversions that occurred in the app after it was installed. These conversions occurred in the app, but were attributed to the installation made on an ad outside of the app.


Sample conversion_rules_stats cube report request:

{
  "cube": "conversion_rules_stats",
  "fields": [
      {
          "field": "Advertiser ID"
      },
      {
          "field": "Campaign ID"
      },
      {
          "field": "Ad Group ID"
      },
      {
          "field": "Product Group ID"
      },
      {
          "field": "Day"
      },
      {
          "field": "Rule ID"
      },
      {
          "field": "Rule Name"
      },
      {
          "field": "Conversion Device"
      },
      {
          "field": "Conversion Value"
      }
  ],
  "filters": [
      {
          "field": "Advertiser ID",
          "operator": "=",
          "value": 929757
      },
      {
          "field": "Campaign ID",
          "operator": "IN",
          "values": [
              3311225,
              3311447
          ]
      },
      {
          "field": "Day",
          "operator": "between",
          "from": "2015-05-24",
          "to": "2015-05-27"
      }
  ]
}

Dimensions

You can use dimensions to request additional entity metadata that is not provided by default in the cube tables.

If you want attributes from a certain dimension to be included in the report, then you must include the dimension’s ID field in the field list. For example, if you would like to include “Ad Landing URL” in a report from the performance_stats cube, then the “Ad ID” must also be requested along with the “Ad Landing URL” field.

The following dimensions are available for querying:

Advertiser

Name

Description

Type

Advertiser ID

The ID of the advertiser account.

long

Advertiser Name

The name of the advertiser account.

string

Advertiser Timezone

The advertiser account timezone, e.g., America/New_York.

enum

Advertiser Currency

Advertiser currency, e.g., USD

string


Campaign

Name

Description

Type

Advertiser ID

The ID of the account associated with the campaign.

long

Campaign ID

The ID of the campaign. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

Campaign Name

The name of the campaign.

string

Campaign Start Date

The start date of the campaign.

yyyy-mm-dd format

Campaign End Date

The end date of the campaign.

yyyy-mm-dd format

Campaign Status

The status of the campaign (ACTIVE, PAUSED).

enum

Budget

The lifetime budget at the campaign level.

BigDecimal

Budget Type

The type of budget.

enum

Campaign Objective

The objective of the campaign as defined in the campaign settings.

string


Ad Group

Name

Description

Type

Advertiser ID

The ID of the account associated with the ad group.

long

Campaign ID

The ID of the campaign associated with the ad group.

long

Ad Group Id

The ID of the ad group. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

Ad Group Name

The name of the ad group.

string

Ad Group Status

The status of the ad group (ACTIVE, PAUSED).

enum


Ad

Name

Description

Type

Advertiser Id

The ID of the account associated with the ad.

long

Campaign Id

The ID of the campaign associated with the ad.

long

Ad Group Id

The ID of the ad group associated with the ad.

long

Ad Id

The ID of the ad. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

Ad Title

The title of the ad that will be shown to the user.

string

Ad Description

The description of the ad that will be shown to the user. This field supports keyword insertion. Max length is 150 characters.

string

Ad SponsoredBy

The string shown against the sponsored by label in the ad.

string

Ad Landing URL

The URL where the user was redirected to upon clicking the ad.

string

Ad Display URL

The user-friendly URL that is displayed to the user.

string

Ad Image URL

The URL of the (uploaded thumbnail) image.

string


Keyword

Name

Description

Type

Keyword ID

The id of the keyword. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

Keyword Value

The keyword text.

string

Keyword Match Type

The keyword match type.

string

Keyword Status

The keyword status.

string

Keyword Param 1

The param1 value for the keyword.

string

Keyword Landing URL

The keyword landing URL.

string


Ad Extension

Name

Description

Type

Ad Extn ID

The ID of the ad extension. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

Ad Extn Type

The type of the ad extension.

enum

Ad Extn Parent Type

The parent type of the ad extension.

enum

Ad Extn Title

The title of the ad extension. Populated only for sitelinks.

string

Ad Extn Phone Number

The phone number associated with the ad extension. Applies to call extensions.

string


Geo

Name

Description

Type

WOE ID

The location ID. This is the primary key for this dimension and should be included in the report in order for other dimension attributes to be queried.

long

WOE Type

country, state, city, dma, zip

enum

WOE Name

The location Name.

string


product_categories

Name

Description

Type

Category ID

ID of the product category

long

Parent Category ID

ID of the parent product category

long

Category Name

Product category name

string

Category Path

The full category path

string