AdWords UI vs. APIHow AdWords UI maps into AdWords API

Timo

Agenda

● Introduction - The AdWords API

● The Basics - Campaigns, Ads, …

● Reporting - Programmatic Data Insights

IntroductionThe AdWords API

UI vs. API

● UI = User Interface○ Interface for humans interacting with a service○ Interaction: Clicks, text input, …○ Delivery: Browser / HTML, Native UI, …

● API = Application Programming Interface○ Interface for applications interacting with a service○ Interaction: Method calls, SOAP messages, … ○ Delivery: Client library, web services, …

How does this apply to AdWords?

AdWords AdWords UI

API

AdWords API

AdWords Application User

AdWords Editor

?3rd Party

Application

The BasicsCampaigns, Ads, ...

UI

Authentication

● Authentication done via Google Account Manager

● Single Sign On using browser cookies

API

api.adwords.refreshToken=INSERT_REFERSH_TOKEN_HEREapi.adwords.clientId=INSERT_CLIENT_ID_HEREapi.adwords.clientSecret=INSERT_CLIENT_SECRET_HEREapi.adwords.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Authentication cont.

● Authentication Mechanism: OAuth 2○ Generate RefreshToken using client

credentials GetRefreshToken.java

○ Store all in properties / ini / config file

○ Client library will take care of the rest during startup

API

UI

AdWords Objects

● AdWords consists of several logical objects (Campaigns, Ad Groups, Ads, …)

● Basic objects represented by tabs in UI

UI

Main AdWords Objects

● Account: AdWords Customer

● Campaign: Ad Groups that logically belong together (defines budget)

● Ad Groups: Contains similar ads, all triggered by the same set of keywords

● Ad (a.k.a. AdGroupAd): Content shown when ad is displayed (Text, Image, …)

UI

Main AdWords Objects cont.Account

Campaign Campaign

Ad Group Ad Group

Ad

Online Electronics Store

TVs Cameras

Plasma TVs TFT TVs

Buy test best Plasme TVs at our store!Out now: The 2015

Plasma TV series!

AdKeyword

buy plasma TVKeyword

lastest plasma TVsKeyword

plasma tv store

Campaign

Phones

API

Objects, Services & Operations

● General Rule: One service for each object○ get Retrieve object, specified by Selector○ query Like get, but specified by AWQL○ mutate Alter objects, depending on operator

■ ADD Creates a new object■ SET Updates an object■ REMOVE Deletes an object

API

Generic Example

AdWordsSession session = [...]AdWordsServices services = [...]

XYServiceInterface service = services.get(session, XYServiceInterface.class);

Selector selector = new Selector();selector.setFields(new String[] {"Id", "Name"});

XYPage page = service.get(selector);

for (XY object : page.getEntries()) {

System.out.println(object.getId() + " - " + object.getName());

} API

“Root” objects for API interaction

Create the service

Specify what you want:- Fields- Conditions- Limits- ...

Retrieve the data

Browse through the dataNote: Only selected fields will return values!

API

Generic Example

AdWordsSession session = [...]AdWordsServices services = [...]

CampaignServiceInterface service = services.get(session, CampaignServiceInterface.class);

Selector selector = new Selector();selector.setFields(new String[] {"Id", "Name"});

CampaignPage page = service.get(selector);

for (Campaign object : page.getEntries()) {

System.out.println(object.getId() + " - " + object.getName());

} API

Selector selector = new SelectorBuilder() .fields("Id", "Name").build()

Syntactic Sugar

API

Some Campaign Data Services

API

CampaignService

AdGroupService AdGroupAdService

CampaignCriterionService

Ad Extensions

● UI: All extensions bundled in one tab (GMB for locations)

