GPS SOAP Services

GPS Insight provides some services available in a standard SOAP format. Our SOAP server uses a standard WSDL connection. Create your SOAP client with the following WSDL URL:

• http://standard.gpsinsight.com/soap/services.php?wsdl

Visit the same URL as a web page to see the current list of available services:

• http://standard.gpsinsight.com/soap/services.php

NOTE: Some customers have reported difficulty with these SOAP services when connecting with .NET or JAVA web services clients. You may consider using our REST web services as an alternative: http://wiki.gpsinsight.com/wiki/support/web_services/rest

This service provides a way for you to test that the server is running normally.

• Method Name: heartbeat
• Parameters:
  • name A test string to return from our SOAP server
• Example Response:

 <response type="heartbeat">
   <test>test</test>
   <errors count="0"/>
 </response>

This service updates various attribues of a single driver. If you specify a reference id it will try to match on that. If that does not match or if it is not specified, it will try to match on a first and last name. If a match is found, the information will be updated for that driver. If no match is found, the information will be inserted as a new driver.

• Method Name: driverUpdate
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • fname The driver’s first name (optional)
  • lname The driver’s last name
  • refid Your internal ID number for this driver (optional)
  • email The driver’s email address (optional)
  • phone The driver’s phone number (10-digit, optional)

• Example Response:

  <response type="driverUpdate">
    <message>Driver was updated</message>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="driverUpdate">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service sends a message to a vehicle’s Garmin.

• Method Name: garminMessage
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A valid vin for any vehicle on your account
  • message A message to send to the vehicle

• Example Response:

 <response type="garminMessage">
   <message>Message sent</message>
   <errors count="0"/>
 </response>

• Example Failure Response:

 <response type="garminMessage">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service returns a list of recently received Garmin messages.

• Method Name: garminGetMessage
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A valid vehicle identifier for any vehicle on your account
  • date (optional) A date from which to query messages
  • type (optional) Restrict messages to a certain type ‘sent’ or ‘received’

• Example Response:

<response type=”garminGetMessages”>

   <vehicle>
     <vin>LK89SDF987DSF</vin>
     <vehicle>Larry</vehicle>
     <lmu_serial>433186876876</lmu_serial>
     <nuvi_serial>38107657657</nuvi_serial>
     <received>
       <message>
         <text>3-28-11-03-GPS Insight</text>
         <date>03/28/2011 10:21:43</date>
       </message>
       <message>
         <text>3-28-11-00-GPS Insight</text>
         <date>03/28/2011 10:21:42</date>
       </message>
     </received>
     <sent>
       <message>
         <text>Leaving Customers Location</text>
         <date>03/28/2011 07:56:45</date>
       </message>
     </sent>
   </vehicle>
 <errors count="0"/>
 </response>

• Example Failure Response:

 <response type="garminGetMessages">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service sends a stop location to a vehicle’s Garmin.

• Method Name: garminDispatch
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A valid vin for any vehicle on your account
  • location An address or lat,lon position to send to the vehicle
  • name A name for the stop location

• Example Response:

 <response type="garminDispatch">
   <message>Dispatch sent</message>
   <errors count="0"/>
 </response>

• Example Failure Response:

 <response type="garminDispatch">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service allows you to programatically create landmarks on your account. Landmarks will be created as circluar landmarks at the given latitude/longitude point with a default radius of 750 feet. They will be assigned to the default group of the given user. Name conflicts will cause another landmark to be created with a incremented sequence number.

• Method Name: landmark
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • latitude Latitude of the landmark’s center
  • longitude Longitude of the landmark’s center
  • label Landmark name

• Example Response:

 <response type="landmark">
   <message>
     LANDMARK: Park City created at lat/lon: 40.63271, -111.44531
   </message>
   <errors count="0"/>
 </response>

This query returns a list of vehicles in a specified group, along with the last-reported (current) location for that vehicle.

• Method Name: location
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A vehicle or group. The vehicle be searched for in the following order:
    • Leave blank for ALL VEHICLES
    • Numeric Vehicle Group ID
    • Vehicle Group Name
    • VIN for a single vehicle
    • Vehicle Label for a single vehicle
    • Partial Vehicle Group Name
    • Partial Vehicle Label
  • time (optional) A time in the past at which the vehicle will be queried (format m/d/y h:m:s)
