Partner API – getReturns V2

Home » Partner API » Partner API – getReturns V2
Partner API No Comments

The JumpDrive API function “getReturns” in V2 allows customers and partners to access data about returning vehicles using the 2nd generation JD vehicle device.

Getting Started

Our Partner API requires the following to retrieve vehicle return information:

  1. API URL, Username and Password (please email partner@jumpdrive.com for your credentials)
  2. Vehicle Identification Number (VIN) to get it’s return details.
  3. Familiarity with a programming language supporting REST calls (PHP, Ruby, .NET, and Python)

For best results, we recommend querying the API at least every minute during customer hours of operation.

Steps For Using the API

  1. Create a script to call our API URL (will be provided via email upon request) and pass your username, password, and response format.  By default all results are in XML, for example – getReturns(username, password, vin, response).  For JSON formatted results, use getReturns(username, password, vin, json).
  2. If you receive the message “Invalid Username and/or Password”, please contact partner@jumpdrive.com and we will confirm your credentials.
  3. IMPORTANT: The API returns only new data generated since the previous request. If no new new information is available, it will return the “No New Records” message.

Sample XML/JSON results

 

Sample XML Response
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <Trip1>
   <VIN>5GAKRBED0BJ315904</VIN> 
   <JumpDriveID>fffc8d</JumpDriveID> 
   <LotID>273</LotID>
   <LotName>Pine Ridge</LotName> 
   <LastTimeIn>2016-02-02 16:36:22</LastTimeIn>
   <FuelVolume>11.6</FuelVolume>
   <StartMileage>50844</StartMileage>
   <LastMileage>50947</LastMileage>
   <FuelVolume>25.5</FuelVolume>
   <FuelPercent>13.93</FuelPercent>
   <ID>660102</ID> 
   <CustomerID>67</CustomerID>
   <CreatedAt>2016-02-02 16:36:22</CreatedAt>
   </Trip1>
   <Trip2>
   <VIN>5GAKRBED0BJ315904</VIN>
   <JumpDriveID>fffc8d</JumpDriveID>
   <LotID>273</LotID>
   <LotName>Pine Ridge</LotName>    
   <LastTimeIn>2016-01-29 17:39:53</LastTimeIn>
   <FuelVolume>22.55</FuelVolume>
   <FuelPercent>27.08</FuelPercent>
   <StartMileage>50255</StartMileage>
   <LastMileage>50491</LastMileage>
   <ID>643602</ID>
   <CustomerID>67</CustomerID>
   <CreatedAt>2016-01-29 17:39:53</CreatedAt>
   </Trip2>
   <Trip3>
   <VIN>5GAKRBED0BJ315904</VIN> 
   <JumpDriveID>fffc8d</JumpDriveID>
   <LotID>273</LotID>
   <LotName>Pine Ridge</LotName> 
   <LastTimeIn>2016-01-28 16:53:34</LastTimeIn>
   <FuelVolume>27.2</FuelVolume>
   <FuelPercent>32.66</FuelPercent>
   <StartMileage>49993</StartMileage>
   <LastMileage>50255</LastMileage>
   <ID>635702</ID> 
   <CustomerID>67</CustomerID>
   <CreatedAt>2016-01-28 16:53:34</CreatedAt>
   </Trip3>
   <Trip4>
   <VIN>5GAKRBED0BJ315904</VIN>
   <JumpDriveID>fffc8d</JumpDriveID> 
   <LotID>273</LotID>
   <LotName>Pine Ridge</LotName> 
   <LastTimeIn>2016-01-27 17:51:21</LastTimeIn>
   <FuelVolume>23.86</FuelVolume>
   <FuelPercent>28.65</FuelPercent>
   <StartMileage>48446</StartMileage>
   <LastMileage>49993</LastMileage>
   <ID>631102</ID> 
   <CustomerID>67</CustomerID>
   <CreatedAt>2016-01-27 17:51:21</CreatedAt>
   </Trip4>
   <Trip5>
   <VIN>5GAKRBED0BJ315904</VIN> 
   <JumpDriveID>fffc8d</JumpDriveID>
   <LotID>273</LotID>
   <LotName>Pine Ridge</LotName>
   <LastTimeIn>2016-01-27 10:46:41</LastTimeIn>
   <FuelVolume>32.08</FuelVolume>
   <FuelPercent>38.52</FuelPercent>
   <StartMileage>44562</StartMileage>
   <LastMileage>49991</LastMileage>
   <ID>627402</ID> 
   <CustomerID>67</CustomerID>
   <CreatedAt>2016-01-27 10:46:41</CreatedAt>
   </Trip5>
