The Omniture API – Putting Your Own Spin on the Data

At last year’s Omniture Summit – yes the 2008 version – one of the most interesting announcements was the release of a Reporting API for SiteCatalyst. Like red wine, technology announcements generally require a certain amount of time to age into a respectable level of maturity and the Omniture Reporting API was no exception. But late last year, after playing on-and-off with the API, we at Semphonic decided it had reached a level of maturity where it could be successfully used.  It’s still early days – the API is beta and its deployment model a little fuzzy – but you can work with it reliably and produce interesting products. This blog isn’t about programming, and I don’t want to get ridiculously technical. So what I’m going to do is provide some background on the API. What is an API, when you might want to use the Omniture API, how it works from an implementation perspective and a brief primer in how the Reporting API, in particular, is actually used.

So what is an API?
API stands for Application Programming Interface – and it’s really nothing more than a way for one program to communicate with another. APIs are common in all types of technology applications and programmers use them all the time.

So the very first thing to understand about APIs is they are for programmers. If you aren’t a fairly technical person, you won’t want to use an API yourself though you may still want to know what they can do.

In these internet everywhere days, most APIs are a special type of API called a web service that is used to connect one program to another across the internet. Most of the Omniture APIs are web services. Notice that I used the plural tense there – because the Omniture API is actually several very distinct pieces and they don’t all function quite the same way.

What can the API do?
Here’s where we get into the different pieces of the Omniture API. The Omniture API includes web services for doing administrative tasks (essentially anything you might do from the SiteCatalyst Admin Console you can also do programmatically), accessing most SiteCatalyst data (this is the Reporting API I’ll talk about in my next post), accessing some Discover data, and for accessing the Data Warehouse (submitting or monitoring requests). There are also APIs for SAINT and Data Services that are very early days. In addition, Omniture has a long-stranding Data Insertion API. This isn’t a web service – it’s a simpler interface that allows you to use XML Post requests to send data to a report suite.

You should think about using an API whenever you need to either get Omniture data into some other program/system or you need to provide additional automation around some common Omniture task.

Let me give you an example. When we perform data quality audits for our customers, one of the things we check is how the Administrative items are configured. If you have a single report suite, that’s easily done in the Admin Console. But if a client has twenty, fifty or five-hundred report suites, it’s a lot of navigation time wasted just getting their information.

You can use the Omniture Administration Web Service to dump all of the settings for every report suite in an account to an Excel spreadsheet. It’s handy. And, in fact, there’s a sample application on the Omniture Developer site for doing just that.

Here’s another common problem. You have a system to report on that includes both offline and online data. You need to send out reports daily. Since the information you want is in Omniture and some other system (probably a database), you have to manually combine the two.

But now, you can pull the data from your internal system first, then use the Omniture Reporting API to get the online data you need. Your program can combine them and automatically send out a report that contains both types of data.

So the basic rule of thumb is this: if you need to combine data from two or more systems including Omniture Suite, if you need to move Omniture information into some application other than Excel, or if you need to automate some task that isn’t well handled by the Suite, then the APIs might be a good bet.

What Programming Languages can you use?
Since the Omniture APIs are mostly web services, you can use any language that will consume a web service. These days, that means you can use pretty much anything.

If, like Semphonic, you are Windows Shop, I’d strongly advise you to use VS 2008 languages. The security model used by Omniture is not well supported in earlier versions of the VS .NET languages.

How much does it cost?
Here lies the rub. Nobody knows. Right now, Omniture is using a token system. Each account gets a certain fixed amount of tokens free each month. Each request takes up a certain number of those tokens (based on the request). When you run out of tokens, your requests just start to fail.

I know of no policy for buying tokens and I don’t think Omniture has fixed the actual number of tokens that will be available or what the price will be. I’m going to devote a whole post to the “token” issue because it’s really the biggest problem with the API.

Is it hard to use?
Not really. Given that you are programmer, it’s very similar to most other web services in conception and execution. Most programmers will be able to download a sample application and begin using it almost immediately.

Does this mean I can get all my Omniture data or can access stuff I couldn’t before?
No. This is probably the biggest misconception about the API (I get this about the Data Warehouse too). You don’t suddenly have access to every record and you can’t run SQL like queries against the data. The API is NO substitute for the data feed. Using the Reporting API, you can get access to most (but by no means all) of the data available in SiteCatalyst. It’s pretty much like Excel Integration. So if you are moving data to Excel, it’s unlikely you’d get any benefit from the API and you have a much worse usage policy (tokens) to deal with. Nor does the Data Warehouse API somehow open up any capabilities – you just use it to automatically submit or check the status of requests. That’s it. The API is not equivalent to warehousing the information and it will generally give you less not more access to data than SiteCatalyst, Discover or the Data Warehouse.

Where can I find out more?
The first, best and pretty much only resource for Omniture API information is the web site http://developer.omniture.com. You will need an Omniture account login to access the documentation there.

I think that probably covers the most common questions about the Omniture APIs. In my next post, I’ll walk through using the Reporting API and show how it works.

Comments

[Chris Wareham]

Hi Gary-

Thanks much for a very informative primer on API usage, for the mention of our API capabilities, and for the opportunity to clear up some of the murkiness that you point out about our token mechanism.

To get started, each login company gets 2000 monthly tokens for free. Omniture customers can contact their account representatives to purchase more if needed. Those 2000 tokens are 'use them or lose them' on a monthly basis; we don't currently offer 'rollover' tokens, but it's something we're looking at.

In terms of API consumption, whenever a single API "call" is made to Omniture's Reporting, Admin, SAINT, Discover, Data Warehouse, or Data Sources APIs, 1 token is charged. Most generic *Reporting API* requests will require 2 tokens; queueing the request for the data will consume 1 token, and the receipt of the data itself will consume 1 token.

In our other APIs, most transactions will consume only 1 token. As we enrich the kinds of data available via the APIs, it's possible that we'll increase the token charge for certain calls, but for now each single API call consumes only 1 token.

I hope this clears up a bit of the murkiness around our token mechanism. Please feel free to contact me cwareham@omniture.com, or visit http://developer.omniture.com (some pages require your SiteCatalyst login), or contact your account manager if you have additional questions about the API or how to get access to additional tokens for your environment.

Chris Wareham
Senior Director, Product Management
Omniture