4. 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, …
5. How does this apply to AdWords?
AdWords AdWords UI
API
AdWords API
AdWords
Application User
AdWords Editor
?3rd Party
Application
9. U
I
AdWords Objects
● AdWords consists of several logical objects
(Campaigns, Ad Groups, Ads, …)
● Basic objects represented by tabs in UI
10. U
I
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, …)
11. U
I
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!
Ad
Keyword
buy plasma TVKeyword
lastest plasma TVsKeyword
plasma tv store
Campaign
Phones
12. A
PI
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
13. A
PI
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());
} A
PI
“Root” objects for
API interaction
Create the service
Specify what you want:
- Fields
- Conditions
- Limits
- ...
Retrieve the data
Browse through the data
Note: Only selected fields
will return values!
14. A
PI
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());
} A
PI
Selector selector = new SelectorBuilder()
.fields("Id", "Name").build()
Syntactic Sugar
15. A
PI
Some Campaign Data Services
A
PI
CampaignService
AdGroupService AdGroupAdService
CampaignCriterionService
16. 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
17. A
PI
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);
A
PI
18. A
PI
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});
A
PI
21. U
I
Embedded Reports
U
I
● 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
23. A
PI
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
24. A
PI
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);
A
PI
A
PI
25. A
PI
Reporting Example cont.
"Test (Feb 2, 2015-Mar 3, 2015)"
Campaign ID,Impressions,Clicks
225151578,120310,869
225381138,2284,10
Total,122594,879
A
PI
A
PI
26. A
PI
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);
A
PI
A
PI
27. A
PI
API Reporting Mappings
A
PI
A
PI
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);
28. A
PI
API Reporting Mappings cont.
A
PI
UI API Example
Segmentation (defined by fields)
Ordering Not supported
Pagination Not supported
Schedule Reports Not supported
Email Reports Not supported
A
PI
