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"
}