• Example Response:

  <response type="location">
    <vehicles>
      <vehicle>
        <vin>1GCGG25U241158437</vin>
        <vehicle>Painter Ready 2</vehicle>
        <current>
          <date>10/8/2008</date>
          <time>14:08:34</time>
          <ignition>off</ignition>
          <latitude>33.3454</latitude>
          <longitude>-111.34234</longitude>
          <age_minutes>40</age_minutes>
        </current>
      </vehicle>
    </vehicles>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="location">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This query returns a list of vehicles including addresses and landmarks (if available) for a specified group, along with the last-reported (current) location for that vehicle.

• Method Name: locationDetail
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A vehicle or group. The vehicle be searched for in the following order:
    • Leave blank for ALL VEHICLES
    • Numeric Vehicle Group ID
    • Vehicle Group Name
    • VIN for a single vehicle
    • Vehicle Label for a single vehicle
    • Partial Vehicle Group Name
    • Partial Vehicle Label
  • time (optional) A time in the past at which the vehicle will be queried (format m/d/y h:m:s)
• Example Response:

  <response type="locationDetail">
    <vehicles>
      <vehicle>
        <vin>5GZCZ53486S842028</vin>
        <vehicle>Larae</vehicle>
        <current>
          <date>04/06/2010</date>
          <time>17:00:17</time>
          <ignition>off</ignition>
          <latitude>33.69937</latitude>
          <longitude>-111.92458</longitude>
          <age_minutes>2</age_minutes>
          <address>23437 N Scottsdale Rd, Scottsdale, AZ 85255</address>
          <landmark>GPS Insight Headquarters</landmark>
          <landmark_id>98023</landmark_id>
        </current>
      </vehicle>
    </vehicles>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="locationDetail">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This query returns a link to download a Google Earth KMZ file which will display the current status of the selected vehicles. The URL in the response should be requested separately to download a KMZ file.

• Method Name: mapCurrent
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • group or vehicle (optional) A valid vehicle group id, group name, vin, or vehicle name
  • follow (optional) Whether Google Earth should follow the vehicle when it refreshes
  • trail (optional) A trail of X minutes will be drawn behind the vehicle on the map. (-1 will provide a whole day of trail)

• The group/vehicle can be requested as any of the following and will be discovered in this order:

1. Vehicle Group Id number
2. Vehicle Group Name
3. VIN
4. Vehicle Name
5. Partial Vehicle Group Name
6. Partial Vehicle Name

• Example Response:

  <response type="mapCurrent">
    <url>http://standard.gpsinsight.com/soap/getFile.php?kmz=1234567890</url>
    <errors count="0"/>
  </response>

This query returns a list of vehicles in a specified group, along with the last known odometer reading for that vehicle. UPDATE: this method now returns run time (in hours) as well.

• Method Name: odometer
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • group_id A valid vehicle group id
  • time (optional) A time in the past at which the vehicle will be queried (format m/d/y h:m:s)
• Example Response:

  <response type="odometer">
    <vehicles>
      <vehicle>
        <vin>1GCGG25U241158437</vin>
        <vehicle>Painter Ready 2</vehicle>
        <odometer>71362</odometer>
        <run_time>956.71</run_time>
        <date>Jul 11, 2007</date>
        <time>21:31</time>
        <age_minutes>26540</age_minutes>
      </vehicle>
    </vehicles>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="odometer">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service updates the total odometer reading in miles for a single vehicle. Note: Odometer readings are only transmitted from the vehicle at 50 minute intervals so the updated odometer reading may not be reflected in reports for up to 50 minutes after a vehicle starts moving.

NOTE: You will get an error (210) if you invoke this method for a vehicle that is moving. The vehicle must be stopped to update the odometer.

• Method Name: odometerUpdate
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vin A valid vin for any vehicle on your account
  • odometer A whole number representing the current odometer reading
  • time Odometer reading date/time (optional)

