Method: accounts.generateReport

Fetch metrics for Waze Ads campaigns.

The reporting guide provides example queries and describes the basics of using generateReport.

Note that data from this method may be as much as 12 hours old, so recent metrics and changes to resources are not reflected in the reports.

HTTP request

POST https://ads.wazeapis.com/v1/{account=accounts/*}:generateReport

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
account

string

Required. The resource name of the account.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  },
  "fields": [
    string
  ],
  "pageSize": integer,
  "pageToken": string,
  "order": [
    {
      object (Order)
    }
  ],
  "filters": [
    {
      object (Filter)
    }
  ]
}
Fields
startDate

object (Date)

Required. First date to include in the report.
endDate

object (Date)

Required. Last date to include in the report.
fields[]

string

Required. Fields to include in the report. In the response, rows are grouped by all fields, except those which start with the prefix metric.. The following values are supported:

  • ad.name: A string of the form accounts/{account_id}/ads/{ad_id}.
  • ad.standardBanner.title
  • ad.standardBanner.description
  • ad.title
  • ad.type
  • budgetPlan.name: A string of the form accounts/{account_id}/budgetPlans/{budgetplan_id}.
  • budgetPlan.type
  • campaign.name: A string of the form accounts/{account_id}/campaigns/{campaign_id}.
  • campaign.cpmBid
  • campaign.state
  • campaign.title
  • campaign.type
  • location.additionalInfo
  • location.address
  • location.name: A string of the form accounts/{account_id}/locations/{locationId}.
  • location.latLng.longitude
  • location.latLng.latitude
  • location.locality
  • location.state
  • location.title
  • region.additionalInfo
  • region.name: A string of the form accounts/{account_id}/regions/{region_id}.
  • region.state
  • region.title
  • region.geographicalRegion.administrativeAreaTitle
  • region.geographicalRegion.name
  • region.geographicalRegion.regionCode
  • region.geographicalRegion.type
  • metric.adClickCount: The number of clicks on pins or search results. This metric is zero for TAKEOVER campaigns because they are displayed automatically without a click from the user. See this help center article for details.
  • metric.approxUniqueWazeDriversImpressionCount: The approximate number of unique impressions. When this metric is included in generateReport request, day must also be included and the only other permitted fields are those with the prefix metric.
  • metric.callAndUrlClickCount: The number of phone calls and website visits from the ad.
  • metric.costMicros: The cost accrued for the given row in micro currency units for the currency set on the account. For example, if the account currency is USD, then 1,000,000 is one US dollar. This metric includes capping, but not discounts.
  • metric.ctr: Click-through rate, metric.adClickCount/metric.impressionCount. 0 if metric.impressionCount is 0.
  • metric.deepLinkClickCount: the number of clicks on the deep link button from the location profile. The API doesn't allow you to create ads with deep links.
  • metric.engagementCount: The total number of interactions with the ad. This includes navigations, info button clicks, calls, and website visits for the row. See this help center article for details.
  • metric.favoriteBrandAddClickCount: The number of times a Waze driver has added the brand to their favorites.
  • metric.favoriteBrandRemoveClickCount: The number of times a Waze driver has removed the brand from their favorites.
  • metric.impressionCount: The number of impressions for the row.
  • metric.inboxClickCount: The number of times the main actions in inbox messages were clicked.
  • metric.inboxImpressionCount: The number of times inbox messages were viewed.
  • metric.inboxReminderClickCount: The number of times the main actions in inbox reminder messages were clicked.
  • metric.inboxReminderImpressionCount: The number of times inbox reminder messages were viewed.
  • metric.locationSaveClickCount: The number of times Waze drivers saved the location to their history list.
  • metric.moreInfoClickCount: The number of clicks on the info "i" button.
  • metric.navigationCount: The number of navigations for the row.
  • metric.navigationDirectCount: The number of navigations initiated directly from the ad and location profile.
  • metric.navigationHistoryCount: The number of navigations from a driver's history list. Locations are saved to the driver's history list when the driver navigates or chooses "save location."
  • metric.profileUriClickCount: The number of website visits from the location profile.
  • deviceOs: The operating system the Waze Driver uses. The following values are supported:
    • ANDROID includes both Android mobile phones and Android Auto
    • IOS includes both iPhone and CarPlay
    • UNKNOWN
  • deviceType: The type of device the Waze Driver uses. The following values are supported:
    • MOBILE_PHONE
    • IN_CAR this includes Android Auto, CarPlay and SmartDeviceLink. See this help center article for details of SmartDeviceLink.
    • UNKNOWN
  • date: The date that ads were shown to Waze drivers, in the format YYYY-MM-DD. The time zone of the location is used to determine this date.
  • week: The week that ads were shown to Waze drivers, in the format YYYY-MM-DD. Monday is the first date of the week, so 2020-02-24 represents the whole week from Monday 2020-02-24 to Sunday 2020-03-01 inclusive. The time zone of the location is used to determine the week.
  • month: The month that ads were shown to Waze drivers, in the format YYYY-MM-01. The time zone of the location is used to determine the month.
  • year: The year that ads were shown to Waze drivers, in the format YYYY-01-01. The time zone of the location is used to determine the year. The fields string can support at most one of the Time Grouping Fields date, week, month or year value.
