API

 


Overview


iAtlas is a first class IoT cloud-based tracking service used all over the world. Our first class API runs on top of the world's most powerful cloud platform, Amazon Web Services. We run on top of redundant, highly secure, highly scalable and highly available servers. With customers all over the world, our servers must maintain stability and availability. Our devices respond with data based on distance, time and direction. We store this data in a highly available PostGres database engine. Our web, android and ios apps make calls into our API to pull the data.


iAtlas API is a RESTful/JSON interface using token based authentication. With an iAtlas username and password, you have access to all of your data through the API.


Here is a list of currently available API endpoints:


https://api.iatlas.us/user/login - api login

https://api.iatlas.us/device/get_user_devices - get all devices under this users id

https://api.iatlas.us/trip/vehicle_position_new - get all currently vehicle positions

https://api.iatlas.us/trip/by_id - get a trip by trip id

https://api.iatlas.us/trip/get_device_trips_by_date - get trips for a specific device by date

https://api.iatlas.us/device/onMyWayCreate - send a customer a link to track a vehicle

https://api.iatlas.us/user/logout - logout of the api


https://api.iatlas.us/trip/last_trip - no documention yet

https://api.iatlas.us/trip/last_10_trips - no documentation yet


Authentication


Given the correct username/password, we generate a unique binary hash, sha512 encoded token from the username+timestamp. The token is used for all subsequent calls to the api. The token times out after 60 minutes.


Request/Response


Requests are made using URL parameters and primarily GET. Request are mutlipart-form requests. Responses are in JSON. Every request, other than the login endpoint, must have the token. We have created examples you can use to test the API. We like Postman a lot. It is a Chrome plugin.


NOTE: changing the REQEUST to an _id is not yours, will invalidate your token, you’ll have to get a new token before continuing. This is another security feature we have implemented to protect the data from hacking.



api login - authentication


request: POST https://api.iatlas.us/user/login

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="username"


iatlas-username-here

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="password"


password-here

------WebKitFormBoundary7MA4YWxkTrZu0gW--


response:

{

   "_id": "5",

   "_token": "6a4ebb5ae569escc83c67c0d99bb6538283f05646151fa64c8129c85887f02f34f7c666d95b2c1a2663fc2efbaaba7460b6a0135cded6f9f88x8d14a7e418a61db4",

   "message": "success",

   "_success": "t"

}



Get devices for your account


request: POST https://api.iatlas.us/device/get_user_devices

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_token"


27d5fb072b5eaf6f3fc1d9835ef31eb17a6cb0d90bb4f77edf7c40600ed1b5b7ededd632947ca60f30b56e6c22428ef1230c001448f2971726967cfe1cc4efdf

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_id"


5

------WebKitFormBoundary7MA4YWxkTrZu0gW--



response:

[

   {

       "userid": "5",

       "alias": "4542045249",

       "device_id": "4542045249",

       "id": "8",

       "description": "",

       "speed_limit": "0",

       "is_owner": "t",

       "created_at": "2015-04-06 13:38:59.038995+00",

       "vin": null,

       "sim_number": null

   },

   {

       "userid": "5",

       "alias": "4542045250",

       "device_id": "4542045250",

       "id": "9",

       "description": "",

       "speed_limit": "0",

       "is_owner": "t",

       "created_at": "2015-04-06 13:47:20.682417+00",

       "vin": null,

       "sim_number": null

   },

   {

       "userid": "5",

       "alias": "Greg Banks",

       "device_id": "4532111476",

       "id": "53",

       "description": null,

       "speed_limit": "0",

       "is_owner": "f",

       "created_at": "2016-01-16 22:01:40.707643+00",

       "vin": "null",

       "sim_number": "null"

   },

   {

       "userid": "5",

       "alias": "Frikkie Ford Focus",

       "device_id": "4532111656",

       "id": "70",

       "description": null,

       "speed_limit": "0",

       "is_owner": "f",

       "created_at": "2016-03-07 13:44:18.194926+00",

       "vin": "",

       "sim_number": "undefined"

   },

   {

       "userid": "5",

       "alias": "Kia",

       "device_id": "4532111930",

       "id": "79",

       "description": null,

       "speed_limit": "0",

       "is_owner": "f",

       "created_at": "2016-05-02 02:53:23.833478+00",

       "vin": null,

       "sim_number": null

   },

   {

       "userid": "5",

       "alias": "White Van",

       "device_id": "4562008834",

       "id": "37",

       "description": null,

       "speed_limit": "0",

       "is_owner": "t",

       "created_at": "2015-09-15 13:57:24.456194+00",

       "vin": "null",

       "sim_number": "null"

   },

   {

       "userid": "5",

       "alias": "Mexico",

       "device_id": "4532111492",

       "id": "111",

       "description": null,

       "speed_limit": "0",

       "is_owner": "f",

       "created_at": "2016-05-31 22:27:13.991788+00",

       "vin": "null",

       "sim_number": "null"

   },

   {

       "userid": "5",

       "alias": "Hyundai",

       "device_id": "4532111617",

       "id": "516",

       "description": null,

       "speed_limit": "0",

       "is_owner": "f",

       "created_at": "2016-09-21 17:38:12.229455+00",

       "vin": null,

       "sim_number": null

   },

   {

       "userid": "5",

       "alias": "White Truck",

       "device_id": "4542006248",

       "id": "593",

       "description": null,

       "speed_limit": "0",

       "is_owner": "t",

       "created_at": "2016-11-02 23:35:04.861424+00",

       "vin": null,

       "sim_number": null

   }

]



Get latest telemetry data for all vehicles on your account


request: POST https://api.iatlas.us/trip/vehicle_position_new

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_token"


27d5fb072b5eaf6f3fc1d9835ef31eb17a6cb0d90bb4f77edf7c40600ed1b5b7ededd632947ca60f30b56e6c22428ef1230c001448f2971726967cfe1cc4efdf

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_id"


5

------WebKitFormBoundary7MA4YWxkTrZu0gW--



response:

[

   {

       "lasttripstoplocaltime": "2016-06-10 10:29:15",

       "lasttripstartlocaltime": "2016-06-10 10:27:12",

       "drivingtime": 123,

       "stoptripaddress": "132, Civic Circle, Lewisville, Denton County, Texas, 75067, United States of America",

       "eventcode": 0,

       "distancetraveled": 429,

       "maxspeed": 24.083999633789,

       "starttripaddress": "124, Civic Circle, Lewisville, Denton County, Texas, 75067, United States of America",

       "inputs": 0,

       "satellite": 9,

       "mobileid": "4532111476",

       "updatetime": {

           "sec": 1465573934,

           "usec": 0

       },

       "vehiclestate": "S",

       "devicestatus": "C",

       "speed": 0.071999996900558,

       "rssi": -69,

       "longitude": -97.021743774414,

       "latitude": 33.045364379883,

       "altitude": 148.19000244141,

       "lasttripstart": {

           "sec": 1465558032,

           "usec": 0

       },

       "lasttripstop": {

           "sec": 1465558155,

           "usec": 0

       },

       "plugged": "plugged",

       "unreachableaddres": null,

       "eventLength": 28,

       "last_event": {

           "updatetime": "2016-06-10 11:29:15",

           "latitude": 33.045364379883,

           "longitude": -97.021743774414,

           "altitude": 148.19000244141,

           "speed": 0.071999996900558,

           "heading": 180,

           "satellites": 9,

           "fixStatus": 0,

           "carrier": 410,

           "rssi": -69,

           "commState": 47,

           "hdop": 0.90000003576279,

           "inputs": 0,

           "unitStatus": 0,

           "eventIndex": 3,

           "eventCode": 0,

           "accums": 2,

           "spare": 302,

           "accum": [

               731559,

               -1962671936

           ],

           "zones": null,

           "speedLimit": 56.326900482178,

           "localupdatetime": "2016-06-10 10:29:15",

           "tripline_case": "ON_TRIP",

           "lastStop": null

       },

       "serverUtcTime": 1481483208

   },

   {

       "lasttripstoplocaltime": "2016-07-08 13:10:02",

       "lasttripstartlocaltime": "2016-07-08 13:03:28",

       "drivingtime": 394,

       "stoptripaddress": "Jardines, Aguascalientes, 20288, Estados Unidos Mexicanos",

       "eventcode": 0,

       "distancetraveled": 1956,

       "maxspeed": 56.267997741699,

       "starttripaddress": "Valente Quintana, Aguascalientes, 20288, Estados Unidos Mexicanos",

       "inputs": 16,

       "satellite": 6,

       "mobileid": "4532111656",

       "updatetime": {

           "sec": 1467995642,

           "usec": 0

       },

       "vehiclestate": "S",

       "devicestatus": "C",

       "speed": 0.79199993610382,

       "rssi": -93,

       "longitude": -102.30038452148,

       "latitude": 21.857955932617,

       "altitude": 1849.8699951172,

       "lasttripstart": {

           "sec": 1467986608,

           "usec": 0

       },

       "lasttripstop": {

           "sec": 1467987002,

           "usec": 0

       },

       "plugged": "plugged",

       "unreachableaddres": null,

       "eventLength": 29,

       "last_event": {

           "updatetime": "2016-07-08 14:10:02",

           "latitude": 21.857955932617,

           "longitude": -102.30038452148,

           "altitude": 1849.8699951172,

           "speed": 0.79199993610382,

           "heading": 200,

           "satellites": 6,

           "fixStatus": 2,

           "carrier": 3,

           "rssi": -93,

           "commState": 47,

           "hdop": 1.3999999761581,

           "inputs": 16,

           "unitStatus": 0,

           "eventIndex": 3,

           "eventCode": 0,

           "accums": 2,

           "spare": 302,

           "accum": [

               491379,

               -1961139877

           ],

           "zones": null,

           "speedLimit": 990,

           "localupdatetime": "2016-07-08 13:10:02",

           "tripline_case": "ON_TRIP",

           "lastStop": null

       },

       "serverUtcTime": 1481483208

   }

]



Get trips by date range for one or more devices


request: POST https://api.iatlas.us/trip/devices_trip_by_date

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


description of parameters:

deviceIds[] - a single deviceID. You can get this from the get_user_devices endpoint. You can have multiple deviceIds[] in the request if you want to pull back trips for more than 1 device at a time.

date_range - last_hour, last_8, last_24, this_week, last_week, this_month, last_month, custom. custom requires dateFrom and dateTo

mytime - you current localtime


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_token"


5a6fbf5b79a052f3ed1e6c50b9db6814456402ebba460b6db053766bd01c400dd8f4f6c8620733c48d4b38b0da3110d5736762826eb86697e4efbbbb28718263

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_id"


5

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="date"


2014-10-14

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="deviceIds[]"


4532111617

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="deviceIds[]"


4562008834

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="dateFrom"


2016-12-01

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="dateTo"


2016-12-11

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="date_range"


last_week

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="myTime"


2016-12-11 13:22:24

------WebKitFormBoundary7MA4YWxkTrZu0gW--


response:

[

   {

       "trip_id": "82598",

       "deviceid": "4532111617",

       "device_alias": "Hyundai",

       "starttime": "2016-12-04 16:10:06",

       "stoptime": "2016-12-04 16:20:16",

       "startaddress": "Freddy's Frozen Custard, 9053, North 121st East Avenue, Owasso, Tulsa County, Oklahoma, 74055, United States of America",

       "startlong": "-95.8416137695312",

       "startlat": "36.2904815673828",

       "startalt": "189.699996948242",

       "stopaddress": "North Memorial Drive, Tulsa County, Oklahoma, 74021, United States of America",

       "stoplong": "-95.8879241943359",

       "stoplat": "36.258373260498",

       "stopalt": "151.039993286133",

       "distance": "7609",

       "duration": "610"

   },

   {

       "trip_id": "82544",

       "deviceid": "4532111617",

       "device_alias": "Hyundai",

       "starttime": "2016-12-04 11:43:05",

       "stoptime": "2016-12-04 11:54:50",

       "startaddress": "North Memorial Drive, Tulsa County, Oklahoma, 74021, United States of America",

       "startlong": "-95.8878402709961",

       "startlat": "36.2583312988281",

       "startalt": "154.699996948242",

       "stopaddress": "North 121st East Avenue, Owasso, Tulsa County, Oklahoma, 74055, United States of America",

       "stoplong": "-95.8420867919922",

       "stoplat": "36.2903938293457",

       "stopalt": "186.580001831055",

       "distance": "7590",

       "duration": "705"

   },

   {

       "trip_id": "82262",

       "deviceid": "4532111617",

       "device_alias": "Hyundai",

       "starttime": "2016-12-03 19:19:40",

       "stoptime": "2016-12-03 19:29:03",

       "startaddress": "North 121st East Avenue, Owasso, Tulsa County, Oklahoma, 74055, United States of America",

       "startlong": "-95.8420715332031",

       "startlat": "36.2903900146484",

       "startalt": "184.910003662109",

       "stopaddress": "North Memorial Drive, Tulsa County, Oklahoma, 74021, United States of America",

       "stoplong": "-95.8878860473633",

       "stoplat": "36.2583656311035",

       "stopalt": "156.279998779297",

       "distance": "7678",

       "duration": "563"

   }

]



Get detailed trip information, data points, by trip id - this returns a lot of data points. Each point recorded on the trip.


request: POST https://api.iatlas.us/trip/by_id

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_token"


5a6fbf5b79a052f3ed1e6c50b9db6814456402ebba460b6db053766bd01c400dd8f4f6c8620733c48d4b38b0da3110d5736762826eb86697e4efbbbb28718263

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="_id"


5

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="tripID"


82262

------WebKitFormBoundary7MA4YWxkTrZu0gW--


response:

{

   "id": "82262",

   "mobileid": "4532111617",

   "startriptime": "2016-12-03 20:19:40",

   "stoptriptime": "2016-12-03 20:29:03",

   "starttripaddres": "North 121st East Avenue, Owasso, Tulsa County, Oklahoma, 74055, United States of America",

   "startlongitude": "-95.8420715332031",

   "startlatitude": "36.2903900146484",

   "startaltitude": "184.910003662109",

   "stoptripaddres": "North Memorial Drive, Tulsa County, Oklahoma, 74021, United States of America",

   "stoplongitide": "-95.8878860473633",

   "stoplatitude": "36.2583656311035",

   "stopaltitude": "156.279998779297",

   "averadgespeed": "49.097040438487",

   "maxspeed": "92.3759994506836",

   "tripdistance": "7678",

   "tripduration": "563",

   "tripstops": "0",

   "tripsstopsdurations": "0",

   "zonein": "0",

   "zoneout": "0",

   "excessiveacceleration": "0",

   "harshbraking": "0",

   "corneringleft": "0",

   "corneringright": "0",

   "tripstate": "END_TRIP",

   "feulconsumed": "0",

   "feulkm": "0",

   "flag": "0",

   "startmessageid": "0",

   "stopmessageid": "0",

   "drive_score": "0",

   "freeflowtime": "119",

   "speedingtime": "164",

   "freeflowdistance": "2129",

   "speedingdistance": "3122",

   "nonfreeflowtime": "280",

   "nonfreeflowdistance": "2427",

   "speeding": "0",

   "speedviolations": "0",

   "localstartriptime": "2016-12-03 19:19:40",

   "localstoptriptime": "2016-12-03 19:29:03",

   "trip_json": [

       {

           "updatetime": "2016-12-03 20:19:40",

           "latitude": 36.290390014648,

           "longitude": -95.842071533203,

           "altitude": 184.91000366211,

           "speed": 5.0759997367859,

           "heading": 44,

           "satellites": 9,

           "fixStatus": 34,

           "carrier": 410,

           "rssi": -87,

           "commState": 8,

           "hdop": 1.2000000476837,

           "inputs": 1,

           "unitStatus": 0,

           "eventIndex": 1,

           "eventCode": 1,

           "accums": 2,

           "spare": 0,

           "accum": [

               1257565,

               -1979383410

           ],

           "zones": null,

           "speedLimit": 990,

           "localupdatetime": "2016-12-03 19:19:40",

           "tripline_case": "NEW_TRIP",

           "lastStop": null

       },

       {

           "updatetime": "2016-12-03 20:19:49",

           "latitude": 36.290477752686,

           "longitude": -95.841659545898,

           "altitude": 187.5,

           "speed": 16.091999053955,

           "heading": 72,

           "satellites": 9,

           "fixStatus": 34,

           "carrier": 410,

           "rssi": -87,

           "commState": 0,

           "hdop": 1.2000000476837,

           "inputs": 1,

           "unitStatus": 0,

           "eventIndex": 15,

           "eventCode": 11,

           "accums": 2,

           "spare": 302,

           "accum": [

               1257603,

               -1979383410

           ],

           "zones": null,

           "speedLimit": 990,

           "localupdatetime": "2016-12-03 19:19:49",

           "tripline_case": "ON_TRIP",

           "lastStop": null

       }

   ]

}



Share your location with someone for a specific period of time (type). This endpoint, will send an email to someone and provide them a link of the devices location in real time.


request: POST https://api.iatlas.us/device/onMyWayCreate

header:

Content-Type: application/x-www-form-urlencoded


description of parameters:

_id - your user_id, retrieved from authentication

_token - retrieved from authentication

device_ids[] - deviceId you want to share

from - from date in YYYY-MM-DD - these are for future use, at this time only type determines share time

to - to date in YYYY-MM-DD

myTime - your local time

type - 1_hour, 2_hour, 4_hour, 8_hour, today, this_week, this_month, forever

devName - this can be any name you would like, the user will see this name in the email

username - the email address of the person you want to share this devices location with


body:

_id=5&_token=5a6fbf5b79a052f3ed1e6c50b9db6814456402ebba460b6db053766bd01c400dd8f4f6c8620733c48d4b38b0da3110d5736762826eb86697e4efbbbb28718263&device_ids[]=4562008834&from=2015-12-21&to=2015-12-21&myTime=2015-12-2108:22:51&type=1_hour&devName=WhiteVan&username=urban.john@gmail.com


response:

{

 "success": "t",

 "message": "Device WhiteVan has been successfully shared for the next 01:00:00 hours<br/>"

}




Logout of the iatlas API.


request: POST https://api.iatlas.us/user/logout

header:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW


description of parameters:

token - retrieved from authentication


body:

------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="token"


5a6fbf5b79a052f3ed1e6c50b9db6814456402ebba460b6db053766bd01c400dd8f4f6c8620733c48d4b38b0da3110d5736762826eb86697e4efbbbb28718263

------WebKitFormBoundary7MA4YWxkTrZu0gW--


response:

{

 "_token": "533de4e8cbef6efe9e2c29cfeefe7ad935bc3afcac3e7e54f881602ed6784d966476b64e0332d78700593b29a42a784890ef4bb08a66dc4f809eb880fefb56fc",

 "_status": "logout success",

 "_success": "t"

}