Report Web Service Guide

Introduction

The report web service provides programmatic access to all the reports within the application. Our web service implementation uses standard internet protocols and can be called using most major development languages, including all Visual Studio languages, Java and PHP. You can use the report web service to create custom dashboards or a variety of other interfaces that access report data.

In addition to accessing report data, chart image files are also available through the web service.

Our philosophy on the architecture of the report web service is to provide a simple, unchanging interface that provides access to all the reports within the application. Since the number of reports available and the data within the reports are constantly changing, we have created an interface specification that is generic and will not need to be updated every time the data format changes.

Background

The report web service is based on industry standard technology, such as SOAP and WSDL. For background information on these technologies, please refer to the following link:

W3C Web Services Information

Implementation

The web service is implemented by referencing our WSDL file in your development environment. The method of doing this is dependent upon your development tool. The WSDL file can be referenced from the URL below:

http://opera.hitslink.com/reportws.asmx

The service description can be viewed from the following link:

View service description

The WSDL definition can be viewed from the following link:

View WSDL definition

The report web service supports transport-level security (SSL).

Function Reference

Function	Description	Parameters	Returns
GetData	Get an array of report data and an array of column definitions.	account - The account id of the account to retrieve the data from. password - The password of the account. This information is transmitted securely over the internet. reportId - The report id of the report. Select this from the enumerated list. maxRows - The maximum number of data rows to return. There is a limit of 1000. chartHeight - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure. chartWidth - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure.	This call returns the 'Data' structure. See the section below on the definition of the 'Data' structure.
GetDataFromTimeframe	Get an array of report data and an array of column definitions for a specific date range. If the report does not use timeframes, this call will function the same as GetData.	account - The account id of the account to retrieve the data from. password - The password of the account. This information is transmitted securely over the internet. reportId - The report id of the report. Select this from the enumerated list. Timeframe Type - Daily, Weekly, Monthly, Quarterly, or Yearly. Select this from the enumerated list. Start Date - The start date of the report. End Date - The end date of the report. maxRows - The maximum number of data rows to return. There is a limit of 1000. chartHeight - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure. chartWidth - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure.	This call returns the 'Data' structure. See the section below on the definition of the 'Data' structure.
GetDataFromQueryString	Get an array of report data and an array of column definitions by passing in a query string. For complex report settings, the browser's query string contains the complete report definition. This function accepts a query string to determine the report data to retrieve. For example, if a report has multiple filters and a custom sorting, the standard GetData call cannot be used.	account - The account id of the account to retrieve the data from. password - The password of the account. This information is transmitted securely over the internet. queryString - The query string after the ? on the browser's address line for a report you wish to retrieve data on. chartHeight - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure. chartWidth - If this is set to a value greater than zero, a chart will be generated and the url of the chart will be returned in the 'Data' structure.	This call returns the 'Data' structure. See the section below on the definition of the 'Data' structure.

Return Structure

All calls return a structure called 'Data', which is a simple class with three properties and two arrays. The first array is called ColumnDefinitions, which contains meta data on the columns returned by the call. The second array is an array of rows representing the report data. This array is called 'Rows'.

The structure of the Data class (in VB.NET syntax) is:

Public Class Data
    Public Title As String
    Public EndDate As Date
    Public StartDate As Date
    Public ChartURL As String
    Public ColumnDefinitions As ColumnDefinition()
    Public Rows As Row()
End Class

The ColumnDefinition class is defined as:

Public Class ColumnDefinition
    Public Title As String
    Public Align As AlignmentTypes  '    Left, right or centered on report output
    Public Sortable As Boolean
    Public DataType As DataTypes
End Class

The AlignmentTypes enumeration is defined as:

Enum AlignmentTypes
    Left
    Right
    Center
End Enum

The DataType enumeration is defined as:

Public Enum DataTypes
    DataTypeString = 0
    DataTypeInteger = 1
    DataTypeNumeric = 2
    DataTypeCurrency = 3
    DataTypePercent = 4
    DataTypeDate = 5
End Enum

The Column class is defined as:

Public Class Column
    Public Value As String
End Class

The Row class is defined as:

Public Class Row
    Public Columns As Column()
End Class

Sample Code

The following are samples of code to retrieve report data. The first example is written in ASP.NET using the VB.NET language.

First, import the web reference into your project and call it 'Analytics'.

'------------------------------------------------------------------------------------
'   REPORT WEBSERVICE SAMPLE CODE (ASP.NET using VB.NET)
'
'   This sample makes a webservice call to retrieve the Browser Versions report 
'   data and displays the output in a table.
'
'   This sample depends on having the WSDL file imported into the development 
'   environment.
'------------------------------------------------------------------------------------

'   ReportWS is the webservice name found in the WSDL file
Dim ws As New Analytics.ReportWS

Dim i As Integer, j As Integer

Try
    Dim rptData As Analytics.Data    ' The data structure returned by the webservice call

'   Call the webservice and retrieve the report data 
    rptData = ws.GetData("YOUR ACCOUNT ID", "YOUR PASSWORD", _
        Reports.ReportsEnum.BrowserVersions, 10, 0, 0)

Response.Write("<table><tr>")

'   Loop through the column definitions returned and display their titles
    For i = 0 To rptData.ColumnDefinitions.GetUpperBound(0)
        Response.Write("<td>" & rptData.ColumnDefinitions(i).Title & "</td>")
    Next

Response.Write("</tr>")

'   Now loop through the report data and output it
    For j = 0 To rptData.Rows.GetUpperBound(0)
        Response.Write("<tr>")

For i = 0 To rptData.ColumnDefinitions.GetUpperBound(0)
            Response.Write("<td>" & rptData.Rows(j).Columns(i).Value & "</td>")
        Next

Response.Write("</tr>")
    Next

Catch ex As Exception
    Response.Write(ex.Message)
End Try

This example is in PHP:

<?
//------------------------------------------------------------------------------------
//   REPORT WEBSERVICE SAMPLE CODE (PHP)
//
//   This sample makes a webservice call to retrieve the Browser Versions report 
//   data.
//
//------------------------------------------------------------------------------------

$username = "";	// Your account id
$password = "";	// Your account password

// The report you would like returned.
// See description (http://www.hitslink.com/reportWS.asmx)
$reportID = "";
$maxRows = "";   // The number of Rows you would like returned
$chartHeight = "";   // The height of the chart generated
$chartWidth = "";    // The width of the chart generated

$params = array("account" => $username, // Create a wrapper array for SOAP params
  "password" => $password, 
  "reportId" => $reportID, 
  "maxRows"  => $maxRows, 
  "chartHeight"  => $chartHeight, 
  "chartWidth"  => $chartWidth);

// Instantiate the soapclient, pass it the WSDL location
$client = new soapclient("http://www.hitslink.com/reportWS.asmx?WSDL");

Try
{
    // Call the GetData WS Function, parse and display to taste.
    $return = $client->GetData($params);
    print($return->GetDataResult);
}
catch(Exception $e)   // Handle Exceptions Here
{
print("Exception Occurred, Handle it here.");
}
?>

How to access specific columns

The numeric index of columns can change, so do not hard code the index when accessing specific columns. If you need to access specific columns, use the following method:

For example, if you need to directly access the 'Bounces' column (C# example):