Skip to main content

Determining a Field Computer Location

Getting the GPS Location of a Field Computer consists of 2 steps:

  1. Determining the ID of the Field Computer to be located
  2. Asking the Slingshot API Server for the GPS Location(s) of the chosen Field Computer

Step 1: Determining the ID of the Field Computer to be located​

To determine the ID of the Field Computer to be located, the API Client needs to issue a GET request to the /FieldComputers URI and allow the user to choose the Field Computer from their list of Field Computers.

The response to a GET request to the /FieldComputers URI will be:

<slingshotindex xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.ravenslingshot.com/SlingshotIndex/2010">
    <totalcount>2</totalcount>
    <pagesize>20</pagesize>
    <ispreviouspage>false</ispreviouspage>
    <isnextpage>false</isnextpage>
    <pageindex>0</pageindex>
    <totalpages>1</totalpages>
    <fieldcomputer>
        <id>2058</id>
        <name>VPRO4 T380</name>
        <uri>https://api.ravenslingshot.com/FieldComputers/2058</uri>
    </fieldcomputer>
    <fieldcomputer>
        <id>2558</id>
        <name>E-Pro II B2</name>
        <uri>https://api.ravenslingshot.com/FieldComputers/2558</uri>
    </fieldcomputer>
</slingshotindex>

This response can be parsed using the SlingshotIndex.xsd schema. Once the user picks a Field Computer, the API Client will need to save the URI value of the chosen Field Computer to use in Step 2.

Step 2: Asking the Slingshot API Server for the GPS Location(s) of the chosen Field Computer​

There are two calls that an API Client can make to determine the GPS Location of the chosen Field Computer.

A GET call to /FieldComputers/{fcID}/CurrentLocation will return a Slingshot Index response containing a single record that contains the most recent GPS location reported into the Slingshot system by the Field Computer represented by {fcID}. This record will contain the Latitude, Longitude, Altitude, Speed, Direction, and a DateTime stamp of when the record was created.

<slingshotindex xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.ravenslingshot.com/SlingshotIndex/2010">
    <totalcount>1</totalcount>
    <pagesize>20</pagesize>
    <ispreviouspage>false</ispreviouspage>
    <isnextpage>false</isnextpage>
    <pageindex>0</pageindex>
    <totalpages>1</totalpages>
    <devicelocation>
        <id>253006</id>
        <deviceid>1092</deviceid>
        <subtype>Field Computer</subtype>
        <lat>0.00000000</lat>
        <lon>0.00000000</lon>
        <alt>0</alt>
        <speed>0</speed>
        <direction>0</direction>
        <gpsdatetime>2010-10-05T18:03:20Z</gpsdatetime>
    </devicelocation>
</slingshotindex>

A GET call to /FieldComputers/{fcID}/Locations will return a Slingshot Index response containing multiple records that contain the GPS Location reported into the Slingshot system by the Field Computer represented by {fcID} over time.

By default, the Slingshot API Server will return 20 records per request, but this value can be controlled by adding the query string parameter pageSize to the GET call.

<slingshotindex xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.ravenslingshot.com/SlingshotIndex/2010">
    <totalcount>1990</totalcount>
    <pagesize>20</pagesize>
    <ispreviouspage>false</ispreviouspage>
    <isnextpage>true</isnextpage>
    <pageindex>0</pageindex>
    <totalpages>100</totalpages>
    <devicelocation>
        <id>253006</id>
        <deviceid>1092</deviceid>
        <subtype>Field Computer</subtype>
        <lat>0.00000000</lat>
        <lon>0.00000000</lon>
        <alt>0</alt>
        <speed>0</speed>
        <direction>0</direction>
        <gpsdatetime>2010-10-05T18:03:20Z</gpsdatetime>
    </devicelocation>
    <devicelocation>
        <id>253005</id>
        <deviceid>1092</deviceid>
        <subtype>Field Computer</subtype>
        <lat>0.00000000</lat>
        <lon>0.00000000</lon>
        <alt>0</alt>
        <speed>0</speed>
        <direction>0</direction>
        <gpsdatetime>2010-10-05T17:58:10Z</gpsdatetime>
    </devicelocation>
</slingshotindex>

Both of these responses can be parsed using the SlingshotIndex.xsd schema file. The data types and units are also documented in the SlingshotIndex.xsd schema file.

If the Slingshot API Server can determine which Field Hub a specific Field Computer is using, the API server will return the GPS Location records of the Field Hub and the SubType element of these records will be 'Field Hub'. If the Slingshot API Server cannot determine which Field Hub a Field Computer is using, it will return the GPS Location records of the Field Computer and the SubType of these records will be 'Field Computer'.

Currently, GPS Location records come in from Field Hubs every 30 seconds and GPS Location records come in from Field Computers every 5 minutes.

Getting the GPS Location of more than one Field Computer in a single API call.​

Both of these calls support the special value of all for {fcID}.

When this value is used for {fcID}, the Slingshot API Server will return the a Slingshot Index response containing the most recent GPS Location for each Field Computer that the user has access to. A call to /FieldComputers/all/CurrentLocation will return a single GPS Location for each Field Computer. In contrast, a call to /FieldComputers/all/Locations will return multiple GPS Locations for each Field Computer and this result set could be quite large.

At this time, however, the call to /FieldComputers/all/Locations is not implemented.