Version(1.0.0)

Copyright � Africa Wildlife Tracking 2018

API Info

Introduction

Terms and Conditions
Fair usage Policy
Security/Fraud

Getting Started
Subscription
Session Token

Getting Client Info
Tag List
Unit List

Getting Tag Data
Live Data
Replay Data
History Data

Decrypting The Data

Decrypted Live Tag Data
Decrypted History Tag Data

How to use AWT Tracker API

Introduction

The AWT API (Application Programmer Interface) allows clients of Africa Wildlife Tracking [AWT] to periodically request live and historic data from our server.

Terminology

AWT - Africa Wildlife Tracking.
API - Application Programming Iterface.
Tag - Data Acquisition Equipment manufactured in the form of a collar, ear tag, back pack or implant for the animal.
Unit - Transceivers and Satellite Towers and other such devices that are used to transmit commands to and receive data from Tags via VHF\UHF.
VAP - Virtual Access Point – Virtual grouping of various tags under a client organization.
UTC - Universal Time Coordinated - the primary time standard by which the world regulates clocks and time.
EPOCH - is a system for describing a point in time, defined as an approximation of the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970.

API

The API consists of several PHP queries that will produce encrypted data on request in JSON format. The client application will have to decrypt the JSON Data for it to be of any use.

Live Data: A request for all new data not previously requested. This data, for a new session, will initially not be older than 10 minutes and thereafter as near to real time as possible.
Replay Data: A request for data for a specific time span up to a maximum of 90 days.
History Data: A request for data for a specific time span greater than 90 days. This query could potentially produce a very large data set therefore filtering constraints are mandatory.

Terms and Conditions

Please read these Terms and Conditions carefully before proceeding with your subscription and use of this API.

