Avantalytics External API Documentation v3.26

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.