Ad Analytics API



Introduction

PointRoll’s Ad Analytics API allows other applications to interact directly with PointRoll’s OnPoint Analytics system, enabling customers to submit data requests reflecting campaign performance.

Onboarding

Before using the Ad Analytics API you will need to participate in an onboarding discussion with PointRoll. This meeting will help us understand how you intend to use the API. It will also provide a forum to discuss the technical details of the implementation specific to your business needs. If you are interested in integrating with PointRoll’s API, contact your PointRoll Representative to schedule an onboarding discussion.

In preparation for the call, please consider the following:
• What is your target date for implementation?
• What specific metrics and aggregations do you expect to include in your API request(s)?
• Will your data encompass oversight for more than one advertiser?
• How frequently do you expect to make data requests to PointRoll through the Ad Analytics API?
• What level of granularity are you expecting to request?

Getting Started

The information in this document outlines the fundamental information of PointRoll’s Ad Analytics API. Before using the API, you are encouraged to review this document to ensure you have the necessary information and resources for proper implementation.

Requirements

The following items are required to use the PointRoll API:
1. Username and password supplied by PointRoll
2. Appropriate permissions (configured by PointRoll at time username/password issued)
3. Advertiser ID

• Advertiser ID for advertisers will be determined by the scope of your token
• Advertiser ID for agencies/publishers will be determined by submitting a request to the API. • The response will contain a list of IDs for advertisers to which the agency/publisher has access. The advertiser IDs from that list can then be included in subsequent report requests.

4. The URL to use to access the data is https://reportapi.pointroll.com

Technical Details

The Ad Analytics API is based on REST principles. It uses an HTTPS transport, and supports JSON and XML data formats.

How It Works

All data requests made through the OnPoint Ad Analytics API must be both authenticated and authorized, and are illustrated in the process flow below.

How It Works

Available Metrics + Aggregations

The following metrics and aggregations are available to be requested through the API. Each metric/aggregation has a corresponding ID, which will be used in the request.

Aggregations
Aggregations
Detail Metrics*
Summary Metrics*These metrics can only be requested one at a time. They cannot be grouped in a request with any other metrics.

Summary Metrics*
Detail Metrics

*These metrics can only be requested one at a time. They cannot be grouped in a request with any other metrics.

Using the API

The REST Client

One way to interact with the API is by using a REST client. The REST client is a good tool to use to test API calls and inspect the data returned. There are several free/open source REST clients available for download on the web. More information on the REST client: http://restclient.net/

Best Practices for Requesting Data

Best practices for using the Ad Analytics API are outlined below:

Best Practices

Service Level Agreements

Service level agreements for the PointRoll Ad Analytics API:
• Each request is limited to 31 days
• Each request is limited to a maximum of 1 advertiser
• The timeout standard for a token request is 12 hours
• The timeout standard for a report request is 30 seconds
• Only 1 time based aggregation may be selected at a time. Time based aggregations include daily, weekly, and monthly.

Making Requests

The following information will assist you in making successful data requests. For detailed sample requests, refer to the Request Flow documents (JSON/XML).

Data Request Requirements

