Reporting API

Introduction

The Flite Reporting API provides access to the tabular data in the Flite Platform standard reports. To access data, you create an http request that specifies multiple query parameters, such as the start and end dates, and the dimensions and metrics that make up the column headers in the table. This request is sent to the Flite Reporting API and returns all the data in the form of a table.

Benefits

The Flite Reporting API gives you access to most of the reporting data in the Flite Platform.

Reduce time by automating both simple and complex reporting tasks.
Pick and choose the data you want to see, in the order that you want to see it in.
Integrate your Flite data into other business applications.

Overview

The Flite Reporting API offers three endpoints to aid in downloading reports. The first endpoint generates a report request that will be processed asynchronously. The second endpoint gives you information about your report (including report status). If your report is completed, you can use the third endpoint to obtain your report. The third endpoint returns your completed request in the format of your choice.

Getting Started

This document is going to cover how to use the Flite Reporting API so that you can get started right away. Below are the two major steps this document will cover.

Authenticating and authorizing a user.
Querying the Reporting API.

Authentication

The Flite Reporting API utilizes OAuth. OAuth is a standard by which third-party servers can obtain access to an HTTP service. Utilizing OAuth requires a set of keys that will be provided by Flite. More information on OAuth is available at http://oauth.net/

Obtaining OAuth Keys

Each Flite user can be issued a set of OAuth keys, one key for each Organization the user is registered with. A set of OAuth keys includes a public and a private key. Request your Organization’s OAuth keys from your designated Account Manager or through Flite support at http://support.flite.com.

OAuth and the Flite Reporting API

Due to the requirements of using the OAuth protocol, when requesting a Flite resource each request must pass a number of parameters, including:

  • The public key
  • A nonce
  • A signature that’s generated based on the public key, private key, timestamp, nonce, and the resource being requested
    There are many open source libraries available in many languages that can generate signed OAUTH requests. To verify that you are generating requests correctly, LinkedIn provides a handy tool: https://developer-programs.linkedin.com/oauth-test-console

NOTE

We enforce a 5 second window on the timestamp, so be sure to click the link quickly after generating it.

Querying the API for Reports

Querying the Flite Reporting API is a three step process. Each step requires a signed request to the Flite Reporting API endpoints. This section of the documentation covers each of the three requests.

Step 1 - Create Report Request:

The first step in generating tabular data through the Flite Reporting API is to create a request for a report. Based on the various parameters you supply in this request, you can specify the kind of report you want and trigger its processing. Note that the report will be processed asynchronously. The details of the request and its parameters are provided later in this section.

Once you trigger the first request to the Flite Reporting API, a report object will be created based on the specified request parameters. This endpoint will return a JSON object with the key “reportId” identifying your specific report request (an example is provided later in this section). You can use this reportId to both retrieve information about your report (such as status) and later to download it once it's processing is complete.

Report Request URL

http://api.flite.com/rr/v1.0/data/{type}/{guid}.{format}?{params…}

*HTTP method type: GET

Example:

http://api.flite.com/rr/v1.0/data/ad/56298ef0-d28a-4ebe-96ed-0e7b49c202e3.csv?start=04/16/2015&end=04/22/2015&columns=adName,adId,placementSize,impressions,interactions,engagements,clickthroughs,totalTimeOnUnit,day&name=demoAd

Report Request URL (when {type} is REPORT):

http://api.flite.com/rr/v1.0/data/{type}/{subType}/{guid}.{format}?{params…}

Sample response for both requests:

{"reportId":"89fb56cd-dcae-4452-b33f-f5774b146117"}

Path Parameters
All of the path parameters associated with the two urls above are required. Below are their expected values.

Parameter:{type}
Description
Required (exactly one)

AD

Used for providing data on ads. In this case the guid provided will be for an ad.

Yes

ADMIX

Used for providing data on ad mixes. In this case the guid provided will be for an ad mix.

Yes

CAMPAIGN

Use for providing data on campaigns In this case the guid provided will be for a campaign.

Yes

REPORT

