REST Resource: accounts.campaigns

Resource: Campaign

JSON representation
{
  "name": string,
  "title": string,
  "type": enum (Type),
  "state": enum (State),
  "targetingHours": {
    object (WeeklySchedule)
  },
  "onlyBusinessHours": boolean,
  "cpmBid": {
    object (Money)
  },
  "budgetPlan": string,
  "ads": [
    {
      object (CampaignAd)
    }
  ],
  "locations": [
    string
  ],
  "radiusMeters": string,
  "regions": [
    string
  ],
  "goal": enum (Goal),
  "createTime": string,
  "updateTime": string
}
Fields
name

string

The resource name of the campaign. Format: accounts/{account}/campaigns/{campaign}

title

string

Required. Title used to identify the campaign in the dashboard and in reports. Not visible to Waze drivers. The maximum length is 100 characters.

type

enum (Type)

Required. Immutable. The type of this campaign. The field is required on creation and can't be edited once a campaign is created. To create a SEARCH campaign there must be non-SEARCH campaigns active for the dates set in the budget plan.

state

enum (State)

Required. Determines whether the campaign is active and ads are shown to Waze drivers. You can only create campaigns in the ACTIVE or PAUSED states. This field can only be changed with the state transition methods campaigns.activate and campaigns.pause, not campaigns.patch.

targetingHours

object (WeeklySchedule)

A collection of times when this campaign serves ads. Each period represents a range of hours when ads are shown during the week in the location's time zone.

If no schedule is provided then this field doesn't apply filtering. If both onlyBusinessHours and targetingHours are specified, then ads are only shown at the intersection of targetingHours and the location's regular business hours.

Example: Show ads on Saturdays from 09:00-12:00 and 13:00-17:00:

targetingHours {
  timePeriods {
    startDay: SATURDAY
    startTime: "09:00"
    endDay: SATURDAY
    endTime: "12:00"
  }
  timePeriods {
    startDay: SATURDAY
    startTime: "13:00"
    endDay: SATURDAY
    endTime: "17:00"
  }
}

The ending time must occur after the starting time, either later in the same day, or on a subsequent day.

NOTE: Overnight hours, such as Monday 20:00 until Tuesday 02:00, are allowed on writes. On reads, they are split into multiple day components.

onlyBusinessHours

boolean

Determines whether ads are shown only when locations are open. If a location doesn't have business hours, no filtering is applied by this field. If both onlyBusinessHours and targetingHours are specified, then ads are only shown at the intersection of targetingHours and the location's regular business hours.

cpmBid

object (Money)

The Cost-Per-Thousand impressions (CPM) bid for this campaign. For more details on budget requirements, see Edit your budget. Consult your rate card for documentation on the minimum value that can be set. You should always set the minimum permitted value.

When the type is SEARCH, don't set this field.

budgetPlan

string

Required. Resource name of the budget plan to associate with this campaign. Format: accounts/{account}/budgetPlans/{budgetPlan}

ads[]

object (CampaignAd)

Required. The ads to include in this campaign.

NOTE: Currently exactly one ad must be specified for each campaign.

Permitted ads depend on the campaign type:

  • If this is a SEARCH campaign, the ad must have hideNavigation set to false.
  • If this is a TAKEOVER campaign targeting regions, the ad must be a CALL_NOW or SAVE_FOR_LATER ad with hideNavigation set to true.
locations[]

string

Resource names for the Location resources to include in the campaign. To include all active locations in the campaign, use the string accounts/{account}/locations. If providing specific locations, up to 50 locations are supported.

Format: accounts/{account}/locations/{location}

radiusMeters

string (int64 format)

Target locations that are within the specified distance from Waze drivers in kilometers. The permitted values depend on the campaign type:

  • For TAKEOVER campaigns, permitted values are 2,000, 5,000, 10,000. For all Ad types except for DRIVE_THERE, 20,000 and 50,000 are permitted as well.
  • For ARROW campaigns, permitted values are 1,000, 2,000 and 5,000.
  • This field must not be set for PIN or SEARCH campaigns. PIN campaigns are only shown when the pin can be displayed on the Waze Driver's screen.
regions[]

string

Resource names for the Region resources to include in the campaign. Regions can only be used with TAKEOVER campaigns and only CALL_NOW or SAVE_FOR_LATER ads where hideNavigation is set to true. When regions are specified, no locations can be specified. If providing specific regions, up to 50 regions are supported.

To include all active regions in the campaign, use the string accounts/{account}/regions.

Format: accounts/{account}/regions/{region}

goal

enum (Goal)

Goal of the Campaign.

createTime

string (Timestamp format)

Output only. Time when this campaign was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. Time when this campaign was most recently updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Type

Campaign type.

Enums
TYPE_UNSPECIFIED Type unspecified.
PIN Pins shown on the map. See this help center article for details of this Type.
SEARCH Locations are promoted in the search results. See this help center article for details of this Type.
TAKEOVER A pocket-sized billboard is shown when Waze drivers come to a stop. See this help center article for details of this Type.
ARROW Arrows shown on the map. See this help center article for details of this Type.

State

Campaign state.

Enums
STATE_UNSPECIFIED State unspecified.
ACTIVE The campaign is active, so ads are shown to all Waze drivers, subject to targeting.
PAUSED The campaign is paused, so ads aren't shown to Waze drivers.
COMPLETED The last endDate of the budget plan associated with this campaign is in the past. After 2021-10-19 campaigns where the end date is in the past will be returned with this state rather than ACTIVE.

CampaignAd

Ad to include in the campaign.

JSON representation
{
  "ad": string
}
Fields
ad

string

Required. Resource name of the Ad to include in the campaign. Format: accounts/{account}/ads/{ad}

Goal

Campaign goal.

Enums
GOAL_UNSPECIFIED
STORE_VISITS The primary goal of this campaign is to optimize store visits.
WEBSITE_VISITS The primary goal of this campaign is to optimize website visits.
BRAND_LOCATION_AWARENESS The primary goal of this campaign is to improve the business's location awareness.
CALLS The primary goal of this campaign is to deliver calls.

Methods

activate

Activates a campaign.

create

Creates a new campaign.

get

Returns the requested campaign.

list

Lists the campaigns from an account, ordered by name.

patch

Updates an existing campaign.

pause

Pauses a campaign.