The following items are required when making data requests:

  • Advertiser ID
    • Advertiser ID for advertisers will be determined by the scope of your token
    • Advertiser ID for agencies/publishers will be determined by submitting a request to the API. The response will contain a list of IDs for advertisers to which the agency/publisher has access. The advertiser IDs from that list can then be included in subsequent report requests.
        • Date Range
        • TOKEN included in the header of each request
        • Username and password included in the header of each request
          • This is only required when getting a token via a call to “/User/Login”
        • Metrics IDs
        • Aggregations IDs
        • Campaign IDs
          • Not required but should be used in the request when you want data for specific campaigns for the advertiser(s) in the request.
          • If a Campaign ID is not used, data for all campaigns will be returned for the advertiser(s) included in the request.

           

          Sample Requests + Returns

          Sample requests and returns for both JSON and XML are displayed on the request flow. To view this detailed sequence diagram displaying the sample requests, click here (JSON/XML).

          Report Status Codes

          When a request for a report status is submitted, one of five statuses can be returned from the request.sample requests

          Error Handling

          If a request fails, an error will be returned and the requester will receive a notification about the failure. Common reasons for failure and sample error messages are listed below.

          Common Reasons for Failure

          The following may result in a failure of your data request:
          • Access/permissions restrictions (not authorized to see or use the API)
          • Extremely large data requests
          • Requests for data for a time period exceeding 31 days
          • Malformed requests

          General Information About Errors

          Information about errors generated when using the API:
          • Requests that generate an immediate error will return HTTP code 500 ‘Internal Server Error’
          • Requests that result in an error status on a report can be determined by calling the pickup error function for that report
          • The ‘errorID’ shown for each error is intended as an identifier to reference a specific error in order to assist PointRoll in diagnostics

          The content of the error comes back in JSON as:

          JSON

          The content of the error comes back in XML as:

          XML

          Sample Errors

          Sample Errors

          Release Notes

          PointRoll Ad Analytics API, Version 2. June 1, 2013.

          Support

          If you need further assistance, contact Support at:

          EMAIL support@pointroll.com

          PHONE 1.800.203.6956 ext. 109

           

          Back to Top Back to Top

About The author

PointRoll Marketing


PointRoll Sponsers ADC Festival


adc festival

by: Walter Geer

What do you get when you mix some of the world’s top creative minds from advertising, photography, film, and architecture, throw them on a beautiful resort in South Beach Miami just steps from warm crystal blue water, add a lot of alcohol, yoga on the beach, an awards show, and the openness and freedom to inspire and be inspired without being pitched? You end up with The ADC Festival of Art + Craft in Advertising and Design, sponsored by yours truly -PointRoll.

If you were lucky enough to be one of 300 people specially selected to attend, then you were part of quite an experience. It’s typical of most conferences to sit, listen, take notes and leave. Not at the ADC Festival. Every session required forming groups of 3-5 people from various parts of the globe to participate in hands-on workshops guided by the top creative folks in the industry.

So what does your not-so-typical day look like?

What if…

You were presented with a 10 pound bag of clay and had to build a sculpture of the man, the myth, the legend, Lionel Richie? Would you be able to craft the oh-so-popular face of the man that sang “All Night Long?” You may not believe it, but the most difficult part was creating the afro. Can you imagine??? My team ended up resorting to using the plastic bag to give it a full lustrous soul glow!

What if…

You were asked to break down the walls and barriers of social networks and truly expose yourself to someone you don’t know? Broken out in to a group of five, we were asked to share our most private possession with a random stranger: OUR CELL PHONES! After handing it over to this stranger, they had to open your photo gallery, swipe until someone said stop, tap the screen randomly, and present that photo to the group. When this was done the stranger holding your phone and photo would have to explain what’s going on in the picture.

What if…

You had the opportunity to take an hour out of your day to build a guitar with Martin Guitars’ Director of Museum and Archives, Dick Boak? Don’t know who he is? For the past 32 years, he led the formation of Martin’s Artist Relations Department, and orchestrated the conception of more than one hundred and forty signature guitar collaborations with the top musical talents of our time. Imagine spending the time to carve, whittle, and sand one of the most beautiful guitars in the world.

What if…

You got to spend an hour with one of the pioneers of the flash and ActionScript scene, Joshua Davis. Joshua blew everyone’s mind with a small glimpse into his world and his vision for where art can go. Using open source tools like “Processing”, Davis has come up with the perfect marriage of code and art. Sharing his genius on GitHub, Joshua has developed a framework that allows artists to add randomization, movement, and interactivity to their art – ultimately creating breathtaking pieces that are equal parts technically and aesthetically astounding. 

What if…

All you needed was your imagination and friends to create advertising in real time? During the final award ceremony, PointRoll placed the ADC festival attendees inside a digital ad banner – in real-time – through “Create-A-Vision. Some of the biggest names in advertising and design were able explore their inner improvisational acting skills, which then populated into a digital banner in just minutes!