pageSize

integer

The maximum number of rows to return. The service might return fewer than this value. If unspecified, at most 50 rows are returned. The maximum value is 1000; values above 1000 are coerced to 1000.
pageToken

string

A page token, received from a previous accounts.generateReport call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to accounts.generateReport must match the call that provided the page token.

The token will expire and is not guaranteed to work indefinitely.
order[]

object (Order)

The fields that the rows in the report are to be sorted by.
filters[]

object (Filter)

Filters to only include rows that meet specific conditions in the report. Only rows that match all of the filters in the request are returned in the response.

Response body

If successful, the response body contains data with the following structure:

JSON representation 
{
  "headers": [
    string
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "nextPageToken": string,
  "totalSize": string
}
Fields
headers[]

string

Headers that are included in the report. These match the fields in the request.
rows[]

object (Row)

Values for each of the headers for each of the groupings.
nextPageToken

string

A token that can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.
totalSize

string (int64 format)

The total number of rows of the response across all pages.

If a filter was included in the request this reflects the total number of rows after filtering.

Order

How to order the rows of the report. Consider the following:

order: {
  sort: "ASC"
  field: "date"
}

In this example the rows of the report are sorted in ascending order according to the date values.

JSON representation 
{
  "sort": enum (Sort),
  "field": string
}
Fields
sort

enum (Sort)

Determines whether the sort is ascending or descending.
field

string

The field to sort by. Only fields that appear in the request fields field can be set here.

Sort

Enums
SORT_UNSPECIFIED
ASC Sort by ascending order.
DESC Sort by descending order.

Filter

Conditions for which rows to include in the report. For example:

  • Include only rows where metric.impressionCount is larger than 100:
filters: {
  field: "metric.impressionCount"
  operator: "GREATER_THAN"
  value: "100"
}
  • Include only rows where the campaign.name is "accounts/123/campaigns/456" or "accounts/123/campaigns/457".
filters: {
  field: "campaign.name"
  operator: "IN"
  values: [
    "accounts/123/campaigns/456",
    "accounts/123/campaigns/457"
  ]
}
JSON representation 
{
  "operator": enum (Operator),
  "value": string,
  "values": [
    string
  ],
  "field": string
}
Fields
operator

enum (Operator)

Filtering behavior.
value

string

Value to use for filtering. Required for all operator values except IN and NOT_IN.
values[]

string

Values to use for filtering. Required when the operator is set to IN or NOT_IN.
field

string

A field that appears in the request fields on which to filter.

Operator

Operators that can be used to specify conditions when generating a report.

Enums
OPERATOR_UNSPECIFIED Operator unspecified.
EQUAL The field is equal to the stated value.
NOT_EQUAL_TO The field is not equal to the stated value.
GREATER_THAN The field is greater than the stated value.
GREATER_THAN_OR_EQUAL_TO The field is greater than or equal to the stated value.
LESS_THAN The field is less than the stated value.
LESS_THAN_OR_EQUAL_TO The field is less than or equal to the stated value.
HAS_SUBSTRING The string field contains the specified substring.
NOT_HAS_SUBSTRING The string field does not contain the specified substring.
IN The field is in the array of values.
NOT_IN The field is not in the array of values.

Row

JSON representation 
{
  "values": [
    string
  ],
  "privacyThresholdApplied": boolean
}
Fields
values[]

string

A value that corresponds to each of the headers. The name of enum values are printed, such as TAKEOVER. Integers are printed without comma separators, such as 1000000. Doubles are printed to four decimal places, such as 42.1412. Bool values are printed as true or false.
privacyThresholdApplied

boolean

A boolean indicating whether or not the metric values in the row were omitted due to the number of impressions for this row not meeting the minimum privacy threshold. The reporting guide provides more information.