Fair Usage Policy

  • A fair usage policy will apply to users of this API.
  • Since the logging interval for most tags is set to a period longer than 10 minutes, requests for data from the API faster than one minute apart will result in a suspension of 1 hour.
  • Live, Replay and Historic queries are timed independently so there is no penalty if Live, Replay and/or Historic data is requested immediately one after each other.
  • Note that repeat offenders will be suspended indefinitely and that removal of this suspension is entirely at the discretion of AWT.
  • AWT reserves the right to amend the FUP as and when deemed necessary.
  • Security/Fraud Disclaimer

    While AWT will take every precaution to protect the security and confidentiality of your personal data and business information, AWT will in no way be held liable for any unauthorized access to data via the API as a result of a security breach.

    By subscribing to the API you automatically agree to all the terms and conditions imposed on this API.

    Getting Started

    Subscription

    To make use of the AWT API service, clients will need to make a once off call to the Subscribe function. If the subscription process is successful a Subscription Token will be passed back in the result. This token must be used as the Key to decrypt encrypted data sent back by the API. The client’s subscription will remain active for as long as the user remains a client of AWT. Misuse of the API however can result in either temporary or permanent removal of access. To subscribe to the API a call is made to the PHP function Subscribe and the client’s Username and Application Registration Code must be submitted as parameters.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/subscribe.php
    Method: POST
    Input Parameters:

    USR = User Name.
    RC = Application Registration Code.

    Result: Unencrypted JSON.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        Subscription_Token: "Unique string associated with a specific client"
    }
    
    

    Try it:

    Submit

    Session Token

    To be able to request data from the API a session token needs to be obtained. This token will be used in all subsequent calls to the API and needs to be renewed periodically at least once an hour. If the token expires, calls to the API will fail.

    To get a new token a call to the PHP Function token is made. Your Username and Password must be submitted as parameters. Note that your user password, initially chosen when registering either of our Windows PC or Mobile applications, can be changed online here.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/token.php
    Method: POST
    Input Parameters:

    USR = User Name. Supplied by AWT.
    PW = User password. Initially supplied by AWT. Can be changed online here.

    Result: Unencrypted JSON.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        Token: "Unique string associated with a specific client and current session"
    }
    
    

    Try it:

    Submit

    Getting Client Info

    Tag List

    To get a list of all the tags owned and routed to a specific client a call to the PHP Function taglist is made. The session token must be submitted as the only parameter.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/taglist.php
    Method: POST
    Input Parameters:

    ST = Session Token. Result of token function.

    Result: Unencrypted JSON.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        Tag_List: [
                    {id: 1256, type: "IM-SAT Tag"},
                    {id: 1323, type: "GS-SAT Tag"} 
                  ]
    }
    
    

    Try it:

    Unit List

    To get a list of all the units that is assigned to a specific client, a call to the PHP Function unitlist is made. The session token must be submitted as the only parameter.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/unitlist.php
    Method: POST
    Input Parameters:

    ST = Session Token. Result of token function.

    Result: Unencrypted JSON.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        Unit_List: [
             {id: 56, prefix: "AWTIRDMVAPU", type: Iiridium Satellite Virtual Access Point, label:"Some Label"},   
             {id: 67, prefix: "GAWTGSMVAPU", type: GSM Tag Virtual Access Point, label:"Some Label"}    
           ]
    }
    
    

    Try it:

    Getting Tag Data

    Live Data

    To get recent tag data a call to the PHP function data is made. The data query is designed to efficiently get new tag data and keep the data up to date on client systems. In most cases its is required to pass the session token as the only parameter when using the data query.

    Once a new session has been obtained and is passed as the only parameter to the data query, the query will return all data received for all tags during the last 24 hours. Any subsequent queries after that, no less than one minute apart, will return all the data received for all the tags since the last query.

    If a session token is left to expire i.e. not renewed within an hour then the process will resume by firstly returning 24 hours worth of data and then new data only.

    The system also caters for specifying two additional (Optional) parameters.
    a) Rollback Time
    b) Start Record Index

    When the Rollback Time parameter is specified the system will ignore its internally stored query parameters, that determines what data sub-set to return, and will return all data with a time stamp bigger or equal than the time specified by the rollback time.
    Caution: Take note that this is a time based query. Data is stored by the time the data was recorded by the device and not when it was saved in the database. Data can be recorded and only saved days later in the database. This is due to the fact that devices may not have satellite or gsm coverage at the time the data was recorded.
    By specifying this parameter the query will not return newly received “out of coverage” data unless the was recoded later than the given rollback time.

    When the Start Index is specified the query will return all data with a record index bigger or equal than the specified index.

    Caution:This query is not time-based. This will return all data received after the specified index. This could include data with older timestamps. The source of “new data” with older timestamps can be either out of coverage data or data that was downloaded from devices and then uploaded to the database.

    Note that there is a fair usage policy that apply to making periodic calls to this function. Make sure that you adhere to this policy.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/data.php
    Method: POST
    Input Parameters:

    ST = Session Token. Result of token function.
    RT = Rollback Time. (Optional)
    IND = Start Index. (Optional)

    Result: Encrypted JSON.

    Notice that the Actual Data Record will be an encrypted string. To get the data this string needs to be decrypted. Refer to the section on Decrypting The Data for details. The Decrypted Data will be in JSON format.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
      
    

    Example Result (Successful Call):

    
    {
        Result: true,
        IV: "Initial vector to decrypt the Cyphertext",
        Ciphertext: "Encrypted String"
    }
    
    

    Try it:

    Replay Data

    To retrieve data for a specific time span no older than 90 days from today, a call to the PHP function replay is made.

    The Session Token, as well as Start and Stop Times in UTC UNIX Epoch format, must be submitted as parameters. This query could potentially produce a very large data set therefore filter constraints are mandatory. Data can either be filtered by Tag or VAP. To filter on a Tag, specify the Tag’s ID and pass an empty string for the VAP ID. To filter on a VAP, specify the VAP’s ID and pass an empty string for the Tag ID. Note that data will be limited to 1000 records.

    Note that there is a fair usage policy that apply to making periodic calls to this function. Make sure that you adhere to this policy.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/replay.php
    Method: POST
    Input Parameters:

    ST = Session Token. Result of token function.
    T1 = Start Time. Epoch(UTC).
    T2 = Stop Time. Epoch(UTC).
    T = Filter Tag ID. (Optional)
    U = Filter Unit ID. (Optional)

    Result: Encrypted JSON.

    Notice that the Actual Data Record will be an encrypted string. To get the data this string needs to be decrypted. Refer to the section on Decrypting The Data for details. The Decrypted Data will be in JSON format.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        IV: "Initial vector to decrypt the Cyphertext",
        Ciphertext: "Encrypted String"
    }
    
    

    Try it:

    History Data

    To retrieve historic data for a specific time span older than 90 days, a call to the PHP function history is made. With this function data can be retrieved for the entire lifespan of a tag. Note that not all the data fields for tags are archived and will therefore not be available with this function call.

    The Session Token, as well as Start and Stop Times in UTC UNIX epoch format, must be submitted as parameters.

    This query could potentially produce a very large data set therefore filter constraints are mandatory. Data can either be filtered by Tag or VAP. To filter on a Tag, specify the Tag’s ID and pass an empty string for the VAP ID. To filter on a VAP, specify the VAP’s ID and pass an empty string for the Tag ID. Note that data will be limited to 1000 records.

    Note that there is a fair usage policy that apply to making periodic calls to this function. Make sure that you adhere to this policy.

    Function Call: https://api.africawildlifetracking.com/Scripts/php/api/history.php
    Method: POST
    Input Parameters:

    ST = Session Token. Result of token function.
    T1 = Start Time. Epoch(UTC).
    T2 = Stop Time. Epoch(UTC).
    T = Filter Tag ID.
    U = Filter Unit ID.

    Result: Encrypted JSON.

    Notice that the Actual Data Record will be an encrypted string. To get the data this string needs to be decrypted. Refer to the section on Decrypting The Data for details. The Decrypted Data will be in JSON format.

    Example Result (Failed Call):

    
    {
        Result: false,
        Reason: "Whatever the reason"
    }
    
    

    Example Result (Successful Call):

    
    {
        Result: true,
        IV: "Initial vector to decrypt the Cyphertext",
        Ciphertext: "Encrypted String"
    }
    
    

    Try it:

    Decrypting The Data

    
    //------------------------------------------------------------------------------------------------------------ 
    //PHP compatible decryption algo
    //------------------------------------------------------------------------------------------------------------  
        function decrypt(cypher_text, keyIn, IVIn){
                var iv = CryptoJS.enc.Hex.parse(IVIn);
                var key = CryptoJS.enc.Hex.parse(keyIn); 
                var ct = CryptoJS.enc.Base64.parse(cypher_text); 
                var decrypted = CryptoJS.AES.decrypt({ciphertext: ct, salt: ""}, key, {iv: iv}).toString(CryptoJS.enc.Utf8);
                return decrypted;
        }
    
    //------------------------------------------------------------------------------------------------------------ 
    //Usage: 
    //------------------------------------------------------------------------------------------------------------  
        var ResultObj = JSON.parse(Result); //Result for PHP call
        if (ResultObj.Result === false){
                alert('Error: ' + ResultObj.Reason);
        } else if (ResultObj.Ciphertext === ""){
                alert('No data available.');
        } else {   
                var key = SubscriptionToken; //Your Subscription Token is used as the key.
                var decrypted = decrypt(ResultObj.Ciphertext, key, ResultObj.IV);
        }
    

    Decrypted Live Tag Data

    The following example depicts two JSON records returned by the History function.
    Each record contains the following fields:

    Note in some cases some values for fields will not be available and will be indicates as "Unknown".

    
    {
        [
            {
                record_index: 1234,  
                unit_id:"AWTIRDMVAPU774",
                tag_id:1000,
                alarms: {
                            Track Mode: false,
                            Battery: false,
                            Geofence: false,
                            Coverage: false,
                            Memory: false,
                            CBit: false,
                            Movement: "Unknown",
                            Tamperfoil: false
                        },
                batt: 3.6,
                temperature: 32,
                timestamp:1536852710,
                lat: -12.18578,
                lon: 54.726135,
                dop: 1,
                speed: 0,
                accelerometer: {
                                    X: 7475,
                                    Y: 3601,
                                    Z: 2099
                                },
                log_interval: "Every 1 hour"
        },
        {
                unit_id: "AWTIMCVAP743",
                tag_id: 1224124,
                alarms: {
                             Track Mode: false,
                             Battery: false,
                             Geofence: false,
                             Coverage: true,
                             Memory: false,
                             CBit: false,
                             Movement: "Unknown",
                             Tamperfoil: false
                        },
                batt: 7,
                temperature: "Unknown",
                timestamp: 1536863432,
                lat: -37.926348333333,
                lon: 29.843266666667,	
                dop:0,
                speed:0,
                accelerometer: {
                                    X: "Unknown",
                                    Y: "Unknown",
                                    Z: "Unknown"
                                },
                log_interval:"Off"
            }
        ]
    }
    

    Decrypted History Tag Data

    The following example depicts two JSON records returned by the History function.
    Each record contains the following fields:

    Note in some cases some values for fields will not be available and will be indicates as "Unknown".

    
    {
       [		
            { 
                unit_id: "AWTLORAVAP821",
                tag_id: 12345,
                temperature: "Unknown",
                timestamp: 1536092821,
                lat: -21.95453,
                lon: 34.76556,
                dop: 1,
                speed: 0,
                accelerometer:  { 
                                    X: "Unknown",
                                    Y: "Unknown",
                                    Z: "Unknown"
                                }
            },
            {
                unit_id: AWTLORAVAP741,
                tag_id: 2929,
                temperature: "Unknown",
                timestamp: 1536100651, 
                lat: -45.34562833,
                lon: 34.76562,
                dop: 2,
                speed: 0,
                accelerometer: {
                                    X:"Unknown",
                                    Y:"Unknown",
                                    Z:"Unknown"
                                }
            }
        ]
    }