And it didn’t stop there. This highlighted just 5 of the 11 sessions that took place over 3 days in sunny Miami. Each night ended with an awards show, where ADC Cubes were given to top creative winners.

Hopefully we’ll see you there next year!

About The author

PointRoll Marketing


Play Flappy Beanie!


beanie

It began with a Boy and his Beanie. Now, as we welcome in our new website, we want to leave you with a tribute to the Beanie, and a reminder of how far we’ve come.

This Throwback Thursday, play “Flappy Beanie!” Pilot the Beanie through a series of tubes at blazing speeds and see your high score. Can you best your friends? Share the game to find out!

About “Flappy Beanie”: The construction of this game was one of the results of PointRoll’s 2014 Hackathon.  Jesse Brown did most of the work building the game, with help coding and testing from fellow ‘Rollers Kevin Broomall, Steve Rayl, and Carl Herrick.  While the basic nature of the game was derived from Flappy Birds, all the assets and music for this game are PointRoll specific.  Thanks for playing!

Game URL: http://bit.ly/1e8CbQO

About The author

PointRoll Marketing


2013 PoinRoll Benchmarks Released


2013benchmarks

Every year, we take some time to evaluate the past year via our Benchmarks Report.  Yesterday, we released the 2013 Benchmark Report.

2013benchmarks_12013benchmarks_32013benchmarks_2

This year’s report is divided  into six categories — Format, Size, In-Stream, Vertical, Viewability and Day of the Week — across display, mobile and video.

Among the key findings:

  • People are more willing than they used to be to watch long pre-roll video ads
  • Ad viewability increased by 17% over last year, up to 60%.
  • Adding video to rich media boosts interaction rates by an average of more than 17%
  • In part because of their size, IAB Rising Stars deliver a 70% lift in CTR over other ad formats — and 36% more brand interaction time
  • 30-second in-stream video ads deliver a completion rate just 6% lower than that of their 15-second peers — yet they earn a CTR 55% higher than 15-second ads. (That’s good news for advertisers looking to repurpose 30-second TV spots.)
  • Rich media interaction rate is higher during the week — important information for brands — but click-through rate is higher on weekends.

Take a cruise through the interactive report.  Click around, and see what you can find.  You can download the entire report here: http://link.pointroll.com/2013benchmarks.

Portions of this report were published first in VideoNuze, Direct Marketing News and MediaPost.

About The author

PointRoll Marketing


Why Mobile Ads Suck
and How to Change That


mobile ads

By: Dan Mouradian, PointRoll Product Marketing Director

The very first ad on television was this 10 second spot for Bulova. It’s little more than a “static” graphic and a 2 second voiceover… with 8 seconds of dead air. As bad as this ad is, it was the very first. Oftentimes, the first of anything isn’t very good; the very first powered flight was 3 seconds. Even the Constitution was flawed at first: it’s had 27 Amendments. Why the Bulova ad looks and sounds like this is simple: the most effective form of advertising at the time was radio. This is little more than a radio spot with an image crudely attached to it. It aired in 1941. Nearly 75 years later we find ourselves making the same mistakes, only this time with mobile advertising.

You cannot approach mobile advertising the way you approach display advertising. It is not the same. It is not even close. The only thing they have in common is that they are both connected to the internet. 

The most common form of mobile advertising is the static 320×50 static JPG. Why? Why on earth are we building crappy JPEGs? Why is everyone ignoring the fact that the mobile devices we all carry around in our pockets are purpose-built for consumption of media? A recent study shows that we check our devices on average 100 times a day, which once every 10 minutes if you happen to sleep only 6 hours a night. The reason these formats are the most common is because they are the easiest – that’s it. We’re being lazy. They are not the most effective, they are not the most engaging, but most condemning of all is that the measurement of these types of units is the worst kind of measurement out there.