● V201409: Feed Services Old :(

○ Define generic feed, add items,map structure, associate with campaign

● V201502: Dedicated Services New!

○ Create extension feed items and add to ad group / campaign / customer

API

Ad Extensions Example

AdWordsSession session = [...]AdWordsServices services = [...]CampaignExtensionSettingServiceInterface service = [...]

SitelinkFeedItem sitelink = new SitelinkFeedItem();sitelink.setSitelinkText("Store Hours");sitelink.setSitelinkFinalUrls(new UrlList(new String[] {"http://www.example.com/storehours"}));

CampaignExtensionSetting campaignExtSetting = new CampaignExtensionSetting();campaignExtSetting.setCampaignId(campaignId);campaignExtSetting.setExtensionType(FeedType.SITELINK);

API

API

Ad Extensions Example cont.

ExtensionSetting extSetting = new ExtensionSetting();extSetting.setExtensions( new ExtensionFeedItem[] {sitelink});campaignExtSetting.setExtensionSetting(extSetting);

CampaignExtensionSettingOperation op = new CampaignExtensionSettingOperation();op.setOperand(campaignExtSetting);op.setOperator(Operator.ADD);

CampaignExtensionSettingReturnValue returnValue = service.mutate( new CampaignExtensionSettingOperation[] {op});

API

ReportingProgrammatic Data Insights

UI

AdWords Dashboard

UI

UI

Embedded Reports

UI

● UI integrates reporting & management

● Chart shows metrics over time○ Customizable metrics○ Filters for date ranges, object attributes…

● Table shows metrics grouped by objects○ Customizable columns○ Filters from charts○ Download as CSV, XML, PDF, ... file

UI

Reporting vs. Management

UI

Download

Customization

API

Reporting with the API

● Reports through ReportDownloader*○ Download as stream / file, same as through UI○ Define report type, columns, filters, format, etc.

using ReportDefinition○ Alternative: AWQL

* Slightly different in other languages

API

Reporting Example

Selector selector = new Selector();selector.getFields().addAll(Lists.newArrayList( "CampaignId", "Impressions", "Clicks"));

ReportDefinition rd = new ReportDefinition();rd.setSelector(selector);rd.setReportName("Test Report");rd.setDateRangeType(ReportDefinitionDateRangeType.LAST_30_DAYS);rd.setReportType(ReportDefinitionReportType.CAMPAIGN_PERFORMANCE_REPORT);rd.setDownloadFormat(DownloadFormat.CSV);rd.setIncludeZeroImpressions(false);

ReportDownloadResponse response = new ReportDownloader(session).downloadReport(rd);

Streams.copy(response.getInputStream(), System.out); API

API

API

Reporting Example cont.

"Test (Feb 2, 2015-Mar 3, 2015)"Campaign ID,Impressions,Clicks225151578,120310,869225381138,2284,10Total,122594,879

API

API

API

Reporting Example / AWQL

String query = "SELECT CampaignId, Impressions, Clicks" + " FROM CAMPAIGN_PERFORMANCE_REPORT" + + " WHERE Impressions > 0" + " DURING LAST_30_DAYS";

ReportDownloadResponse response = new ReportDownloader(session).downloadReport(query, DownloadFormat.CSV);

Streams.copy(response.getInputStream(), System.out);

API

API

API

API Reporting Mappings

API

API

UI API Example

Columns fields selector.getFields().add("Name");

Date Range dateRange reportDefinition.setDateRangeType( ReportDefinitionDateRangeType.LAST_30_DAYS);

Filters predicates Predicate p = new Predicate();p.setField("Impressions");p.setOperator(PredicateOperator.GREATER_THAN);p.getValues().add("3000");

Download Formats downloadFormat reportDefinition.setDownloadFormat( DownloadFormat.CSV);

API

API Reporting Mappings cont.

API

UI API Example

Segmentation (defined by fields)

Ordering Not supported

Pagination Not supported

Schedule Reports Not supported

Email Reports Not supported

API

API

Reports Types

API

CAMPAIGN_PERFORMANCE_REPORT

ADGROUP_PERFORMANCE_REPORT

Full list @ http://goo.gl/HlGePj

Resources● AdWords Help http://goo.gl/1pxGGu● API Developers Guide http://goo.gl/Q8rgGL● UI Report Mapping http://goo.gl/vEvULv