Off the Charts: Introduction to the Google Analytics Metadata API Video Lecture | Google Analytics: For Developers - Data & Analytics

welcome my name is Pete frazzela i'm a
developer
on the google analytics team and thanks
for coming neck guy so today we're going
to talk a little bit about the Google
Analytics metadata API how to use the
metadata API what does it mean for you
in terms of development and maybe some
products that you might be working on
and then we'll talk a little bit with
this new thing which is the data
deprecation problem the metrics
represent the numbers numerical values
and the dimensions represent the strings
or text that break down the metrics on
various criteria for example the source
and medium so the big question is for
developers is what are the dimensions
and metrics that are available that you
can use in the reporting AP is to query
for your data now take for example what
we have a tool here is a query Explorer
what we build in the query Explorer we
allow users to build different queries
to query our API and get that reporting
data that we showed earlier in the query
Explorer we have a section for people to
select dimensions for them to select
metrics when they select them we show
groups all the different dimensions and
metrics we even show descriptions now we
built this tool because we know the
product and we work on the product team
but for developers building interfaces
like this in their own product it can be
very difficult to stay on top of all
this data and so what we did is we
packaged all this data and we released
it in what we call the metadata API with
the metadata API you have access to all
this data programmatically great so
let's just take a look at what kind of
what this looks like and this is actual
response back from that date metadata
API right so we have a new endpoint
under metadata and then you provide a
report type and then the resource is
called column so when you actually visit
that URL let's back up you'll see the
actual response this is coming directly
from the server right so we have all
this is elias is live it's just came a
lot ricotta that was really fast yeah so
it comes back and we get all this great
information you just described writes
the stuff that you need to kind of build
these you
the core reporting API or other Google
reporting api's is the ID this is kind
of important part of this and it
represents the entire dimension or
metric and that's the name you actually
use when you query for the reporting
reporting data right so this is it in
this example we have average time on
site that's the ID that's the kind of
information you get back the other thing
is that we've provided all these list of
attributes that makes sense to have when
you were trying to build a UI that it's
not that you're going to need to know
and we can kind of group these into
different areas and in the first area we
all talk about is the type attributes
there's two of them here and they
provide two pieces information that are
obviously essential one is the is this a
dimension or metric which is the type
attribute that identifies that and then
we have the data type and this lets you
know for this particular dimension or
metric what is the data value that
you're getting that's been returned is
it time is it may be a percent is it
afloat integer so this is things like
that formatting exactly so you can
understand what the format of that value
is right because when you look at JSON
response these are all basically strings
for getting that right and this tells
you the actual data type for that the
next thing is that we provide is kind of
these we can just think of as like
description or you I attributes right so
you'll notice that we have these
groupings available for you and this is
stuff that we provide that the google
analytics team as kind of grouped these
different dimensions and metrics into
kind of similar groupings that that will
be helpful when you're building a UI for
example this is you can use it or not
use it but it's the help of that and
that's in the situation right so every
dimension metric is going to have this
group attribute and just to help you
with that and then we also have things
like the UI name and the app UI name so
depending on whether you are set up a
web property or an appt property I
profile there's certain dimensions and
measures that have different names the
penetrance app or web right and if there
is a particular name for an appt you I
then will they will provide this this
extra attribute as part of the response
for that particular dimension or metric
so you want to check that one year when
you're using the metadata API you want
to check the response to see if that
exists for that particular dimension or
metric and use that depending on whether
whether you're building an app or web
interface easy let me provide
description which just gives a little
description of what the actual dimension
metric is and then we provide this
additional calculation attribute again
this kit provides more information
if it is a calculated metric which some
there is a few that are tackling metrics
this will show you the actual dimensions
make sure start other metrics that we
use to actually come up with that
calculation so these are all very
helpful building out your you guys just
as you described the other thing is that
we have there is particular dimensions
and metrics that are that have these
repeated values so if you have like a
numeric index so something for example
we have custom dimensions and metrics
you'll notice they have these double X's
as part of the ID and what that means is
that there's a there's a particular
range for that that that dimension or
metric so we provide these attributes
that give you the boundary or the range
that is valid for this particular
dimension or metric and this this helped
you understand either for validation
purposes or if you want to build out a
list of dimensions and metrics that are
valid for a particular repeated value
this will this will provide those the
values that you need to know for that
and then finally we have the some
attributes that you can think of as
helping in terms of validation so we
have an allowed in segments attribute
and this just helps you identify whether
a particular dimension or metric can be
used in a reporting query as a segment
and if it if it is allowed in this this
attribute exists if not it will not
exist and again this is helpful for
validation and making sure you provide
building queries out that look that will
work properly so it's a whole bunch of
good stuff in terms of the data that we
provide it gives anything pretty much
like a a good good coverage on all the
stuff you're going to need to build out
the open API right the final thing we
will talk about here in terms of
attributes is this etag value so you'll
notice when you when you make a request
to the metadata API you'll get a
response back and they'll be an e-tag
attribute and what this is is a unique
identifier that you can use to determine
whether the response has changed since
the last time that you requested it so
if there if you make the response and
you cash at client site or server side
and then you make another request later
on if that valued matches the value you
have stored the e-tag value that means
the response has not changed this is
helpful for a few reasons one is you can
if you've maybe got a response and build
out a UI you can use the e-type to
determine if you need to update that you
I because if the value isn't changing
there's no point in updating your UI
that's going to change this last time we
requested another way you can use it is
when you make a request to the Google
Analytics servers to the metadata API
you can actually include this e tag
values part of the headers and then the
response you get back will depend on
whether the value you provided is the
same as what's already exists on the
server or it doesn't so if you send the
eTech Val units the same will respond
back with 304 response which is a not
modified response and you can then
you'll know that there's no changes if
you provide the value response back with
a 200 then you'll actually get a new
recent means there's a new response and
you have to update what you which you
have on your server side of your client
side so it's really helpful saving quota
and this is really probably useful for
mobile so you don't want to be sending a
lot of data back and forth and mobile
and actually when you make the request
of the metadata API you can specify
fields parameter and specify just to
request the e-tag value if you'd like so
it's really useful for caching and
making sure efficient use of the API in
quota so it's like a little bit about
the data duplication policy this is new
right with them we ingest one of the
things that we're introducing with the
metadata API is a new data deprecation
policy and this covers how we add and
change data within google analytics
reporting AP is so when we add new data
we'll add it will announce it through
the change log and then the data will
automatically appear through the
metadata API so if you're actually
building any products using this API
they'll automatically be updated which
is fantastic the second thing is when we
decide to remove data in the past it was
you know we would announce it but there
is nothing formal so today we're
formalizing it with this API when we
Annette when we announced the
deprecation of data what we'll do is
we'll actually message the change logs
and then it will be available for a
minimum of six months after which will
remove it and what we're doing is to
message user interfaces to keep them
updated where it's actually a new status
parameter that will set to deprecated by
default it's public and so once it's
deprecated you can actually update your
interfaces to start changing them and
then finally in the cases where we want
to replace sometimes we'll rename a
different dimension in metric this will
also go through deprecation where we'll
announce the change on a changelog the
data will be available for the old name
will be available for minimum of six
months but we'll also introduce a
brand new parameter that's called the
replaced by parameter and actually
returns an ID that points to a different
entity that's the replacement a
different dimension or metric that's the
replacement for the one that's being
deprecated so what's great about is now
with the metadata API for products that
have integrated with it they completely
can be compliant with all the
deprecation policies without having to
push new releases to production so let's
take a look at some of these attributes
yeah actually you know how it manifests
an actual response so you'll see that
there's a few different attributes here
let Nick mention which was the status so
when it's deprecated this will change
for public to deprecated and you should
always be checking for this value to
make sure that the dimensions and
metrics you're using are still valid and
can be used in a query and if it does
change a deprecated then you definitely
want to be checking to see if it's been
replaced maybe by a different ID and if
that's the case then we'll also include
this replaced by attribute which in
points the ID of the obviously dimension
metric that's replacing this particular
one right now and I think the good thing
about this is that if many people will
build saved reports within their
products and interfaces so if you do see
something that's deprecated you will
want to make sure you go back and update
or warn your users that either the
queries will stop working in the future
or just go ahead and update them with a
replaced by so that way they don't see
any disruption of service yeah yeah and
if you don't do this Walter mately at
some point that'll be removed and you'll
get a battery bad request response yeah
and it'll be a bad user experience as
well yeah exactly okay great so we
covered a lot but but you know it's it's
a very simple but powerful API think so
this is you know it's really easy to use
and it is really powerful to what you
can do in the UI this or that but we do
have a lot of resources available if
you'd like to learn more about this API
and how to use it we provide some code
code snippets and examples on our
developer site as per usual and again if
you're going to use a register and api's
console and get an API key that you can
throw together and then we have some new
data deprecation policy that you know
encourage you to read and review so if
you're building applications you
understand how things will be changing
the future that's it for today we want
to keep it short and simple and we want
to thank you for joining us again and we
hope to see you next time thank you very
much