Using Query Services

Queries allow you to issue various requests from any standard cell phone with SMS service, from an attached Garmin device, or from an authorized email address. Once your phone or email address is authorized, the portal offers several query-based services for your account: Admin Functions, Driver Functions, Alert Monitor Functions, and Garmin Functions. Queries must be formatted according to a specific syntax in order to receive a valid response.

Authorize Your SMS-Enabled Device

Before using query services on your phone, you must authorize your device using your portal credentials for your account. Authorization is a one-time setup process.

Authorization of an SMS number happens automatically if the number was included in an SMS message sent from the portal. You can view authorized numbers for your account by opening the  portal and going to Account > Manage UsersAuthentication for email and SMS queries.

To authorize your SMS-enabled device

  1. Compose a new text message using the following syntax (substitute your username and password for the placeholders shown with brackets):

gps login [username] [password]

  1. Send the message to 477-477 (GPSGPS).

If your credentials were sent successfully, you’ll receive a confirmation message: “Login succeeded. Proceed with any GPS command”

Authorize Your Email Address

Before using query services in an email, you must authorize your email address in your account and then create token(s) for each vehicle group that you want to isolate. Authorization is a one-time setup process.

To authorize your email address:

  1. From the portal, hover over the Account menu, click Manage Users, and click Authentication for email and SMS queries.

The Authenticate Phones for SMS Query page opens in a new browser tab.

  1. In the Email List grid, click Email next to Register New.

  1. In the Add New Email window, enter your email address, and associate it to a user account.
  2. Click Add Email.

A success message indicates that the address was saved.

  1. From the bottom of the Group Token List grid, click Group Token next to Register New.
  2. In the Add New Group Token window, choose the username for which you want to associate groups, and then choose a vehicle access group.
  3. Click Add Group Token.

A new token (XXXX) is created for the selected vehicle group. You’ll use this token in the “To” address when you send query-based emails.

You can send individual messages to a particular vehicle within the group token when you specify the vehicle in the query. The token just ensures that you have access to the vehicles within the group.

  1. From the Query Wizard, click Email.
  2. When the Query Wizard expands, choose an email address from the list of authorized users.
  3. Choose a Vehicle Group (group token).

The Query Wizard refreshes to show the ‘To’ Address that you must use whenever sending query-based emails to the selected vehicle group:

Send Messages using Query Functions

The following queries are available to use with SMS messaging, email messaging, or Garmin messaging (only where indicated). For phone-based queries, send messages to 477-477 (GPSGPS). For email-based queries, send messages to the customized address(es) for your username. Responses are typically received 5-30 seconds after the query has been sent. Input is not case-sensitive.

Admin Functions

Admin functions require authorization.

Query Syntax Response Example(s) Notes
Current Location gps [vehicle name]

Example: gps TR-150
TR-150: Idle stop for 4 min at Headquarters
OR
TR-150: 65 mph WNW (75 max) at 19001 N. Scottsdale Road, Scottsdale, AZ (33.6594398 -111.9247721)
[Vehicle name] can be full or partial. All matching vehicles are returned in the response. Append the keyword address to return an address instead of a landmark name (if applicable).
Append the keyword/value cc [recipient number] to send the response to another recipient.
Group Location gps [group name] group

Example: gps Delivery group
TR-150: Stopped 8 hrs, 5 min at 19001 N. Scottsdale Road, Scottsdale, AZ (33.6594398 -111.9247721)
TR-151…[repeat for each vehicle in the group]
[Group name] cannot be partial.
Set Landmark gps [vehicle name] landmark [new landmark name]

Example: gps TR-150 landmark Checkpoint D38
LANDMARK: checkpoint d38 created at lat/lon: 33.6594398 -111.9247721 [Vehicle name] must be full name (no partials).
Driving Distance gps [vehicle name] distance [entity]

Example: gps TR-150 distance headquarters
TR-150 (42 mph ENE (max)) is 21.2 mi. drive from Headquarters (about 33 min) The keyword distance can be shortened to dist. [Entity] can be a vehicle name (full or partial), a landmark, or a street address. Use commas between address parts.
Close Vehicles gps [vehicle name] close

Example: gps TR-150 close
VN-173 35 yards E stopped
VN-174 409 yards N 34 mph W -41 sec
VN-175…[repeat for each vehicle within range]
[Vehicle name] can be full or partial. All matching vehicles are returned in the response.
Moving vehicles report the number of seconds between when the two vehicles according to the last time they reported. Positive = queried vehicle reported first; negative = response vehicle reported first. In the example, VN-174 reported 41 seconds ago, which means the distance (409 yards) may have changed since it was originally estimated (assuming the vehicle continued moving W at 34 mph).
Register Vehicle Phone Number gps [vehicle name] driver [phone number]

Example: gps TR-150 driver 5553859399
5553859399 was assigned to 'TR-150' [Phone number] is necessary only if sending the query from a different phone number.

Driver Functions

Driver functions do not require authorization, but a driver’s phone number must be associated with a vehicle before issuing any of these queries.

Query Syntax Response Example(s) Notes
Driver Lookup by ID gps id [driver id] or gps [driver id] id

