Benefits Of Our External REST API
- - 100% Secure HTTP Protocol Communication (SSL)
- - Compact Response Format (JSON)
- - Speed - 100msec Targeted Avg. Response Time*
Avantalytics provides customers who purchase services access to certain API methods for the purposes of better
integrating the data with the customer's in-house and/or third party systems. This documentation describes the
available API calls and necessary parameters and return values. Currently all API output is only available via JSON
format as described below. See below for details.
Base URL Access
All access to the external API can be reached only through the following address:
For all URLs listed below it is assumed that they are relative to this address. Please note, it is case sensitive.
Customer Specific Security Access Tokens
All API calls below require you to use your unique customer access token in order to receive meaningful responses.
This should have been given to you, by us, during the initial API access discussions or during account signup. If you do not have one yet,
please contact Avantalytics support (firstname.lastname@example.org) to discuss the options.
In addition, all API calls require your account ID as part of the request.
These two keys together, if they match will provide access to the API calls to which you've been granted access, depending on your account settings.
API Standard Responses
All API calls to registered API URLs will always respond with an HTTP response code 200. Because access is managed
within the application layer, the response body itself will determine whether the call actually succeeded or not. The
only exception to this rule is a 404 HTTP response code, which will be returned if you provide a mal-formed REST
Every API call will provide the following fields providing some
information detailing whether the result was successful and/or limited based upon permissions.
The output fragment below shows the response portion relating to a succesful API call. Please note: an API call is
considered sucessful from a REST status - even if the data it returns signifies an error occured. In this way, we treat
the success of the application call separately from the success of the HTTP response. So, the code below is a successful REST
API call, even if the error field value below was "true". It is your job to use the results of these standard fields to determine
whether your application should continue it's processing.
NEW 7-21-2013: We now provide an additional field in responses shown above 'msec' which is the number of milliseconds execution time per point returned
"html": "The operation was successful.",
"msg": "The operation was successful.",
We recommend checking each of these in your application handling logic before relying on the output that follows.
Also note - it is possible for success
have different boolean codes. The permission
field returns true if your account has
been granted access to this API call or the underlying functions supporting it. The authenticated
field, by contrast, only tells you whether you have authenticated correctly - a false value here will indicate in incorrect apikey/accountid
combination. If this happens, the API will throttle itself to one request every 3 seconds until a correct combination
has been submitted. It does this to avert DDoS attacks by potential attackers.
Simple Test GET Request Usage Examples
The examples above are meant to provide you with the minimal request/response for several popular
languages. In all cases you should arrive with a json serialized string which you should deserialize into
and object or array for consumption.