We, at the AdWords API Team, are often asked questions such as "Where have all my units gone?" and "How many API units has a particular account used in the last month?" Luckily, we have supplied you with a great set of tools with InfoService to answer these questions. In this blog post, we'll talk about some basic uses of this service, as well as some caveats that can be solved using some more advanced techniques. All code examples have been coded using the AdWords Java Client Library.
Update: both of these examples have now been included as utility methods in the file UnitsUtils.java. The example links below have been updated as well.
We have a top most MCC, Top-MCC, which is the root of our tree. Since our goal is to generate a mapping of child account to the amount of quota used, a first approach may be to run getUnitCountForClients for each client, as shown below:
From the results, you can create a mapping that resembles:
You'll notice that while this data gives you some idea of client usage, there's no aggregation of client usage up to the MCC; Sub-MCC-1 returns just the number of units called directly on that account, such as from a command with headers:
In the method UnitUtils.getClientUnitsUsage, I show how to traverse the full account tree below the top most MCC and sum the units for each client to produce a mapping like the one above. However, if by some chance, a client has two parent accounts, linked through UI/API and API, and those parents are both distant children of the same parent, that client will be doubly counted. We've also shown how to keep track of these doubly counted clients in the demo.
We hope that these new utility methods will help you keep track of your API usage and stay tuned for more great demos like these!
--Adam Rogal, AdWords API Team
Where have all my units gone?
"Where have all my units gone?" is one of the most frequent questions asked by our developers seeking to trim down their API usage. Although InfoService provides the method getUnitCountForMethod, it is not inherently obvious how to generate a full mapping of usage. The heart of the problem is that, to call getUnitCountForMethod, you must pass it a service name and method. To get a full mapping of method to usage, getUnitCountForMethod must be called for each service and method pair. In the method UnitUtils.getMethodUsage, I have shown how you might do this.
The method is broken into two parts: populating a full mapping of service name to list of method names, and calling getUnitCountForMethod for each mapping. The result of each call is then put into a new map, referred to as methodUsage in the method. When the method has finished running, which may take a few seconds, methodUsage will have a mapping of serviceName.methodName to quotaUsage and the output will resemble:
The method is broken into two parts: populating a full mapping of service name to list of method names, and calling getUnitCountForMethod for each mapping. The result of each call is then put into a new map, referred to as methodUsage in the method. When the method has finished running, which may take a few seconds, methodUsage will have a mapping of serviceName.methodName to quotaUsage and the output will resemble:
AccountService.getAccountInfo = 3
AccountService.getClientAccountInfos = 257
AccountService.getClientAccounts = 0
AccountService.getMccAlerts = 0
AccountService.updateAccountInfo = 0
...AdService.addAds = 5005AdService.checkAds = 0AdService.findBusinesses = 0AdService.getActiveAds = 0AdService.getAd = 0AdService.getAdStats = 0AdService.getAllAds = 0AdService.getMyBusinesses = 0AdService.getMyVideos = 0AdService.updateAds = 0...TrafficEstimatorService.checkKeywordTraffic = 0
TrafficEstimatorService.estimateAdGroupList = 0
TrafficEstimatorService.estimateCampaignList = 0
TrafficEstimatorService.estimateKeywordList = 0
As you can see, many of my units went towards adding Ads. Using this data, I could enter my monthly values into a spreadsheet and plot my usage over several months. Not only could I easily spot where all of my units have gone, but I would also be able to spot any out of the ordinary behavior as well.
As a side note, regardless of the credentials supplied to the service, this method will only gather data against the developer token. Meaning that, supplying a clientEmail or clientCustomerId will not give a finer grained set of results.
How many API units has a particular child account used in the last month?
Another great feature of InfoService is that it allows you to determine how many units a particular child account has used over a period of time. This information can be used to invoice clients, if you are developing for an Agency, or to perform cost/ctr analysis, if you wished to optimize your accounts per API spend.
There is one caveat, however. Let's say that we have an account structure that resembles the one below:
There is one caveat, however. Let's say that we have an account structure that resembles the one below:
We have a top most MCC, Top-MCC, which is the root of our tree. Since our goal is to generate a mapping of child account to the amount of quota used, a first approach may be to run getUnitCountForClients for each client, as shown below:
InfoService.getUnitCountForClients(["Sub-MCC-1",
"Sub-MCC-2", "Client-1", "Client-2",
"Client-3", "Client-4"],
"3/1/2009", "3/31/2009");
From the results, you can create a mapping that resembles:
Sub-MCC-1 = 55
Sub-MCC-2 = 70
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400
Sub-MCC-2 = 70
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400
You'll notice that while this data gives you some idea of client usage, there's no aggregation of client usage up to the MCC; Sub-MCC-1 returns just the number of units called directly on that account, such as from a command with headers:
<email>Top-MCC</email>
<password>passwordForTop-MCC</password>
<developerToken>...</developerToken>
<applicationToken>...</applicationToken>
<userAgent>...</userAgent>
<clientEmail>Sub-MCC-1</clientEmail>
What you may actually want is an aggregation of unit usage such as:<password>passwordForTop-MCC</password>
<developerToken>...</developerToken>
<applicationToken>...</applicationToken>
<userAgent>...</userAgent>
<clientEmail>Sub-MCC-1</clientEmail>
Top-MCC = 2275
Sub-MCC-1 = 1305
Sub-MCC-2 = 470
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400
Sub-MCC-1 = 1305
Sub-MCC-2 = 470
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400
In the method UnitUtils.getClientUnitsUsage, I show how to traverse the full account tree below the top most MCC and sum the units for each client to produce a mapping like the one above. However, if by some chance, a client has two parent accounts, linked through UI/API and API, and those parents are both distant children of the same parent, that client will be doubly counted. We've also shown how to keep track of these doubly counted clients in the demo.
We hope that these new utility methods will help you keep track of your API usage and stay tuned for more great demos like these!
--Adam Rogal, AdWords API Team
