Unit

API for accessing units information

Search Units

When requesting the API for information about specific devices, you have to know the unit ID of this device on our server.

You can use the Unit search API to find out ids according to the Modem Id (or Serial if there is no modem on the board) of your device.

The route for unit searching is: GET /units/search(.#{format})

HTTP Method Resource Path Available Formats URLs
GET /units/search html, json, ext_json Production, Sandbox

API Call – Search units

HTTP Method: GET
Resource Path: /units/search.#{format}
Available Formats: html, json, ext_json
URLs: Production, Sandbox
Output: Array of Units

Available URL Query parameters

  • modids – Show units matching provided GRPS Modem IDs1 (default: Any modid)
    • * can be used for substring search.

1 This is the number that uniquely identifies the GPRS modem in the device.

Example Requests

Get all devices containing 3216 in their Modem ID

  • Request :
    • GET /units/search?modids=*3216*
  • Expected status header :
    • HTTP/1.1 200 OK
XML
$ curl 'http://g8teway.com/api/v2/units/search.xml?modids=*3216*' -b mdi.cookie -c mdi.cookie
Response
<?xml version="1.0" encoding="UTF-8"?>
<units type="array">
  <unit>
    <id type="integer">42899</id>
    <modid>mdi32161</modid>
  </unit>
  <unit>
    <id type="integer">42891</id>
    <modid>mdi32166</modid>
  </unit>
</units>
JSON
$ curl 'http://g8teway.com/api/v2/units/search.json?modids=*3216*' -b mdi.cookie -c mdi.cookie
Response
[{"unit":
  {"id": 42899,
   "modid": "mdi32161"}},
{"unit":
  {"id": 42891,
   "modid": "mdi32166"}}]

List Units

The route for listing units is: GET /units(.#{format})

API Call – List units

HTTP Method: GET
Resource Path: /units.#{format}
Available Formats: html, json, ext_json
URLs: Production, Sandbox
Output: Array of Units

Available URL Query parameters

  • ret – Fields to retrieve when getting data from the Web Service (default: id, lat, long, time)
    • id – Show unit id
    • lat – Show unit latitude
    • long – Show unit longitude
    • time – Show date of info
    • data – Show last tracking records for specified fields, at specified time.
      This must be used when using the “fieldis” query parameter.
  • unitids – Show only units included in specified unit ids. (default: all units)
  • fieldids – Attach specified tracking field value to returned units. (default: none)
  • unknown – Allow unknown position (default: false)
  • time – Date of info (default: latest info)

Example Requests

Get all unit ids and modem ids

  • Request :
    • GET /units?ret=id,modid
  • Expected status header :
    • HTTP/1.1 200 OK
XML
$ curl 'http://g8teway.com/api/v2/units.xml?ret=id,modid' -b mdi.cookie -c mdi.cookie
Response
<?xml version="1.0" encoding="UTF-8"?>
<units type="array">
  <unit>
    <id type="integer">42883</id>
    <modid>mdi32180</modid>
  </unit>
  <unit>
    <id type="integer">42899</id>
    <modid>mdi32161</modid>
  </unit>
</units>
JSON
$ curl 'http://g8teway.com/api/v2/units.json?ret=id,modid' -b mdi.cookie -c mdi.cookie
Response
[{"unit":
   {"id": 42883,
    "modid": "mdi32180"}},
 {"unit":
   {"id": 42899,
    "modid": "mdi32161"}}]

Get all units with their last known position

  • Request :
    • GET /units?ret=id,modid,lat,long,time
  • Expected status header :
    • HTTP/1.1 200 OK
JSON
$ curl 'http://g8teway.com/api/v2/units.json?ret=id,modid,lat,long,time' -b mdi.cookie -c mdi.cookie
Response
[{"unit":
   {"time": "2009-01-15T19:25:54Z",
    "id": 42883,
    "modid": "mditest32180",
    "lat": -177,
    "long": 1660}},
 {"unit":
   {"time": "2009-04-10T16:03:37Z",
    "id": 42899,
    "modid": "mditest32161",
    "lat": 4885667,
    "long": 235099}}]

Get units including last known value for one or more tracking fields

  • Request :
    • GET /units?ret=id,modid,lat,lng,time,data&fieldids=127,128&unitids=1,2
  • Expected status header :
    • HTTP/1.1 200 OK

If you want to get the last known value of one or more tracking fields, you can also use the units API call.
To do this, simply add data in the ret query parameter and specify at least one field id in fieldids.
Note that in this case the returned object will include an array of tracking records for requested fieldids.

JSON
$ curl 'http://g8teway.com/api/v2/units.json?ret=id,modid,lat,lng,time,data&fieldids=127,128&unitids=1,2' -b mdi.cookie -c mdi.cookie
Response
[{"unit":
    {"id": 1,
     "modid": "151614102424242",
     "last_tracking_records":
     [{"latitude": 20,
       "recordtime": "2009-04-10T13:19:09Z",
       "unitid": 1,
       "id": 2,
       "value": "T%FD%94%0FOfy%8F%01ku7%8E(",
       "longitude": 10,
       "fieldid": 127},
      {"latitude": 20,
       "recordtime": "2009-04-10T13:19:09Z",
       "unitid": 1,
       "id": 4,
       "value": "T%FD%94%0FOfy%8F%01ku7%8E(",
       "longitude": 10,
       "fieldid": 128}]}},
  {"unit":
    {"id": 2,
     "modid": "151614102425478",
     "last_tracking_records":
     [{"latitude": 20,
       "recordtime": "2009-04-10T13:19:09Z",
       "unitid": 2,
       "id": 3,
       "value": "T%FD%94%0FOfy%8F%01ku7%8E(",
       "longitude": 10,
       "fieldid": 128}]}}]