Used to generate reports that are similar to the ones available through the Report Studio. The type has to be supplied with a subType.

Yes

Parameter:{subType}
Description
Required (exactly one)

AD

Used when generating a report for an ad. In this case the guid provided will be for an ad, unless the type is report, in which case the guid will be for a multi-ad report.

Yes

ADMIX

Used when generating a report for an ad mix. In this case the guid provided will be for an ad mix, unless the type is report, in which case the guid will be for a multi-ad report.

Yes

CAMPAIGN

Used when generating a report for a campaign. In this case the guid provided will be for a campaign, unless the type is report, in which case the guid will be for a multi-ad report.

Yes

GUID
This is the resource guid. Currently, it may belong to an ad, an admix, a campaign, or a multi-ad report.

Format
This is the format of the response. Currently, this can be either csv or zip.

Parameter:{format}
Description
Required (exactly one)

zip

Response will be a downloadable zip file.

Yes

csv

Request will have a response type of csv.

Yes

Query Parameters
The query parameters give you the freedom to request a highly customizable report.

Parameter
Description
Required

start

The start date for pulling data. Expected format is m/d/yyyy. If no start date is provided, start date is set to today.

No

end

The end date for pulling data. Expected format is m/d/yyyy. If no end date is provided, start date is set to today.

No

columns

A comma separated list of columns a user wants included in the report. Some column combinations may not be allowed (see section below for eligible columns depending on types).

Yes

includeEmptyRows

A boolean value to indicate whether you want to include rows that have no data.

No

name

The name that the zip file will be saved as.

No

Columns
The table below documents the columns you are allowed to query for based on the type of report that you generate. Flite Reporting API requires you to select all of the identity columns. The order that you specify for these columns in your request is the same order in which they will be returned when your report gets generated.

Step 2 - Get Report Info:

This endpoint will return a JSON object associated with the report request that was formed in the step above. This JSON object provides many forms of information, listed below.

  • processingStartDate: The date and time when the requested report job was kicked off.
  • processingEndDate: The date and time when the requested report job was completed.
  • resourceID: This is the guid parameter of your request. It identifies the resource for which your report is being processed.
  • status: The status of your report. The possible values for this field are:
  • subtype: The subtype specified in the request during step one. If type was not REPORT, and no subType was specified then this field will have the NOT_APPLICABLE value. For other values, look at the subType parameter section in step 1.
  • name: The name provided for your zip file to be saved as. If no name is provided, this field will be empty.
  • columns: The columns you requested in step 1.
  • format: The format you requested for your data in step 1.
  • type: The type of report you are trying to generate.
  • reportId: The guid of the report object in the Flite Reporting API that identifies your request. This is the same value that is returned in step 1. You will use the reportId to download your report once it’s complete.

URL

http://api.flite.com/rr/v1.0/data/report/info/{guid}

Sample Response

{
  "processingStartDate":"2015-03-13 18:42:58.0",
  "resourceId":"56298ef0-d28a-4ebe-96ed-0e7b449c202e3",
  "processingEndDate":"2015-03-13 18:42:59.0",
  "status":"COMPLETE",
  "subType":"NOT_APPLICABLE",
  "name":"demoReport",
  "columns":"impressions,engagements,interactions",
  "format":"CSV",
  "type":"AD",
  "reportId":"89fb56cd-dcae-4452-b33f-f5774b146117"
}

Step 3 - Retrieve Completed Report:

This is the third and final step in generating a report through the Flite Reporting API. Once the status of your report is COMPLETE you can use the endpoint below to download your report. Your report will be returned in the format that you requested.

URL

http://api.flite.com/rr/v1.0/data/report/download/{guid}

Sample Response(s)