Example: gps id 09283
Driver 'Sally Jones (09283)' is assigned to vehicle (TR-150) This query is commonly used when auto driver assignment is not installed; it provides a sanity check to see which driver is currently logged into a vehicle.
Driver Assignment gps [vehicle name] driver [first last, or last, or reference ID]
Example: gps TR-150 driver Sally Jones
Driver 'Sally Gypsy' logged into 'TR-150' [Vehicle name] is optional if the driver's SMS number is already assigned to the vehicle.
Fuel Purchase gps [vehicle name] fuel $[cost] [gallons] gallons [odometer] odo

Example: gps fuel 12.697 gallons $45.19
Fuel Purchase Recorded [Vehicle name] is optional if the driver's SMS number is already assigned to the vehicle. [Cost] must follow the keyword $. [Gallons] must precede the keyword gal or gallons. [Odometer] is optional. Must precede the keyword odo.
Odometer Update gps [vehicle name] odo [odometer value]

Example: gps odo 31773
Odometer for 'TR-150' was updated to 31773 [Vehicle name] is optional if the driver's SMS number is already assigned to the vehicle. [Odometer value] must not use punctuation.
Runtime Update gps [vehicle name] runtime [runtime value]

Example: gps runtime 1301
TR-150 was updated to 1301 [Vehicle name] is optional if the driver's SMS number is already assigned to the vehicle. [Runtime value] must not use punctuation.
Stop Notes gps [vehicle name] note [note text]

Example: gps note customer was not home for delivery
Your note was received Stop notes are viewable on 3D History maps and the Stop Notes report. [Vehicle name] is optional if the driver's SMS number is already assigned. [Note text] can include images when using email (not SMS) to record notes.
Stop stop Number blocked. We will no longer send messages to [phone number]. Blocked phone numbers are visible on the Manage Vehicles Contact Info page. In order to remove a stop request, contact Support.

Alert Monitor Functions

Alert monitor functions require authorization. A monitor tells the system to look for alert conditions. Alert monitors differ from other queries in that you should receive two responses: 1) Confirmation that the monitor is set, 2) Confirmation that alert conditions have been met (may not happen immediately).

Query Syntax Response Example(s) Notes
Parking Monitor gps [vehicle name] parked

Example: gps TR-150 parked
First Response: 'TR-150' is being monitored. You will be notified as soon as we see it is running.
Second Response (occurs when the vehicle's ignition changes from off to on): TR‑150 is running as of 2:51:00 PM (0 MPH).
[Vehicle name] must be full (no partials). Monitor expires the first time the alert conditions are met. No additional alerts will occur unless you set another monitor.
Meeting Monitor gps [vehicle 1 name] meet [vehicle 2 name] [miles]

Example: gps TR-150 meet TR-151 3
First Response: TR-150 and TR-151 are being monitored. You will be notified as soon as we see them within 3 miles of each other.
Second Response (occurs when the vehicles are within X miles of each other): TR-151 (parked) is 0.03 miles SE from TR-150 (parked).
[Vehicle name] must be full (no partials). [Miles] is optional. If not specified, the default is 1 mile. Monitor expires the first time the alert conditions are met. No additional alerts will occur unless you set another monitor.

Garmin Functions

Garmin functions require authorization. You must also be using Garmin services and have Garmin devices attached to your devices.

Query Syntax Response Example(s) Notes
Garmin Dispatch gps [vehicle name] dispatch [location]

Example: gps TR-150 dispatch Headquarters
The Garmin device in the vehicle receives a dispatch notice. [Vehicle name] must be full (no partials). The keyword dispatch can be shortened to dis. [Location] can be a landmark name or street address. (Use commas between address parts.)
Garmin Message gps [vehicle name] garmin [message]

Example: gps TR-150 garmin Happy Flag Day!
The Garmin device in the vehicle receives a message. [Vehicle name] must be full (no partials). The keyword garmin can be shortened to gm.
Stop Notes gps [vehicle name] note [note text]

Example: gps note customer was not home for delivery
Your note was received Stop notes are viewable on the Garmin or SMS Messaging Dashlet(s), the SMS Messaging or Garmin Integration Pages, and the Stop Notes report. [Vehicle name] is optional if the driver's SMS number is already assigned.
Stop stop Number blocked. We will no longer send messages to [phone number]. Blocked phone numbers are visible on the Manage Vehicles Contact Info page. In order to remove a stop request, contact Support.

USPS Routing Features

These functions relate to USPS integration. You must be using USPS web services and have a valid CRID to utilize this function.

Query Syntax Response Example(s) Notes
USPS Contracts gps usps contracts

Example: gps usps contracts
ConID: 123XYZ (trip ID: 101,102) The response will have two parts: The Contract ID from USPS (ConID) and the trips available for assignment within this Contract ID (required for assignment).
USPS Assign gps [vehicle name] usps [ConID] [action] [trip ID] [date or NASS]

Example: gps Truck5 usps 4562 de 4

Example: gps Truck5 usps 4562 de 4 11/11/2011

Example:gps Truck5 usps 4562 de 4 7031
'Truck5' has been assigned to contract '4562 de 4' and data is being sent to USPS Assigning a vehicle with a 'DE' or 'ER' action will initiate a data feed about this vehicle to the USPS. Assigning a vehicle with a 'AR' action will terminate the data feed after sending a final 'Arrival' notification. USPS contracts should be set up ahead of time by Support. Use 'usps contracts' query to test for available contracts. Messages sent from Garmin can be reviewed in the Garmin page (Custom > Garmin > Open)