Resource creation and relationships

This guide describes each of the Waze Ads resources, how they're related conceptually, and the correct order to follow when you create them.

Waze Ads resources

The following list provides definitions of the main Waze Ads resources.

Objective: Understand the main Waze Ads resources at a high level.

Account

Waze Ads Account resources are the foundation of the Ads resources. An Account encapsulates all other user-editable Waze Ads resources, namely Ad, BudgetPlan, Location, Region, Campaign, RoleAssignment, and Invitation instances.

• Create one Account for each business you want to advertise. If you're a reseller, create many Account resources. If you run a single business with multiple stores, you can use a single Account and associate all of the Location instances with that Account.
• All Location resources associated with an Account must be in the same region specified by the Account.advertisingRegionCode.
• You must specify a single Account.Category for each Account. If you have businesses in different categories, create separate Account instances for each of them.
• Reports generated from the accounts.generateReport method can only include data from a single Account.
• RoleAssignment resources determine the role, such as VIEWER or EDITOR, that a user has for a specific Account.
• Invitation resources invite a user to obtain a role over a specific Account.

Note: To create an account, follow our quickstart guide.

Ad

Ad resources associate the call-to-action (CTA), ad text, and images. They determine the visual presentation and the behavior of an ad.

Budget Plan

The BudgetPlan specifies the budget over a period of time that can be used for a Campaign.

Location

Location instances contain a pair of coordinates (longitude and latitude) along with metadata about the Location, such as a business name. When you create a Location, it's scoped under an Account. Location resources are necessary in order to serve the ads. They're the first layer of targeting and determine where the ads are eligible to serve.

Region

Region instances contain a reference to a geographicalRegion polygon along with metadata about the Region, such as a business name and phone number. When you create a Region, it's scoped under an Account.

Campaign

The Campaign resources connect Location and Ad instances, and they associate a BudgetPlan. Campaign resources enable the ads to be served.

See limits and quotas for details on the maximum number of resources that can be created within an account.

Waze API: Resource Creation Dependency flow

The following steps guide you through the resource order of creation:

1. Create an Account. Upon creation, a RoleAssignment is automatically created with your email, name, and the EDITOR Role, which grants you read and write permissions over the new Account.
2. Create the BudgetPlan, Ad, and Location resources in any order. Each resource is associated with the Account.
3. Finally, create the Campaign resources and associate them with the Account, a single Ad, and a single BudgetPlan. Campaign instances can be created without a Location. However, to serve ads, they must target at least one Location.

The following image displays the Resource Creation Dependency flow:

Create a Campaign

Waze Ads Campaign resources are created within the scope or context of a Waze Ads Account. A Campaign targets either a specific location or all Location instances. (You can target up to 50 specific Location instances.) Multiple Campaign resources can share the same set of Location instances, but each Campaign can only hold one type of ad unit, such as Pin, Takeover, Arrow, or Search.