Urchin Data API FAQ
How do I extract data using the Urchin API?
First, choose whether you want to use REST or SOAP. To make a REST request, you simply need a URL with valid query arguments. For example, to extract a list of profiles, you would make the following request:
http://your_host:your_port/services/v1/adminservice/accounts/?login=URCHIN_LOGIN&password=URCHIN_PWD
To learn how to extract data using SOAP, refer to Samples for Java (SOAP) v1.
How do I extract data from multiple profiles?
The Urchin API provides programmatic access to data from all profiles for the authenticated user. You'll need to invoke multiple requests using different profile ids as arguments. For example, you'd invoke the following two requests to extract the visitor ids from profiles 1 and 2:
http://your_host:your_port/services/v1/reportservice/data?login=URCHIN_LOGIN&password=URCHIN_PWD&ids=1&start-date=2009-01-01&end-date=2009-02-01&dimensions=u:visitor_id http://your_host:your_port/services/v1/reportservice/data?login=URCHIN_LOGIN&password=URCHIN_PWD&ids=2&start-date=2009-01-01&end-date=2009-02-01&dimensions=u:visitor_id
Can I import data into Urchin using the API?
No. This version of the API does not provide a way to import data into Urchin.
Why does Firefox return "Access to restricted URI denied (NS_ERROR_DOM_BAD_URI)"?
A browser "same origin policy" prevents access to methods and properties across pages on different sites. However there are several workarounds, such as using a webproxy, iframes and apach mod_rewrite. Search "cross-domain ajax" on Google for more information.
How do I configure a webproxy to get around the "same origin policy"?
Use a CGI, PHP, Python or other script that wraps cross-domain Ajax calls and makes the resulting data local to the requesting domain. Search "web proxy script" on Google for more information.
Where can I find a list of all the available metrics and dimensions?
For information on metrics, see Metrics and Units v1. For information on dimensions, see Dimensions v1.
What is an Urchin table?
In Urchin, a table stores processed (and sometimes raw) data from access logs. All Urchin tables are listed and described in the lib/reporting/profiletypes/Default/datamap.dm2 file. You can only extract data from one table per API call. You cannot request a more broad combination of dimensions and metrics than what is represented in the datamap.
You can extend existing set of tables. For more information, see Custom Data Maps. New tables automatically become available to API users and are discoverable via the getTableList method for SOAP, and getTableList method for REST.
Can I integrate the Urchin Data API with IIS?
Yes. See Can I integrate the Urchin Data API with IIS?.
How do I integrate with Apache?
By default, Urchin is bundled with working instance of the Data API under Apache web server. The Apache module is provided in the dist/lib/api/v1 directory.
SOAP services are discoverable via the following requests:
http://your_host:your_port/services/v1/reportservice?wsdl
and
http://your_host:your_port/services/v1/adminservice?wsdl
REST methods are discoverable via the following requsts:
http://your_host:your_port/services/v1/reportservice
and
http://your_host:your_port/services/v1/adminservice
Can I encrypt my login and password before passing them to the REST services?
Yes. Use SSL-enabled Apache or IIS. For details, refer to How do I activate SSL on the Urchin Webserver?.
How do I enable the Data API over SSL?
Once SSL has been activated, the API will handle requests over SSL. For details on activating SSL, refer to How do I activate SSL on the Urchin Webserver?
What are the main configuration files for the Data API?
The Data API depends on the following configuration files:
- etc/urchin.conf - general settings and connection to configuration database
- etc/session.conf - authentication settings
- var/urchinwebd.conf.template - apache module settings
- lib/api/v1/axis2.xml - common library settings
How do I disable the Urchin Data API?
The Data API is enabled by default. To disable it, stop the Urchin webserver, go to var/urchinwebd.conf.template, comment out the line "LoadModule axis2_module lib/api/XXXApiVersionXXX/mod_axis2.so" and start or restart the Urchin webserver.
How do I switch to another version of the Urchin Data API?
By default, Urchin will switch on the most recent version of the Data API. To enable older version of the API, create new entry in etc/urchin.conf "DataApiVersion: N" and restart the Urchin webserver.
Can I disable authentication?
Yes. The Data API inherits the Urchin session controller authentication settings from etc/session.conf. For details on how to bypass authentication, refer to Using External Authentication or Authentication Bypass.
Where are the API error logs stored?
By default API errors are stored in the var/api.log file. To change default settings and/or error level, see "Can I integrate with IIS?" in this FAQ and the following Help Center article. See Error Handling v1.
How many requests can the API handle?
Environment: linux 2.6, 3 GHz CPU, 2 GB RAM
Average saturation point for the Data API methods are:
- dates period - 1 month
- log size - 300 MB, method IP+User agent
- concurrent users - 400
- hit rate - 80 hits/sec
- response time - 15 milliseconds
- throughput - 320 KB/s
Average saturation point for getData() method (huge log with 10M visitors):
- dates period - 2 years
- log size - 5 GB, method UTM
- concurrent users - 30
- hit rate - 4 hits/sec
- response time - 1 sec
- throughput - 1.5 MB/s
Performance is limited by the following two settings:
- maximum concurrent connections to the MySQL/Postgres database
- maximum sockets on Apache/IIS
To boost the performance, these limits have to be extended.
Can I provide unrestricted API access to my data?
Yes, at your own risk. If you intend to provide access to the world, we recommend that you use an SSL-enabled webserver with the most recent security updates.
Which authentication mechanism does the Data API use?
The Data API inherits the Urchin session controller authentication settings from etc/session.conf.
Does the authentication session expire?
No. The user is authenticated during each call; the Data API doesn't use sessions.
Why must I provide a login and password during each call?
Since the Data API doesn't use sessions, each call requires authentication.
How do I extract data from custom datamaps?
The Data API automatically exposes newly created custom datamaps. Use the getTables() method (in the report service) to retrieve a set of all the available datamaps and their dimensions/metrics.
Here is a sample scenario illustrating how to extract data from a custom datamap:
- Create a new profiletype lib/custom/profiletypes/mycustom1.
- Copy the default.dm2 and default.rs2 files from lib/reporting/profiletypes/default to mycustom1.
- Modify default.dm2 by adding a new datamap entry #40 with dimensions 140 and metrics 5,6,7.
- Call the getTables() method - it will return old tables and new #40 with dimensions 140 and metrics 5,6,7.
- Call getData() method with table_id=40 (or without a table_id if your combination of dimensions/metrics is unique across all tables).