API Overview
Overview Of Our External REST API
- - 100% Secure HTTP Protocol Communication (SSL)
- - Compact Response Format (JSON)
- - High Performance, Concurrent, Fault Tolerant.
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:
https://www.avantalytics.com/REST/.
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 (support@avantalytics.com) to discuss the options.
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
request.
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.
{
"curr_time": 1540226339,
"success": 1,
"error": 0,
"msg": "The operation was successful.",
"permission": 1,
"finished": 1,
"start_time": 1540226337,
"authenticated": 1,
"msec": 1573,
"result": [...]
...
}
Additional fields may be provided depending on the API target being called.
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 and
error to
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
- - PHP Request Example
$url='https://www.avantalytics.com/REST/test/';
$qry_str = ""; // additional fields go here
$ch = curl_init();
// Set query data here with the URL
curl_setopt($ch, CURLOPT_URL, $url . $qry_str);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, '3');
$json = trim(curl_exec($ch));
curl_close($ch);
$jsonObj=json_decode($json);
... //treat jsonObj like a stdClass object!
- - Ruby Request Example
require 'rest_client'
url='https://www.avantalytics.com/REST/test/'
json = RestClient.get url
jsonObj = ActiveSupport::JSON.decode(json)
- - ASP Request Example
var uri='https://www.avantalytics.com/REST/test/';
var webReq = (HttpWebRequest)WebRequest.Create(uri);
webReq.KeepAlive = false;
webReq.Timeout = 30000;
webReq.PreAuthenticate = false;
using (WebResponse webResponse = webReq.GetResponse())
{
using (Stream responseStream = webResponse.GetResponseStream())
{
if (responseStream != null)
{
using (var reader = new StreamReader(responseStream))
{
string jsonStr = reader.ReadToEnd();
' now unserialize your using your favorite
' json deserialize method
' ours is flexjson.sourceforge.net
}
}
}
}
- - cURL Request Example
$ curl https://www.avantalytics.com/REST/test/
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.