This article has moved to our new Help Center:
https://help.angelfishstats.com/helpdesk/KB/View/48621499-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
Make a POST request to /api/token/request with a valid Angelfish username and password in the Body. The data in the Body needs to begin with "data=" (no quotes) and will fail if it's not present.
Here's an example of what this should look like:
POST URL: https://10.1.2.33:9000/api/token/request
Body: 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"}
401 Response: Invalid Credentials
If an invalid username and/or password is provided, the API will return a 401 status code.
403 Response: 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.
405 Response: Method Not Allowed
If the username & password are passed as a query parameter instead of in the body, you'll receive a response of 405: Method Not Allowed.
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
0 Comments