With these static JPEGs, all anyone can tell you is how many ads were served (Impressions), and how many people clicked on them (Clicks). If you divide those two numbers by each other, you get Click Through Rate (CTR). Screw CTR; it’s useless when you are talking about conversion.  Study after study  after study suggests the same thing. If you are going to make mobile ads that don’t suck, you will need to do a few very important things:

Consider the device you are placing your ads on. Doing this ensures you are not making the same mistakes Bulova did in 1941. Consider the device and how users are actually using it. Nobody taps on ads to go to landing pages on mobile devices. You don’t do it; why on earth would you expect a consumer just like you to do it? What you should be doing instead is create engagement opportunities on mobile. When you pick up your phone, open an app or the mobile web, and an ad does catch your glance, remember the feeling you have when you see it. Everyone feels that way. Instead of asking a user to “Tap to Learn More,” ask them to “Swipe to get a personalized offer” or “Swipe to see a web exclusive trailer” or “Pinch to expand” or “Pinch to reveal the all new 20XX car”. Which leads me to my next point.

Be genuine, give users something for their interaction. If you are an entertainment marketer that makes TV shows or movies, trade the user for content. If you advertise cars, ask the user to explore why your car is better than the car they drive now.  If you want to sell something, give them a place to buy it nearby, or how many are in stock, or a coupon. Do these things and measure your ads by conversion rate, or by interaction rate. See what a better story that gives you for your Effie case study and what it will do for your client retention. Be careful though: as people, our bullshit detectors are pretty dialed-in thanks to evolution. If we swipe, pinch or tap and your ad does not immediately give us what was promised but sends us to some landing page, we’re closing it and telling all our friends what a jerk you are for hiding the saber-toothed tiger in the cave you told us fire was in.

Lastly do not ask them to do anything foreign. Asking a user to “click” on a mobile device instantly turns that cleverly crafted message of yours into the following sentiment: “We don’t know you and don’t care about you, so feel free to ignore us.” There is a vernacular to the way we all use our devices, and clicking is not a part of it.

Do these three things, abandon CTR, and you will have built an experience worthy of being on the internet in our pocket. Start here and you can build something great. You won’t be the first to do it, but your advertising will better for thinking about your consumers and how they interact with content, before creating the ad.

About The author

PointRoll Marketing


Media Rating Council
Lifts Advisory on Viewability Measurements


MRC viewability

By: Erin Crapser

The Media Rating Council announced that it has lifted its advisory warning against advertisers using viewability measurements as trading currency. This comes just days after the PointRoll 2013 Benchmark report found a 14% rise in viewability year-over year from 2012. Click here to read more about the announcement.

This announcement is an important reminder that the response elicited by an ad is highly dependent on the context in which it is viewed. As PointRoll has demonstrated, the viewability metric can be used to evaluate inventory quality, and set expectations about the impact an ad will have as part of a larger campaign. Going forward, advertisers will have more confidence that their ads are in view, and can focus on the importance of where they were viewed, both in terms of placement on the page, and device type. With a better understanding of this context, advertisers and agencies are positioned to deliver the most effective ad for each viewing scenario.

Todd Pasternack’s article on “What Comes After Video Viewability” offers further insight on this topic.

About The author

PointRoll Marketing


Big Creative Series:
New York Video Panel


video panel

On March 27th PointRoll hosted Video Panel in New York as part of our Big Creative Series.  The event focused on the challenges and opportunities in video today, and offered insight from panelists Leigh Ferreira, Iordanka Katardjieva, Brad Bernard, and Todd Pasternack.

Below are a few key points from the panel:

  • The idea of relevancy at scale is much easier from a technology perspective than from a creative perspective. “We need to figure out a way to scale relevancy and personalization- that is the hot sauce for any client.” -Todd Pasternack
  • Marrying dynamic creative and programmatic placements is the power of machines plus the creativity of human influence.  “Programmatic is exciting; we are a small shop that is now able to compete against the big agencies.” -Iordanka Katardjieva
  • Interactive and dynamic video are a cost effective way to deliver digital relevance to existing assets and drive increased engagement compared to standard in-stream. “Interactive video has a really strong place in our world. There is no shortage to target, the hardest part is to get noticed.” -Brad Bernard

