allGeo API User Guide
This article describes how to use allGeo APIs to retrieve data from the allGeo system for integration with a Transportation Management System, Payroll system or an ERP system.
Before the APIs can be used, following settings must be configured for the account. These settings are configured by the allGeo administrator from Abaqus.
Enable API Access at the account level
Whitelist IP addresses to restrict API request origination from a specific IP Address or range.
Here is the common sequence of API calls that can be made once the API settings are complete.
Make login API call with account, Username and Password. If the call is successful, user is authenticated and a Token value is returned in the response.
Make non login API calls with token=<token value from login> request parameter along with other required parameters. Every API returns a JSON response with 2 fixed keys in it. They are status with an Integer value indicating the status of the request (0 = success) and message with a String value indicating success or failure reason. There may be other attributes depending on the API and they are documented in the API specification.
Let us walk through an example where the user wants to do the following. Let us also assume that we are conducting this exercise in demo account.
The first step in the exercise is the request API access from Abaqus.
We will request allGeo Administrator to enable API access for account ‘demo.’
We will not whitelist an IP Address or IP Address Range (less secure) so that we can make API calls from anywhere.
From a functional standpoint, we’ll do the following using APIs.
Add a device to allGeo system
Get the list of devices in the account.
Fetch last location of all the devices every hour from 10:00 AM to 02:00 PM
To achieve above stated functionalities here is the sequence of API call we have to make.
1. Login to allGeo via API
Request Method: POST
API Parameters:
So, the API call will look like https://www.mygeotracking.com/track/api/v1/login with account=demo&username=admin&password=<admin password> in the request body
If the above API call is successful you’ll get a JSON response as shown below
{ "status": 0,
"message": "Success",
"token": "384d27d5-5577-4713-8699-ff5e139d87ab"
}
You must store the “token” key value in persistent storage such as a database or in session because you’ll need this value for all other API calls.
2. Add a Device to the Account
PLEASE NOTE: FOR ANY DEVICE TO BE SUCCESSFULLY ADDED and OPTED IN, THE END USER HAS TO PROVIDE THEIR CONSENT. THE WORKFLOW FOR THIS IS BEYOND THE SCOPE OF THIS DOCUMENT. YOU CAN ASSUME THAT THE ACCOUNT HOLDER HAS ALREADY ADDED THE DEVICES AND RECEIVED OPTIN CONSENT FROM THE ENDUSER VIA THE myGeoTracking PORTAL.
3. Delete Device
Delete Device
Below API is used to delete the device from an account. It is DELETE method call
Request call:
Example URI : http://www.mygeotracking.com/track/api/v1/device/9876543210/delete?token=384d27d5-5577-4713-8699-ff5e139d87ab
Response:
Below is the response we get from the delete api call
{"status":0,
"message":"Success"
}Below is the failure response we get from the delete api call
{ "status":101,
"message":"Error deleting the device."
}
4. Location Optin
Location Optin
Below api is used to optin the device for location services. It is PUT method call
Request call:
URI - http://www.mygeotracking.com/track/api/v1/device/{deviceID}/locoptin?token=<UUID>
Example URI : http://www.mygeotracking.com/track/api/v1/device/9876543210/locoptin?token=384d27d5-5577-4713-8699-ff5e139d87ab
M - Mandatory, O-Optional
Response:
Below is the response we get from the locoptin api call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptin api call
{ "message":"Failure",
"status":101
}5. Location Opt out
Location Optout
Below api is used to optout the device from location services. It is PUT method call
Request call:
URI - http://www.mygeotracking.com/track/api/v1/device/{deviceID}/locoptout?token=
Example URI : http://www.mygeotracking.com/track/api/v1/device/9876543210/locoptout?token=384d27d5-5577-4713-8699-ff5e139d87ab
M - Mandatory, O-Optional
Response:
Below is the response we get from the locoptout api call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptout api call
{ "message":"Failure",
"status":101 }
{ "message":"Phone Number not found in the account",
"status":201 }
6. SMS Opt In
SMS Optin
Below api is used to optin the device for sms services. It is PUT method call
Request call:
URI - http://www.mygeotracking.com/track/api/v1/device/{deviceID}/smsoptin?token=
Example URI : http://www.mygeotracking.com/track/api/v1/device/9876543210/smsoptin?token=384d27d5-5577-4713-8699-ff5e139d87ab
M - Mandatory, O-Optional
Response:
Below is the response we get from the smsoptin api call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the smsoptin api call
{ "message":"Failure",
"status":101 }
{ "message":"Phone Number not found in the account",
"status":201 }7. SMS Opt out
SMS Optout
Below api is used to optout the device from sms services. It is PUT method call
Request call:
URI - http://www.mygeotracking.com/track/api/v1/device/{deviceID}/smsoptout?token=<UUID>
Example URI : http://www.mygeotracking.com/track/api/v1/device/9876543210/smsoptout?token=384d27d5-5577-4713-8699-ff5e139d87ab
M - Mandatory, O-Optional
Response:
Below is the success response we get from the smsopout api call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the smsopout api call
{ "message":"Failure",
"status":101 }
{ "message":"Phone Number not found in the account",
"status":201 }
8. Get All Devices in the Account
API URL: https://www.mygeotracking.com/track/api/v1/device?token=<UUID>
Request Method: GET
API Parameters:
So, the API call will look like https://www.mygeotracking.com/track/api/v1/device?token=384d27d5-5577-4713-8699-ff5e139d87ab and upon successful completion you’ll receive a response as shown below
{ "status":0,
"message":"Success",
"result":[
{ "deviceId":"1001111111",
"wifiStatus":"Unknown",
"activeStatus":"Yes",
"agentEnabled":"Yes",
"GPSStatus":"Off",
"smsOptin":"Yes",
"appName":"myGeoTracking Agent",
"appVersion":"2.1.2",
"deviceDesc":"",
"cellNetworkAvail":"Unknown",
"owner":"Company",
"carrier":"Sprint",
"locOptin":"Yes",
"lastTimeClockStat":"None",
"lastCustName":"None"
},
{ "deviceId":"9876543210",
"wifiStatus":"Unknown",
"activeStatus":"Yes",
"agentEnabled":"Yes",
"GPSStatus":"On",
"smsOptin":"Yes",
"appName":"myGeoTracking Agent",
"appVersion":"2.1.2",
"deviceDesc":"John Smith",
"cellNetworkAvail":"Unknown",
"owner":"Company",
"carrier":"Verizon",
"locOptin":"Yes",
"lastTimeClockStat":"None",
"lastCustName":"None" }
]}
Notice that along with status and message, you have result in the response that contains an array devices available in the account with attributes associated with the device.
9. Get Last Location of All Devices in the Account
There are 2 APIs that can be used to retrieve this information
You can get the last location of a specific device by passing the device id (from list of devices retrieved in previous step) or requesting last location of a group by passing all as the group id (group id all is an implied group that is defined by default in every account)
Device Location API URL: https://www.mygeotracking.com/track/api/v1/location/device/{deviceID}?token=<UUID>
Request Method: GET
API Parameters:Group Location API URL: https://www.mygeotracking.com/track/api/v1/location/group/{gorupID}?token=<UUID>
Request Method: GET
API Parameters:
In group location query service, scope is not supported as it may return too large a dataset.
In our example, we’ll make group location API call it will look like https://www.mygeotracking.com/track/api/v1/location/group/all?token=384d27d5-5577-4713-8699-ff5e139d87ab and on successful completion you’ll see a response as shown below
{"status":0,
"message":"Success",
"result":[
{"deviceID":"1031031031",
"odometerKM":"91232.7",
"icon":16,
"altitude":"0",
"statusCodeDesc":"Location",
"date":"2015/02/06",
"time":"02:00:53",
"timezone":"PST",
"speedKPH":"93.3",
"timestamp":1423216853,
"stoppedState":1,
"address":"259 North Lake Merced Hills, San Francisco, CA 94132, USA",
"deviceType":"Phone",
"deviceDesc":"testphone1",
"longitude":"-122.480600",
"latitude":"37.712310",
"locnType":"TLPLOCN",
"satellites":"0",
"accuracy":"315.0",
"heading":"0.0"
},
{"deviceID":"9876543210",
"odometerKM":"80232.7",
"icon":16,
"altitude":"0",
"statusCodeDesc":"Location",
"date":"2015/02/13",
"time":"05:00:53",
"timezone":"PST",
"speedKPH":"60.3",
"timestamp":1423216853,
"stoppedState":1,
"address":"378 2nd Avenue, San Francisco, CA 94118, USA",
"deviceType":"Phone",
"deviceDesc":"Test",
"longitude":"-122.459500",
"latitude":"37.781740",
"locnType":"TLPLOCN",
"satellites":"0",
"accuracy":"315.0",
"heading":"0.0" }
]}
Notice that you received last location data of all devices in the account in result array.
10. Note
You just need to schedule the API call described in step 4 in a scheduler to be invoked at 10:00 AM, 11:00 AM, 12:00 PM, 1:00 PM and 2:00 PM. Calls at these times will be returning last reported locations of all the device as configured in the schedule.
11. Create load
API URL: https://www.mygeotracking.com/track/api/v1/load?token=<UUID>
Request Method: POST
API Parameters:
E.g. URL : https://www.mygeotracking.com/track/api/v1/load/?token=384d27d5-5577-4713-8699-ff5e139d87ab
If device not found in the account. It will create device, Optin the device and then create load for the device.
Request Body:
{
id: <load_id>,
deviceID : <deviceID>,
origin:
{ name: <stop name>,
address: { line1: <line1>, city: <city>, state: <state>, zip: <zip> }
},
destinations:
[
{ name: <stop name>,
address: { line1: <line1>, city: <city>, state: <state>, zip: <zip> },
early_sched_arrival: { datetime: <datetime>, timezone: <timezone> },
late_sched_arrival: { datetime: <datetime>, timezone: <timezone> }
},
{ name: <stop name>,
address: { line1: <line1>, city: <city>, state: <state>, zip: <zip> },
early_sched_arrival: { datetime: <datetime>, timezone: <timezone> },
late_sched_arrival: { datetime: <datetime>, timezone: <timezone> }
}
],
contact: { name: <name>, phone: <phone> },
pickup_number: <pickup number>,
instructions: <instructions>
}
Response:
{ "status": 0,
"message": "Success",
"result": { load_id: <load id> }
}
Sample request is as follows:
{
"id": "myload",
"deviceID": "9876543210",
"origin": {
"name": "myhome",
"address":
{
"line1": "10 19th Avenue",
"city": "San Francisco",
"state": "CA",
"zip": "94121"
}
},
"destinations":
[
{
"name": "stop1",
"address":
{
"line1": "10 19th Avenue",
"city": "San Francisco",
"state": "CA",
"zip": "94121"
},
"early_sched_arrival":
{
"datetime": "datetime",
"timezone": "timezone"
},
"late_sched_arrival" :
{
"datetime": "datetime",
"timezone": "timezone"
}
},
{
"name": "stop2",
"address":
{
"line1": "314 12th Street",
"city": "San Francisco",
"state": "CA",
"zip": "94103"
},
"early_sched_arrival":
{
"datetime": "datetime",
"timezone": "timezone"
},
"late_sched_arrival" :
{
"datetime": "datetime",
"timezone": "timezone"
}
}
],
"contact":
{
"name": "Mike",
"phone": "9876543210"
},
"pickup_number": "pickup number",
"instructions": "instructions"
}
Note :
early_sched_arrival and late_sched_arrival is not implemented.
pickup_number and instructions not implemented.
id is load_id
multiple destination not implemented yet. Only single destination can be provided for now
sample response is as follows
{ "status": 0,
"message": "Success",
"result":
{
"load_id": "myload-1-1"
}
}
12. Cancel load
Request Method: DELETE
API Parameters:
Response:
{ "status": 0,
"message": "Success"
}
Sample url is as follows
https://www.mygeotracking.com/track/api/v1/load/myload-1-1?token=384d27d5-5577-4713-8699-ff5e139d87ab
13. Get Load Loc Data
Request Method: P{OST
API Parameters:
The below request is optional. If you provide json request it will give location data for the given load ID provided in the URL for the given time range.
If the json request is not provided it will give the last location for the given load ID provided in the URL
E.g. url : https://www.mygeotracking.com/track/api/v1/load/getloadloc/myload-1-1?token=384d27d5-5577-4713-8699-ff5e139d87ab
Request :
{
"range":
{
"from": "yyyy/MM/dd HH:mm:ss">,
"to": "yyyy/MM/dd HH:mm:ss"
}
}
Note: time is 24 hour format
Response:
{ "status": 0,
"message": "Success",
"result":
{
"load_id": "myload-1-1",
"deviceID": "9876543210",
"locations":
[
{
"latitude": "37.781740",
"longitude": "-122.459500",
'"accuracy": "312.0",
"address": "378 2nd Avenue, San Francisco, CA 94118, USA",
"date": "2015/08/21",
"time": "06:40:00",
"timezone": "PST"
}
],
}
}
Sample request is as follows:
{
"range":
{
"from": "2015/08/21 00:40:00",
"to": "2015/08/21 10:45:00"
}
}
14. Send Message
Request Method: POST
Request Body:
{
to: [ <device id>,<device id> ],
type: <SMS|InApp>,
message: <message>
}
API Parameters:
Response:
{ "status": 0,
"message": "Success"
}
15. Logout of myGeoTracking system
Request Method: POST
API Parameters:
So, the API call will look like https://www.mygeotracking.com/track/api/v1/logout?token=384d27d5-5577-4713-8699-ff5e139d87ab and if the API is successful, you’ll receive a response as shown below.
{ "status": 0,
"message": "Success"
}
It is safe logout to invalidate the token to prevent and any miss-use of the valid token at a later time.
16. That’s it!! You are done