Follow

API Overview

Internally, Angelfish uses a RESTful API for all data requests. Externally, 3rd party applications and scripts can request data from the same API.

Requests from 3rd party applications & scripts must contain 3 components:

  • the data parameters
  • a valid username
  • a signature

 

DATA PARAMETERS


Required Parameters

ids
The Profile ID to use for the data query - you can view a profile's ID in the summary tab of the Profile's settings. The Profile ID must exist and username used in the request must be able to access the Profile.

start-time
Accepts a date in YYYYMMDD format. Will use the timezone offset specified in the Profile's settings.

end-time
Accepts a date in YYYYMMDD format. Will use the timezone offset specified in the Profile's settings.

username
This is the username used to authenticate to Angelfish.  The username must be able to access the Profile ID referenced in the ids parameter.

 

Optional Parameters

dimensions
Passed as a comma-separated list. See the API Field Reference: Dimensions article for a list of valid dimensions.

metrics
Passed as a comma-separated list. See the API Field Reference: Metrics article for a list of valid metrics.

format
May be one of the following values.
json  (JSON format - this is the default value if format is not specified)
xml   (XML format)
csv   (Comma-separated format)
tsv   (Tab-separated format)
jsonfields   (JSON format with the dimension/metric names as object keys and their values as the object values)

start
The result index to start at. Must be greater than or equal to 1. Default: 1.

max-results
The maximum number of results to return, starting at start. Default: 1000.

sort
A comma-delimited list of fields to sort by, in order. Specifying a single field will sort the results by the field in ascending order. Putting a minus (-) sign in front of a field will sort the results by the field in descending order.

Example: sort by visits first, then pageviews in descending order

...&sort=visits,-pageviews&...

filters
A list of fields, conditions, and condition match values for filtering the results returned. The field, condition expression and value of each filter MUST be url encoded. A field may only be specified once.

Dimension Filter Conditions (evaluated as strings)

Condition Expression Description
== Dimension value must match exactly.
!= Dimension value must not match the exact string.
=~ Dimension value contains the specified value.
!~ Dimension value does not contain the specified value.

Metric Filter Conditions (must be numeric)

Condition Expression Description
== Metric value equals
!= Metric value does not equal
> Metric value is greater than
< Metric value less than
>= Metric value greater than or equal to
<= Metric value less than or equal to

Example:  Only show results where the source contains google and the visits are greater than 5

....&filters=source%3D~google,visits%3E5

 

SIGNATURE


The signature is an alphanumeric string, created by a hashing function and appended to the data request. A valid authentication token is required to generate the signature.

1) Generate Token

The token is requested with a valid username and password from the Angelfish server, and the token is used by the hashing function.

Tokens can be re-used indefinitely but we recommend revoking the token after a single session. Alternatively, you can also define a token expiration value (in minutes) in agf.conf.

Request a New Token

A POST request is made to "<Angelfish server>/api/token/request" with a valid Angelfish username / password (e.g. somedude / itsasecret), like this:  

data={"username":"somedude","password":"itsasecret"}

 

Token Generated Successfully

If the user credentials pass, a JSON response is returned with the requesting username and newly-generated token:

{"username":"somedude","token":"1234ABCDefgh"}

 

Invalid Credentials

If an invalid username and/or password is provided, the API will return a 401 status code.

 

API Tokens Not Allowed

API will return a response with a 403 status code if API tokens are not allowed for the Angelfish instance. Tokens are enabled by default, and can be disabled by the "allow_tokens" variable in agf.conf.

 

2) Generate Signature

The signature is generated by passing the token and the full request (i.e. data parameters and username) through a hash function.

The following steps must be performed IN ORDER:

  • Order all parameters (including username) by parameter name, ascending.
  • Concatenate all name/value pairs into a single string
  • Pass the string and token to the hash function
  • Attach signature to POST

 

Example: make an API request with the following details:

start-time=20131025
end-time=20131031
dimensions=source
metrics=visits
format=tsv
ids=1234
username=somedude (this is the account used to login to Angelfish)

 

Add Username, Order Parameters

We add the username to the parameters and put them in ascending order:

dimensions=source
end-time=20131031
format=tsv
ids=1234
metrics=visits
start-time=20131025
username=somedude

 

Concatenate into a single string

Place an equal sign (=) between the names and values.

dimensions=sourceend-time=20131031format=tsvids=1234metrics=visitsstart-time=20131025username=somedude

(the above should be a single unbroken string, i.e. no spaces or EOL characters)

 

Pass string and token to hash function

The hash function uses HMAC MD5, base 64 encoded, and returns a signature string. Below are links to hash functions written in Perl and PHP, or you can write your own in your language of choice.

Signature Hash Function: PHP
Signature Hash Function: Perl

From our perl example, we'd get the signature like this:

my $hmac = Digest::HMAC_MD5->new("1234ABCDefgh");
$hmac->add("dimensions=sourceend-time=20131031format=tsvids=1234metrics=visitsstart-time=20131025username=somedude");
my $signature = $hmac->b64digest;
# $signature will be something like pZP3dwZlrNtc3RSmoQoH/Q

 

Attach signature to POST

When the signature is attached, the request data will look something like this (signature will vary):

data={"ids":"1","start-time":"20131025","end-time":"20131031","format":"tsv","dimensions":"source","metrics":"visits","username":"somedude","signature":"pZP3dwZlrNtc3RSmoQoH/Q"}

 

Make Request

POST the request data to your Angelfish server at http://SERVER:PORT/api/data

 

EXAMPLE SCRIPT: FULL API REQUEST


http://support.angelfishstats.com/entries/84296067-Sample-Perl-Script-Full-API-request

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.