Some additional reading related to video:

Photos from the event can be found here.

The Big Creative Series will continue with another event in the coming months. Stay tuned for a Save-the-Date and information through our social networks.

About The author

PointRoll Marketing


Big Creative Series:
Los Angeles Auto Summit


auto summit

On March 25th PointRoll hosted an Auto Summit in Los Angeles as part of our Big Creative Series.  The event featured a spirited discussion on the changing automotive marketing landscape, led by moderator Cindy Scott with contributions from panelists Rob Siltanen, Kristi VandenBosch, David Angelo, Ciaran Bossom, and Marc Vermut. It was tremendous to get such broad and informed views on the challenges and opportunities in the auto industry today from these market leaders.

The endeavor to understand how each of them is approaching the future of their automotive marketing businesses centered on the theme “Have traditional agencies become obsolete in the world of automotive marketing?”

Broken out into three sections, the panel provided strong insights regarding:

  • The best ways to structure today’s agencies
  • Where high-profile creative, like Super Bowl ads, fit into automotive strategies in 2014
  • Managing the balance of paid, owned, and earned channels

Several key takeaways from the discussion:

  • Creativity is king in achieving brand impact, while media is the delivery vehicle. However, creative is pulled in many directions, and must meet the needs and parameters of the client, the customer, the dealership network, partner agencies, and the media budget.
  • For too long the industry has used advertising primarily to get the customer to a dealership. Instead, advertising should be used to get the customer to buy into the brand mindset, and to keep the brand conversation alive at all of the many entry points in the customer journey.
  • While the ultimate goal is improving sales, market share, and profitability, keeping score throughout a campaign helps brands and agencies understand what drives performance and how to course-correct if necessary.
  • Distinguishing between Tier I, II, and III ad spend is a behavior driven by business needs, totally removed from how customers perceive ads. Creative strategy should be developed on a larger scale with holistic brand goals in mind.
  • Is a brand best served by a select group of specialist agencies, or the power and scale of a large brand agency? Not surprisingly, we heard many viewpoints on this topic:  good digital work requires the best creative as well as strong digital expertise, not commonly found at some brand agencies. On the other hand, global clients with high demands require the breadth and depth of talent offered by a large agency, backed by a holding company.

Photos from the event can be found here.

The Big Creative Series will continue with another event in May. Stay tuned for a Save-the-Date and information through our social networks.

About The author

PointRoll Marketing


PointRoll Benchmarks:
In-Stream Video


PointRoll Benchmarks for In-Stream Video

In-Stream video has been an extremely fast growing ad format lately, and in our most recent Benchmark Report detailing 2013 ad performance, we’ve once again found the growth and discussion to be backed by solid performance.

Across billions of in-stream impressions served by PointRoll in 2013, we’ve discovered some fascinating statistics proving that not only are in-stream units some of the highest performers in digital advertising, but their acceptance is growing, witnessed by healthy increases in performance year over year.

For more information about how video is continuing to prove its value, check out this article by our friends at VideoNuze! Look for more data from our annual benchmarks report in the days to come.

About The author

PointRoll Marketing


PointRoll Benchmarks:
In-Stream Video


PointRoll Benchmarks for In-Stream Video

In-Stream video has been an extremely fast growing ad format lately, and in our most recent Benchmark Report detailing 2013 ad performance, we’ve once again found the growth and discussion to be backed by solid performance.

Across billions of in-stream impressions served by PointRoll in 2013, we’ve discovered some fascinating statistics proving that not only are in-stream units some of the highest performers in digital advertising, but their acceptance is growing, witnessed by healthy increases in performance year over year.

For more information about how video is continuing to prove its value, check out this article by our friends at VideoNuze! Look for more data from our annual benchmarks report in the days to come.

About The author