Urchin Data API v2 Services

Overview

The Urchin Data API v1 provides entry level data mining capabilities - aggregates, custom tables, totals, visitor and transaction details. Along with sorting and pagination, it introduces basic regular expression and numeric filters.

The Urchin Data API v2 significantly extends the analysis machinery introducing visit, path and transaction segmentations. It now becomes possible to specify up to 50 filters of each type per single query and squeeze the most valuable data out of the reporting database.

Introduction to the Urchin Data API v2 Web Services

Urchin 7.0 is bundled with v1 and v2 instances of the Data API. V2 is the default, although the API can be easily switched back to v1 by setting DataApiVersion? to 1 in <urchin_home>/etc/urchin.conf.

WSDL location:

AdminService:  http://your_host:your_port/services/v2/adminservice?wsdl
ReportService: http://your_host:your_port/services/v2/reportservice?wsdl   

REST methods URIs:

AdminService: http://your_host:your_port/services/v2/adminservice
ReportService:http://your_host:your_port/services/v2/reportservice

REST services explorer is also available at http://your_host:your_port/uapi.html

The Report Service allows to extract the following information:

• Aggregate dimensions and metrics - tables from #1 to #43
• Custom tables - user defined tables from <urchin_home>/lib/custom folder
• Visit related dimensions and metrics - table #256
• Transaction related dimensions and metrics - table #257
• Page related dimensions and metrics - table #259
• Totals and metrics over time - table #258

Data API v2 Reference

Admin service (v2)

The Admin service provides operations for retrieving account and profile information.

WSDL location: http://your_host:your_port/services/v2/adminservice?wsdl

This service provides the following methods:

• getAccountList - Method was not changed and works as described in the v1 version. To see more information please refer to the article | Data API?].
• getProfileList - Method was not changed and works as described in the v1 version. To see more information please refer to the article | Data API?].

Report service (v2)

The Report Service lets you extract data and generate reports from Urchin.

WSDL location: http://your_host:your_port/services/v2/reportservice?wsdl

This service provides the following methods:

• getTableList - Method was extended with new fields "nregexfilters" and "nnumericfilters".

Sample response:

<tns:getTableListResponse xmlns:tns="https://urchin.com/api/urchin/v2/">
<table>
<tableId>257</tableId>
<dimensions>
  <dimension>u:transaction_id</dimension>
  ...

</dimensions>
<metrics>
  <metric>u:transactions</metric>
  ...
</metrics>
<nregexfilters>50</nregexfilters>

<nnumericfilters>50</nnumericfilters>
</table>
</tns:getTableListResponse>

This response shows that Urchin table #257 can be filtered by 50 numeric and 50 regular expression filters. For more information, please refer to the help article Data API.

• getData - Beginning with v2, the method fully supports regular expression and numeric filters. For more information, please refer to the help article Data API.

Filtering gears

• tables ##1-43 - tables contain aggregated dimensions and metrics, support filtering by dimensions and metrics from the queried table only
• table #256 - the table contains all visit details, supports filtering by visit, transaction and path dimensions from tables #256, #257, #258; visit metrics from table #256
• table #257 - the table contains all transaction and visit details, supports filtering by visit, transaction and path dimensions from #256, #257, #258; transaction metrics from table #257
• table #258 - the table contains total data and metrics over time, supports filtering by metrics from table #258 only
• table #259 - the table contains all page and visit details, supports filtering by visit, transaction and path dimensions from #256, #257, #258; page metrics from table #259

Note: In order to see all available dimensions and metrics of these tables, please retrieve information via the method "getTableList" of the Report Service or refer to services explorer at http://your_host:your_port/uapi.html.

For example: extract visit details using REST request.

Sample REST request:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01
&dimensions=u:session_id,u:visitor_id,u:session_ip,u:session_start_time,u:session_end_time&metrics=u:pages,u:visits&table=256

Sample REST response:

<tns:getDataResponse xmlns:tns="https://urchin.com/api/urchin/v2/">
<record>

  <recordId>1</recordId> 
<dimensions>
  <dimension name="u:session_id">1262784738</dimension> 
  <dimension name="u:visitor_id">HWH2-C43FX-GSPE</dimension> 
  <dimension name="u:session_ip">10.6.28.81</dimension> 
  <dimension name="u:session_start_time">2010-01-06T07:32:37-08:00</dimension> 
  <dimension name="u:session_end_time">2010-01-06T07:32:49-08:00</dimension> 

</dimensions>
<metrics>
  <u:pages xmlns:u="https://urchin.com/api/urchin/v2/">1</u:pages> 
  <u:visits xmlns:u="https://urchin.com/api/urchin/v2/">1</u:visits> 
</metrics>

</record>
</tns:getDataResponse>

Query Examples

Get visits from yahoo.com where more than one page has been visited and order by visitor ID:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01
&dimensions=u:visitor_id,u:session_ip,u:utm_campaign&metrics=u:pages,u:visits,u:transactions&sort=u:visitor_id&filters=u:utm_source%3D~yahoo,u:pages%3E1&table=256

Get visitors from google.com and number of bookings they conducted:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01

&dimensions=u:visitor_id&metrics=u:pages,u:visits,u:transactions&filters=u:utm_source%3D~google,u:request_stem%3D~cart.html&table=256

Get all transactions resulting from bing.com searches for a given term:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01
&dimensions=u:transaction_id&metrics=u:transactions,u:revenue,u:tax,u:shipping,u:items&filters=u:utm_source%3D~msn,u:utm_term%3D~schwag&table=257

Get daily metrics for a given period:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01

&dimensions=u:day&metrics=u:pages,u:visits&table=258

Get all pages visited by a given visitor during a period of time:

http://<urchin host>:<port>/services/v2/reportservice/data?login=admin&password=urchin&ids=7&start-date=2008-01-01&end-date=2010-01-01
&dimensions=u:request_stem&metrics=u:pages&filters=u:visitor_id%3D~N8T3-DU4N9-7RPL&table=259

How to enable the older version of the Urchin Data API in Urchin 7.0

By default, newly installed or upgraded instances of Urchin 7.0 use the latest version of the Data API. To switch to another version, please refer to section "How do I switch to another version of the Urchin Data API?" of the article Urchin Data API FAQ.