Google Ads API Workshop – Spring 2019 – AdWords API vs Google Ads API

Google Ads API Workshop – Spring 2019 – AdWords API vs  Google Ads API


JOSH RADCLIFFE: All right, yes. Hi, I’m Josh Radcliffe. I’m a developer programs
engineer out of the New York office, and I am your last– like Cory was the last one
before you got to eat lunch, I’m your last one before
we go on to trivia. And what I’m going
to cover is just a comparison between the AdWords
API and the Google Ads API. So this presentation will
cover API differences, both in terms of
technical differences and functional
differences that you’ll want to keep in mind as
you’re either adopting the API or migrating from
the AdWords API. Then I’ll walk you
through an example where we do the campaign
lifecycle– adding a campaign, updating it, removing it, and
reporting example as well. And then finally, I’ll
touch on some logging and troubleshooting tips that
may help, especially as you’re getting up to speed on the API. And then we’ll have our– the same resources that
you’ve seen before, but a Q&A session at the end. OK, let’s go into the technical
and functional differences between the two APIs. So as you’ve heard
throughout the day, the Google Ads API is– in terms of the transport,
you have two options. You have a REST
API, like REST JSON, which is REST over HTTP
1.1 for the transport, or gRPC over HTTP 2,
and versus the average API was a good, old fashioned
SOAP API over HTTP 1.1. And then as far as
encoding, with AdWords API, you had XML based encoding,
self-describing, very verbose. With the Google Ads
API, you’re either using JSON or the binary
protocol buffer format on the wire. And then, what I think is the
most important point here, is new feature availability. So I’ve done a couple
of these workshops, and we often hear folks who want
to see features that they see in the UI available in the API. With the AdWords API, we were
somewhat limited in our ability to add new things
between releases. With the new API, we can
make additions pretty much at any time. Removing things– we’ll
still have to let all of you know and release a new
version of the API, but additions are far easier. OK, let’s go over some
key functional differences between the two APIs. With the AdWords API, we had
the AdWords Query Language, or AWQL, as it was
sometimes known, which you could use
to issue your request to retrieve objects
and reporting data, whereas in the Google Ads API,
we have the new Google Ads Query Language. And in case it hasn’t been
emphasized enough yet today, it’s a SQL-like language,
but it is not SQL. But it’s actually
simpler in a lot of ways, and we’ll go into that in some
detail a little bit later on. And then with reporting, you
had, with the AdWords API, a separate reporting
endpoint that you would hit to get report data. And you could either
send those requests using AdWords Query Language
or an XML-based selector. And then we had a fixed
set of report types with a fixed set of
fields that you could use. With the Google Ads API, you’re
using the Google Ads Query Language, and you’re
using this one service– the Google Ads service
has a search method, and that’s how you retrieve
everything with the Google Ads API. And where that really
becomes powerful is when you’re reading your
data out of the two APIs. With the AdWords API, you
would retrieve your objects through the services. So for example, campaign
service– if you wanted a full-fledged object, you
used the campaign service and call it to get
or query methods, but you could not get
any metrics or segments or anything. It was just the
objects themselves; whereas with the Google Ads API,
that Google Ads Query Language string you pass to
the search method can include things like
metrics and segments, and filtering on metrics
and segments, and limiting, and all sorts of interesting
things you can do with that. And so that really
is a much more powerful, expressive way
to retrieve your objects with the new API. And you’re getting objects back. You’re not getting just
comma-separated values. You’re actually getting
the same objects you use to manage your account. So you’re not getting
the ID of a campaign, you’re getting a campaign
object with attributes like the full structure. And then for mutates– the mutates have not
changed drastically, really. If you’re familiar
with the AdWords API, it will feel very
similar to you. If you’re not, the basic
idea is you construct a list of operations,
you attach an object to each of those operations,
and you pass that into the mutate method. And then finally, with
the client libraries, the client libraries for AdWords
API were SOAP, obviously. It’s really the only choice. But the Google Ads API– they’re using gRPC. There is the REST JSON endpoint,
but the client libraries use the gRPC transport. So let’s go through a
walkthrough of a basic campaign lifecycle between the two APIs. So the first thing you
might do is add a campaign. And in this example,
you can see that– I mentioned we’re creating
a list of operations. In this case, it
happens to just be one. But we’re specifying the
operator and the operand, which is like the campaign
object that we’re passing in. One thing for people who
are using Python and Ruby– this happens to be Python. You can see there’s a
lot of strings here. You really have to know
the names of all the fields that you want to– all the attributes that you
want to set on the campaign. It’s easy to make
mistakes, right? With the Google Ads API,
here’s the same process using the Python library again. And one thing is, if you’re
familiar with the field names from the old API,
you just basically have to mentally convert the
case into snake case instead of camel case, but they’ll
all be very familiar to you. Status, advertising
channel type– it’s all the same stuff. There are a few exceptions where
we renamed things for clarity, like the campaign_budget here
used to just be called budget. That was a little vague,
so we fixed that here. And then another key difference
is– on the previous example, if I go back just
one moment, you’ll see the budget ID was actually
just like a long number, the budget ID; whereas,
in the new API, the campaign budget is
going to be the resource name of the budget that you
want to use with that campaign. So once you’ve added
a campaign, you can retrieve them
using both APIs. With the AdWords API– here we have an AdWords
Query Language query. You could also do this using
a selector with essentially the same attributes. But we’re a little limited here. You can see all
we’re able to select are the attributes
of a campaign, nothing about its
performance metrics. And the limit clause,
in my personal opinion, is a little confusing, probably
not immediately apparent what LIMIT 0, 200 means;
whereas, with the Google Ads API, a couple of things stand
out, aside from this mosquito. You can select not just
the same attributes that we are selecting
of the campaign, like the ID, the
name, and the status, but you can also get the clicks,
like performance metrics. So just clicks,
and you can filter by those clicks
and order by them and even limit your results. So what this query
is saying is, give me all of my enabled campaigns
with less than 50 clicks over the last seven days,
and limit that and order it by ascending clicks, so
the lowest ones first, and just give me the first 10. So pretty much all of
that was not possible with the AdWords API,
except for the part about being able to select
attributes and by status. So it’s a much
more expressive way to retrieve your objects
with the new one. All right, so the
next part we’ll cover is updating a campaign
with the Google Ads API. You can see with the AdWords
API, the paradigm you had was, again, we have these operators,
or operations with an operator and an operand. You also had to construct a
campaign object when you wanted to do this set, and we’re
setting the ID and the status to paused. With the Google Ads
API, updating it looks somewhat similar. One thing about updates
in the Google Ads API is that we have this
concept of a field mask, or an update mask. And what that
allows you to do is to specify which attributes of
an object you want to update. So if you send in a campaign,
it has lots of attributes. Like let’s say this campaign
we have actually retrieved from the Google Ads
service, it could have a name and advertising
channel type, budget, all sorts of stuff. But we just want to
update the status. You can be very explicit about
that in your update requests or update operations
with the Google Ads API, and that’s what’s highlighted
with the update mask there. So each client
library has utilities so that you should not have
to construct these update masks yourself. But the basic idea is that
if you clone the object, you can pass the original
and the updated one into this utility. It’ll produce this field mask. You can pretty much treat
it like a black box. It should just do what you want. And finally, with
removing campaigns, there are some slight
differences and improvements. Again, with remove,
you see again we’re constructing a campaign, setting
its ID, setting its status. And also, it’s a little– there were some inconsistencies
in the AdWords API how you removed objects. It varied by type. Some of them did set operation. Some of them did remove. So that was the
paradigm we had there. With the Google Ads API, it’s
much more straightforward. You do not need to construct a
campaign just like a campaign object in order to remove it. You just construct an operation
and set its remove attribute to the resource name of that
campaign and pass that in. And then also, the
inconsistency about how you remove each type– we’re avoiding that
with the Google Ads API, like this is the approach
you’ll use across [INAUDIBLE].. So now that we’ve gone through
an object management lifecycle, let’s take a look at reporting. So some key differences in
reporting between the two APIs– with the AdWords
API, the resources you’d use with reports
were report types, and examples include the
keyword performance_report, the
search_query_performance_report. So these were
canned report types with a specific set
of fields that you could select with that report. On the Google Ads API, you
query for metrics and segments from mutable resources,
like campaign or ad groups or ad group ad. And then we also
have the concept of views, which are immutable
resources that exist primarily for retrieving
performance stats. So examples of that– actually, I’ll go
through some examples of that in the next slide. And then the next one,
operating on results– this is where the
Google Ads API really shines, I think, in
comparison to the AdWords API, where with AdWords API you would
get– you would run reports, get IDs and raw values,
and you, the developer, would have to construct
objects and copy those IDs onto the objects, like
construct a campaign, copy the ID you got out of
a report into the campaign, update it, send it in. And you’d use a different
service for that. With the Google Ads API,
the report responses contain actual resource objects. You’re not getting
the IDs and name. You’re getting the
campaign object. And the great thing
about that is you can run a report to
retrieve data, change some attributes of
the objects you got, send those back into a
mutate, and you’re done. So hopefully that should lead
to far less coding on your part to get these updates done. And then finally, for discovery
of metadata about reports– with the AdWords API, we had
the report definition service that would tell you,
given a report type, what are all the fields
available on that report, which fields are compatible with
each other, that sort of thing. And then the Google Ads API,
we have the Google Ads field service, which provides
similar information. One thing is it’s up to you
if you want to dive deeply into Google Ads field service. We do collect all
that information and publish it within our
reference documentation. It’ll be alongside on the left. We try and make it a
little easier so you don’t have to necessarily use
that service to use the API, but there may be use
cases where having that available through
the API would be helpful. OK, and then within
the Google Ads API, there’s equivalent
reporting resources for the various reports
in the AdWords API with a few exceptions. For example, the
destination URL report is not going to be in
the Google Ads API, but destination URLs were– we stopped using
those years ago. So yeah, a couple examples here
are the campaign performance report from AdWords API. With the Google Ads
API, you would just select from the
campaign resource. Similarly, ad group
performance report becomes select from ad_group. And then the next two are views,
which I alluded to earlier. So like the keyword
performance report shows you the performance
of your campaigns from the perspective
summarized by the keywords in your account. And then the search query
performance report– that becomes the
search_term_view. That’s another read-only view. That’s where you can see things
summarized by the search terms that users used that led to
impressions in your campaign. And we do have a guide. In the migration
section, if you go to our developers’ page,
on the left, at the bottom, you’ll see Migration. If you expand that,
there’s a mapping guide that helps you map the field
names from the AdWords API to the field names in
the Google Ads API. So here’s an example of getting
keyword stats with the Google Ads API, and it highlights
some of the benefits I’ve been talking about. So you can see that
even though I’m selecting from the
keyword_view, which is really an ad_group criterion-level
resource, where it’s associated with an ad_group criterion,
you can also select attributes from campaign and ad_group. So the enclosing entities
are available for you to include in your request. And I think you’ll find
that far more attributes of those entities are available
to you within the Google Ads API queries than with
the canned report types we had in the AdWords API. And then this one’s
also using the limit of 50, which just limits the
total results set, as opposed to the– in the AdWords API did
something different. I won’t go into those
details right now. But trust me, it’s easier. And the nice thing is– so from
that query we just looked at, you can see an example
of what would come back in the response. So your response from a Google
Ads service search request is a collection of
Google Ads rows, and then each of those rows
has high level or top level attributes on it, like campaign,
ad_group, ad_group_criterion, and the keyword_view,
which is just a resource name for the keyword. Probably won’t use the resource
name or the keyword_view much. But you can see here,
even though I’m focused on a criterion-level report, I’m
getting back a campaign object and an ad_group_ object
and the ad_group_criterion. And you also have
this nested structure, which reflects the fact that the
ad_group_criterion is not just a list of values. It’s actually a
full-fledged object that you can pass
back in for mutates, which we’ll see in a sec. So here’s an example
of mutating– taking a report response
and turning around and mutating the
objects that you retrieved from that response
or in that response. And so, in this
scenario, let’s say that you want to cut all of your
bids in half, for some reason. And so we’ve issued
a report request where we’ve retrieved
a list of rows, and then this loop
on the right– what it’s doing is it’s going
through, and for each row, it’s cloning, or creating a
copy, of the ad_group_criterion on that row, and
then updating the CPC bid to half of what it was. And that’s using that
utility I mentioned earlier that will diff the two versions,
determine what you actually changed, and come up with
a field mask for you. And then you set
that on the operation that you send into the API. But again, you
won’t have to get– you shouldn’t have to get into
the details of the field mask too deeply. You can just use it. But it does allow for
more explicit updates about what your intention
is, what you actually meant to update. Finally, I’ll just quickly touch
on logging and troubleshooting. I just want to emphasize– I know Anash talked about
this a little bit earlier, but we do have logging in
all of the client libraries. It’s very similar, in
terms of configuration, as the AdWords API
client libraries. And each library and its read
me has a section that tells you how to do that configuration. So that’s very useful,
both for debugging and when you actually deploy
your systems to production. And then for
debugging, the REST API can be very useful,
primarily because it’s human-readable
requests and responses. So it’s tough to decode
protocol buffers in your head, so if you’re just
getting used to the API, you want to see how
things are structured, it’s a really useful tool
to use, the REST endpoint, and it’s pretty easy to
construct those requests using cURL or Wget. There’s lots of
options out there. And it’s also good if
you’re just playing around with queries to see maybe which
fields you can select together. Or on the off
chance where you’re trying to isolate, like, is
this an issue with time using the client library
versus the actual API, you can try it out via cURL
and just sanity check that way. So in summary, key
points here to take away are that the Google Ads API
has both REST and gRPC APIs. It’s kind of two APIs in one. And instead of
XML, Google Ads API uses Protocol
Buffer definitions. I know everyone’s going to be
very sad to see SOAP and XML go away. And then the thing I’m
very excited about, clearly, is we have a unified
model for object retrieval, reporting, and mutates. And then we have the
Google Ads Query Language, which is an improvement over
the AdWords Query Language, that simplifies things for you. And the good news
is services mostly map one-to-one from the AdWords
API to the Google Ads API. There are some
exceptions, but when we’ve made those exceptions,
we’ll make it clear. And they were made
for good reason. For example, budget
order service has now been broken out into
multiple billing services that we think will really
improve the usability of those features. But for the most part– campaign service is
still campaign service, ad group service is
still ad group service, that sort of thing. Also, mutates are largely the
same, with some improvements, just for consistency,
that I mentioned earlier. And then use logging
with the client libraries and REST for troubleshooting
to get used to the API and familiar with what’s
coming back from your requests. And finally, we’ve got
some resources here that– these are in the
PDF, so no one has to furiously copy these URLs. But the API reference
page I mentioned earlier, where we’ve summarized the
Google Ads field service output for you, that’s
where you’ll find that. In the migration
guide, we’ll have these mappings between
report types and field names. So those would be
particularly useful if you’re migrating
from the AdWords API.

Leave a Reply

Your email address will not be published. Required fields are marked *