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