Ad Name,Ad Id,Placement Size,Impressions,Interactions,Engagements,
Clickthroughs,Total Time on Unit (sec),Date FliteDemoAd,5bdc4f90-b8fd-46ba-
993f-fc3885ba548d,300x250,552731,50029,36144,120,155209,2014-04-16
FliteDemoAd,5bdc4f90-b8fd-46ba-993f-fc3885ba548,300x250,
520811,47445,34226,92,146684,2014-04-17 FliteDemoAd,5bdc4f90-b8fd-46ba-
993f-fc3885ba548d,300x250,533773,49285,35623,95,164693,2014-04-18
FliteDemoAd,5bdc4f90-b8fd-46ba-993f-fc3885ba548,300x250,
544699,48036.35066,134,156630,2014-04-19 FliteDemoAd,5bdc4f90-b8fd-46ba-
993f-fc3885ba548d,300x250,490541,44981.32948,166,156251,2014-04-20
FliteDemoAd,5bdc4f90-b8fd-46ba-993f-fc3885ba548d,300x250,
564268,50996.37055,132,164927 ,2014-04-21 FliteDemoAd ,5bdc4f90-b8fd-46ba-
993f-fc3885ba548d,300x250,566653,50093,36365,133,157203,2014-04-22

Querying the API for Resource Guids

You can use the Reporting API for retrieving the ids(guid) for Ads and Campaigns that belong to your organization. This way you can leverage the Flite Reporting API without having the need to login to the Flite Console to retrieve Ad or Campaign ids. The endpoint below will return a JSON object with an array that contains an object for each Ad or Campaign that belongs to the Organization.

Fetch Resource Ids URL

http://api.flite.com/rr/v1.0/data/fetch/{type}?start={startDate}&end={endDate}

*HTTP method type: GET

Example (when {type} is campaign)

http://api.flite.com/rr/v1.0/data/fetch/campaign

Example output for a request when {type} is campaign. Note that the output is going to look the same for both ads and campaigns, only the values will differ.

{
  "resources":[{
    "guid":"f90fcc73-30ac-4416-b1da-da4a08d3a075",
    "name":"BizCo Campaign"
  },{
    "guid":"c2985c9b-c0c4-4869-816f-44fe78ee659",
    "name":"Fall Campaign"
  },{
    "guid":"9c282360-063e-4737-8eb7-e55564bf4cf",
    "name":"Back to School Campaign"
  },{
    "guid":"981563e8-1094-4f56-9cae02d66b2204631",
    "name":"Summer Fun Campaign"
  }]
}

The following are the expected values for the {type} parameter.

Parameter:{type}
Description
Required (exactly one)

AD

Used for providing ad ids (guid) and its name.

Yes

CAMPAIGN

User for providing campaign ids (guid) and its name.

Yes

Query Parameters
The query parameters give you the freedom to request your resources based on creation dates in the Flite platform. If no query parameters are given, your entire data set will be fetched.

Parameter
Description
Required

start

The start date for pulling data. Expected format is m/d/yyyy.

No

end

The end date for pulling data. Expected format is m/d/yyyy.

No

Error messages in the Flite Reporting API

Error messages in the Flite Reporting API indicate that your request was unsuccessful. The errors are returned in a JSON object with the appropriate error code and an accompanying message.

These are the error messages that you may get:

  • authentication failed - with a status 401. This indicates that the user is unauthorized. In this case, check to see if your oAuth parameters are correct or that you haven’t exceeded the 5 second expiration timestamp that Flite utilizes for its API calls.
  • invalid url - with a status 400. This indicates that one or more of your path parameters contains an invalid value. If you have an incorrect resource guid in your API, you will also see this error.
  • invalid query parameters(s) - with a status 400. This indicates that your query parameters have an invalid value. Check to see if your query parameters have expected values and that the columns that you have specified in your report are correct.
  • unexpected error - with a status 500. Something went wrong on our end. Most likely, we are aware of the problem and are already working on it, but nevertheless please contact us and let us know.
  • invalid url or the requested report does not exist - with a status 400. This indicates that the report object that you are referring to does not exist. This error will occur if you try to get info or download a report with a report guid that is invalid.
  • report is not ready - with a status 404. This indicates that the report processing has not yet finished (i.e. report status is not COMPLETE) and it is therefore not ready for download.

Example error (JSON):

{"message":"invalid url",
"code":"400  Bad Request"}

Reporting API