• Example Response:

  <response type="odometerUpdate">
    <message>Odometer for '1GCGG25U241158437' was updated to 8687</message>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="odometerUpdate">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service provides an optimized route based on a list of points and a method of optimization.

• Method Name: optimizeRoute
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • waypoints A string of pairs of street addresses and city, state and/or zip codes, such as [ [”3802 N 27th Street”, “85016”], [”2500 E Camelback Rd”, “Phoenix, AZ”] ]
  • method The method of optimization from this list: fast, short, avoidfwys, morefwys

• Example Response:

  <response type="optimizeRoute">
    <miles>1.89</miles>
    <minutes>4</minutes>
    <waypoints>
      <waypoint><![CDATA[3802 N 27TH ST]]></waypoint>
      <waypoint><![CDATA[2500 E CAMELBACK RD]]></waypoint>
    </waypoints>
    <directions>
      <direction><![CDATA[Depart 3802 N 27TH ST.  ]]></direction>
      <direction><![CDATA[Proceed South on N 27TH ST.  Drive 0 miles]]></direction>
      <direction><![CDATA[Turn Right onto E CLARENDON AVE.  Drive 0.4 miles]]></direction>
      <direction><![CDATA[Turn Right onto N 24TH ST.  Drive 1.3 miles]]></direction>
      <direction><![CDATA[Turn Right onto E CAMELBACK RD.  Drive 0.2 miles]]></direction>
      <direction><![CDATA[Make a U-Turn on E CAMELBACK RD.  Drive 0.1 miles]]></direction>
      <direction><![CDATA[Arrive at 2500 E CAMELBACK RD.  ]]></direction>
    </directions>
    <polyline>
      <point>
        <lat>33.49148</lat>
        <lon>-112.02374</lon>
      </point>
      <point>
        <lat>33.49148</lat>
        <lon>-112.02374</lon>
      </point>
      <point>
        <lat>33.49131</lat>
        <lon>-112.02374</lon>
      </point>
      <point>
        <lat>33.49131</lat>
        <lon>-112.02374</lon>
      </point>
      <point>
        <lat>33.49128</lat>
        <lon>-112.02586</lon>
      </point>

...etc.

    </polyline>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="optimizeRoute">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

Takes a KML file and uploads it as a saved Polyline/Polygon path.

• Method Name: path
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • kml A single polyline or polygon from Google Earth
  • corner Simplify to a corner radius (in feet)
  • name Supply an override name for the path. If you don’t supply a name we will use the name from the placemark. (optional)

• Example Response:

  <response type="path">
    <polyline>Upload Succeeded</polyline>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="path">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This query returns vehicles with a current position close to a specified point. The response will consist of a set of moving vehicles and a set of stopped vehicles. The size of each set is limited to the number of results you request. There is an upper limit of 10 vehicles for each set.

• Method Name: proximity
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • group_id A valid vehicle group id
  • latitude The latitude of the point you want to query
  • longitude The longitude of the point you want to query
  • count The number of vehicles you want of each status (moving or stopped)