</root>
Sample JSON Response
{
 "root": {
 "Trip1": {
 "VIN": "5GAKRBED0BJ315904",
 "JumpDriveID": "fffc8d", 
 "LotID": "273",
 "LotName": "Pine Ridge", 
 "LastTimeIn": "2016-02-02 16:36:22",
 "StartMileage": "50947",
 "LastMileage": "51845", 
 "FuelVolume": "11.6",
 "FuelPercent": "13.93",
 "ID": "660102", 
 "CustomerID": "67",
 "CreatedAt": "2016-02-02 16:36:22"
 },
 "Trip2": {
 "VIN": "5GAKRBED0BJ315904",
 "JumpDriveID": "fffc8d", 
 "LotID": "273",
 "LotName": "Pine Ridge", 
 "LastTimeIn": "2016-02-01 15:16:25",
 "StartMileage": "50147",
 "LastMileage": "50945", 
 "FuelVolume": "31.6",
 "FuelPercent": "83.93",
 "ID": "660102", 
 "CustomerID": "67",
 "CreatedAt": "2016-02-02 16:36:22"
 },
 "Trip3": {
 "VIN": "5GAKRBED0BJ315904",
 "JumpDriveID": "fffc8d", 
 "LotID": "273",
 "LotName": "Pine Ridge", 
 "LastTimeIn": "2016-02-01 15:16:25",
 "StartMileage": "50147",
 "LastMileage": "50945", 
 "FuelVolume": "31.6",
 "FuelPercent": "83.93",
 "ID": "660102", 
 "CustomerID": "67",
 "CreatedAt": "2016-02-02 16:36:22"
 },
 "Trip4": {
 "VIN": "5GAKRBED0BJ315904",
 "JumpDriveID": "fffc8d", 
 "LotID": "273",
 "LotName": "Pine Ridge", 
 "LastTimeIn": "2016-02-01 15:16:25",
 "StartMileage": "50147",
 "LastMileage": "50945", 
 "FuelVolume": "31.6",
 "FuelPercent": "83.93",
 "ID": "660102", 
 "CustomerID": "67",
 "CreatedAt": "2016-02-02 16:36:22"
 },
 "Trip5": {
 "VIN": "5GAKRBED0BJ315904",
 "JumpDriveID": "fffc8d", 
 "LotID": "273",
 "LotName": "Pine Ridge", 
 "LastTimeIn": "2016-02-01 15:16:25",
 "StartMileage": "50147",
 "LastMileage": "50945", 
 "FuelVolume": "31.6",
 "FuelPercent": "83.93",
 "ID": "660102", 
 "CustomerID": "67",
 "CreatedAt": "2016-02-02 16:36:22"
 }
}
}

Description Of Each Field Showing In XML/JSON Responses Above

  1. Trip# = Trip count of VIN within last 3 days and max 5 trips
  2. VIN = Vehicle Identification Number
  3. JumpDriveID = JumpDrive device ID assigned to each customer
  4. LotID = Location ID of vehicle at return
  5. LotName = Location name of vehicle at return
  6. LastTimeIn = Time when vehicle returned (in local time zone)
  7. StartMileage = Vehicle mileage at start of trip (in km)
  8. LastMileage = Vehicle mileage at return of trip (in km)
  9. FuelVolume = Fuel in liters at return
  10. FuelPercent = Fuel in percentage at return
  11. ID = Unique Auto Increment ID of each return record stored in the JumpDrive DB
  12. CustomerID = Internal JumpDrive customer identifier
  13. CreatedAt = Timestamp of return record (in local time zone)

Additional Notes

  1. If JumpDrive does not read mileage on a specific vehicle, the customer can specify if they want JumpDrive to provide “0” for LastMileage or provide our estimate of the vehicle’s mileage.
  2. Some vehicles provide raw fuel data in Liters and others provide it in Percentage, JumpDrive calculates both values for all vehicles and provides it to customers and partners.  FuelPercent and FuelVolume are calculated using our data source for the fuel tank size.

Additional questions?

Please email support@jumpdrive.com if you have any questions or require additional support.