So, You Want to Make a Reporting Application
Tags: business, advertising, programming, analytics
Published: 2019-08-14 13:35:10

Say you’re a prospective new business owner and you are ready to open a brand-new customer facing business. You get everything perfect on opening day, but no one shows up. You are missing a crucial part of any business, **advertising**. Modern businesses need to have a presence both locally and more importantly online. Google, Bing and Facebook are some of the big companies who offer services to help businesses such as yours accomplish this task. 

With intuitive online interfaces and support, an advertiser would be able to grow their online presence and its impact on their business. For the more technically savvy there exists other avenues to build custom tools, dashboards and more. These avenues are called **API’s** or **Application Program Interfaces** and they can be very powerful tools to get the most out of your business. In this article, lets focus on one of the three big advertising companies and its unique API platform.

Most advertising reporting API’s follow a basic set of standards. Before getting your feet wet let’s lay down some standards in which Google (and other online platforms) operate:

- **Documentation is a powerful tool, use it.** There is a lot to unpack when trying to get data out of an API. Questions like Finding out how a report is segmented or how to access the desired fields of a report or the type of data contained within.

- **Data received by the user is usually report based.** There are numerous correlations, rules and first party knowledge that goes into how numbers are displayed to the user. It can simplify the logic a bit when running basic reports but can make it difficult to do custom calculations.

- **Data is the freshest at certain times of the day.** Some data is not and cannot be live. Platforms typically have a set time of day they can guarantee data will be fresh. It is imperative to know and plan around these times if highly accurate results are required.

- **Connecting to and authenticating can be tricky.** APIs are open to the public and data needs to be protected. To connect to them, multiple steps need to be done to ensure privacy. Typically, these protections include using OAuth2, Bearer tokens and a lot of generated keys.

- **Data will not always be in the format you can use.** Data can be transferred in numerous different ways online. JSON is a very simple yet powerful format that is used by API’s to deliver data back to you. Sometimes data needs to be coaxed out of an excel document or some proprietary data structure.

##Documentation
The first step in working with any new technology is reading any documentation available. API’s can be highly complex, and developers rely on it to know what and how to request. It is like night and day when working with an API that doesn’t have good documentation versus one that has great documentation. Google Ads thankfully falls on the “day” end of that spectrum: clean documentation that not only specifies how the data is segmented, but what fields can be requested on the report and even the data type and property name to look for in the return file.

![Clean definition of attributes, segments and metrics on the Google Ads Campaign Performance Report](https://thepracticaldev.s3.amazonaws.com/i/i7989h5uyifb5ovgkp3w.png)
<figcaption>Clean definition of attributes, segments and metrics on the Google Ads Campaign Performance Report</figcaption>

![Very informative breakdown of the AverageCost field on the Campaign Performance Report](https://thepracticaldev.s3.amazonaws.com/i/fcytf2ed0i6uczwvr29p.png)
<figcaption>Very informative breakdown of the AverageCost field on the Campaign Performance Report</figcaption>


##Report Based Data
Google Ads combines Google Search engine results, YouTube video metrics and Google AdSense into a feature rich web app and API. The sheer amount of data available can be overwhelming. It can be even more overwhelming to developers who are just getting started developing on the platform. Google Ads solves this issue by offering a host of reports out of the box.

![A list of the reports offered by Google Ads](https://thepracticaldev.s3.amazonaws.com/i/8lj25q3o3p5zewjghtrl.png)
<figcaption>A list of the reports offered by Google Ads</figcaption>

So, the next question is “How do I get these reports into my code?” Thankfully the answer is straight forward. Normally, to start downloading these reports would require a fair amount of boilerplate code. Google has simplified this step a lot by creating and distributing packages tailored to the Google Ads platform.

Once the packages are installed a developer can generate a request specifying the report type, columns, date range, returned file type and other specific request information. Once sent, the Google Ads API will send back a file in the format requested for consumption. Having this level of flexibility offers developers a solid foundation in which to power their reports.

![Basic C# report request definition](https://thepracticaldev.s3.amazonaws.com/i/7afp3xxkse7f4z9baw7k.png)
<figcaption>Basic C# report request definition</figcaption>

##Fresh Data
A common aspect of working with live advertising data is how **fresh** the data is. The concept of fresh data is not unknown to developers who work in and around databases. Data is considered “Fresh” if it is the most recent, up to date data available. The further from the time the data was released, the more stale the data becomes. It is important to know what type of data you are pulling and when it was pulled to get the most accurate picture possible.

![](https://thepracticaldev.s3.amazonaws.com/i/nwsib9v1pdvzsro3gb5m.png)
<figcaption>For more information about Google Ad metrics, visit https://support.google.com/google-ads/answer/2544985?hl=en</figcaption>

##Authentication
Security is huge concern when working with anyone or anything online and API’s are no different. Google Ads requires four pieces of information before allowing data to be queried in the API. The first is a *developer token*. This is tied to a developer account and is used by Google to track who the developer is and what level of access they have. New developers start out with basic developer access and must send an application to Google for full developer access. The next two pieces of information, the **client id** and **client secret**, are a pair of ids that specify which account the data is drawn from. The id is easy enough to find, but the secret must be generated for that account. Finally, the *refresh token** is another generated token that has a limited life and must be regenerated regularly. Once all these tokens are assembled, data can be requested successfully from the API. A step by step walk-through can be found by clicking [here](https://developers.google.com/adwords/api/docs/guides/first-api-call).

When working with authorization tokens you never want to store them in the code itself. Anyone who has access to your code base has access to your tokens. So where can you store these tokens so that you can still access them in your code? A product such as Azure KeyVault or other cloud-based platform is a great solution to this problem. When it comes time to renew your refresh token, simply swapping it out in the cloud is very fast and simple.

![](https://thepracticaldev.s3.amazonaws.com/i/ncrbsz9i82ia8wfmrblp.png)
<figcaption>For more information about Azure KeyVault, visit https://azure.microsoft.com/en-us/services/key-vault/</figcaption>

##Data Formats
There are multiple ways to transfer data online. JSON, CSV, tab spaced are just some of the common formats employed by modern API’s to respond to data requests. Google Ads give you the option to specify how you would like your data returned. However, the data is returned the key is to get it in a consistent format for your code to consume and process. For example, if you want to store data from a campaign report into your database you might want to request data as a CSV, then convert that data to a database object and save it to the database.

![Sample code for reading a gZip file from the Google Ads API](https://thepracticaldev.s3.amazonaws.com/i/tnqotgdk494yw5econop.png)
<figcaption>Sample code for reading a gZip file from the Google Ads API</figcaption>

##Only the Beginning
Taking these standards into account is only the jumping off point into the world of internet advertising API platforms. Any major customer facing business worth its salt has a vested interest in data pulled from these platforms and how it can help to grow their business. As a developer knowing how to interact with these API’s, understanding their quirks can be a great boon to any developer.