• Example Response:

  <response type="proximity">
  <vehicles>
      <moving>
        <vehicle>
          <vin>3GNEK18R0VG118391</vin>
          <vehicle>TRAVIS</vehicle>    
          <date>Jun 17, 2007</date>
          <time>11:43</time>
          <latitude>33.60889</latitude>
          <longitude>-111.88864</longitude>
          <ignition>on</ignition>
          <speed units="MPH">43</speed>    
          <distance units="feet">3984</distance>
          <heading units="degrees">-63</heading>
          <moving>toward</moving>
        </vehicle>   
        <vehicle>
          <vin>1N4DL01D5YC214444</vin>
          <vehicle>PERRY</vehicle>
          <date>Jun 17, 2007</date>
          <time>22:52</time>
          <latitude>33.62802</latitude>
          <longitude>-111.878827</longitude>
          <ignition>on</ignition>
          <speed units="MPH">10</speed>
          <distance units="feet">4737</distance>
          <heading units="degrees">-111</heading>
          <moving>away</moving>
        </vehicle>
      </moving>
      <stopped>   
        <vehicle>
          <vin>1J4FJ68S8WL170897</vin>
          <vehicle>ELLIOT</vehicle>
          <date>Jun 16, 2007</date>
          <time>20:21</time>
          <latitude>33.6394</latitude>
          <longitude>-111.901227</longitude>
          <ignition>off</ignition>
          <speed units="MPH">37</speed>
          <distance units="feet">5001</distance>
          <heading units="degrees">-90</heading>
          <moving>stopped</moving>
        </vehicle>
        <vehicle>
          <vin>1B4HS28Z8YF151931</vin>
          <vehicle>SHAWN</vehicle>
          <date>Jun 17, 2007</date>
          <time>19:30</time>
          <latitude>33.64203</latitude>
          <longitude>-111.926827</longitude>
          <ignition>off</ignition>
          <speed units="MPH">35</speed>
          <distance units="feet">50536</distance>
          <heading units="degrees">166</heading>
          <moving>stopped</moving>
        </vehicle>
        <vehicle>
          <vin>1GCCS139278128839</vin>
          <vehicle>JONATHAN</vehicle>
          <date>Jun 17, 2007</date>
          <time>23:03</time>
          <latitude>33.61422</latitude>
          <longitude>-112.0384</longitude>
          <ignition>off</ignition>
          <speed units="MPH">12</speed>
          <distance units="feet">53426</distance>
          <heading units="degrees">40</heading>
          <moving>stopped</moving>
        </vehicle>
    </stopped>
    </vehicles>
    <sourcePoint>
      <latitude>33.503549</latitude>
      <longitude>-111.923258</longitude>
    </sourcePoint>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="proximity">
   <errors count="1">
     <error code="201">Requested vehicle count is too high</error>
   </errors>
 </response>

This service lets you test your username and password for authentication validity.

• Method Name: testLogin
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
• Example Response:

 <response type="testLogin">
   <test>Login Success</test>
   <errors count="0"/>
 </response>

• Example Failure Response:

 <response type="testLogin">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

This service will retrieve the name and information on a single vehicle including driver if specified.

• Method Name: vehicle
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vehicle A vin, vehicle, or partial vehicle name

• Example Response:

  <response type="vehicle">
    <vehicle>
      <vin>1H2093482093579</vin>
      <vehicle>Grant</vehicle>
      <color>Black</color>
      <make>Honda</make>
      <model>Civic</model>
      <model_year>2002</model_year>
      <serial_number>24235</serial_number>
      <phone_number></phone_number>
      <email_address>support@gpsinsight.com</email_address>
      <driver_fname>Grant</driver_fname>
      <driver_lname>Anderson</driver_lname>
      <driver_refid></driver_refid>
    </vehicle>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="vehicleUpdate">
   <errors count="1">
     <error code="203">Ambiguous request.  More than one vehicle would be returned</error>
   </errors>
 </response>

This service updates various attribues of a single vehicle. Only the vin number and label are required but the others must be added in order if they are to be updated. NOTE: This service will update the vehicle name if it is different than the existing name but the VIN must match with an existing vehicle.

This service does not update our records immediately, rather it is scheduled for update in the near future. Therefore, a successful response means the record has been successfully scheduled for update within a few minutes.

• Method Name: vehicleUpdate
• Parameters:
  • username Your current GPS Insight username
  • password Your current GPS Insight password
  • vin A valid vin for any vehicle on your account
  • label A new or existing label for a vehicle
  • color (optional)
  • license (optional)
  • license country (2-digit, optional)
  • license state (2-digit, optional)

• Example Response:

  <response type="vehicleUpdate">
    <message>Vehicle '1GCGG25U241158437' was updated</message>
    <errors count="0"/>
  </response>

• Example Failure Response:

 <response type="vehicleUpdate">
   <errors count="1">
     <error code="100">Invalid username or password</error>
   </errors>
 </response>

• 100 - Invalid username or Password
• 105 - Service currently unavailable
• 201 - Requested vehicle count is too high
• 202 - Requested vehicle group is invalid
• 203 - Ambiguous request. More than one vehicle would be returned
• 210 - Requested vehicle is running and the ignition should be off

>>See also: Map Book Web Services

>>See also: REST Web Services