API Guide for Developers

Welcome to the GPS Insight API Guide for Developers! This documentation is designed for people familiar with object-oriented programming concepts. You should also be familiar with GPS Insight capabilities from a user's point of view.

Getting Started

An application programming interface (API) specifies how some software components should interact with each other. GPS Insight's API provides a form of communication via XML or JSON coding language to push your fleet’s data from our system to your back-end systems (e.g., ERP, Dispatch, CRM). By using our API you can effortlessly integrate your fleet’s data into your back-end systems to provide transparency into payroll, fuel card transactions, additional documentation, asset management, and more.

The typical process for interacting with our API is broken into three high-level steps. You'll need to:

• Obtain a Session Token.

• Make a Request.

• Process a Response.

Obtain a Session Token

In order to interact with the API, you must obtain a session token. You can obtain a session token through authentication, which can be done in two ways:

• Username/Password: The Username/Password authentication is the simplest method of retrieving a session token. Use this method if you are developing for internal applications where your password can be kept secret.
  
• App Token: The App Token authentication is the most secure method of retrieving a session token by using an alias for your login credentials. Use this method if you want to avoid passing your login credentials via HTTP requests or sharing your portal credentials with vendors. This limited access can be revoked or changed at any time.

Note: The App Token is not less sensitive than a password because it still provides full access to API functions for that user. Using an API App offers the following benefits: It does not allow access to the Portal site, it can be changed or deactivated by admin users, and app usage can be better tracked.

Once you have a session token, all subsequent requests will not require authentication while the session token is active. The token will eventually expire (varies from about a day to a week), so you will need to occasionally re-authenticate.

To obtain a session token with Username/Password

Open a web browser. Copy and paste the following URL into the Address Bar, substituting your Username and Password for the XXXX placeholders: https://api.gpsinsight.com/v2/userauth/login?username=XXXX&password=XXXX The following response appears: Copy the Session Token (shown above highlighted in yellow), and paste it into Notepad. You will use this token when you make a request. (See #2. Make a Request).

To obtain a session token with an App Token

Open a web browser, and log in to portal.gpsinsight.com. From the Menu Bar, hover over the Account menu, point to Manage Users, and click Manage access to api V2 functions. The Manage API Apps page appears. In the API Apps List grid, click API App next to Create New. In the New API App window, enter an App Name and Description, and click Save API App. A new App Token is generated: Copy the App Token (shown above highlighted in yellow), and past it into Notepad. You will use this token when you authenticate. Open a new browser tab. Copy and paste the following URL into the Address Bar, substituting your Username and App Token for the XXXX placeholders: https://api.gpsinsight.com/v2/userauth/login?username=XXXX&app_token=XXXX The following response appears: Copy the Session Token (shown above highlighted in yellow), and paste it into Notepad. You will use this token when you make a request. (See #2. Make a Request).

Make a Request

Technically, you've already made a request (authentication) that returned a session token. Now, you can make additional requests--this time to return data from your GPS Insight account.

Request Structure
Before you can make this request, you must understand the request structure.

Use the table below to understand the parts of the following request structure:

https://api.gpsinsight.com/v2/vehicle/location/xml?session_token=abcd1234&vehicle=truck1

Alert	Example	Required
API Endpoint Specifies the API endpoint or URL (followed by the http protocol	api.gpsinsight.com/v2	x
Class Specifies the service or class.	vehicle	x
Method Specifies the method.	location	x
Output Format Specifies the formatting for responses. Available formats include: json (default): JavaScript Object Notation is the current standard for APIs and Web Services. This is the format used if none is specified. xjson: The head and errors information will be put in a HTTP header labeled X-json. The data section will be put in the HTTP body with no additional structure. xml: A common format for transmission of web services data. text: Output structure will be more human readable. This is good for testing.	xml
Session Token Specifies the session token obtained from authentication.	session_token=abcd1234	x
Method Parameter(s) Specifies the optional parameter(s) within the method. Separate multiple parameters with an ampersand (&).	vehicle=truck1

Note: You can also add an optional, user-specified value that is returned in the response header (128 character max) to use for troubleshooting (i.e., reference_tag=request_00342), but it is not a core element of the request structure.

Process a Response

Response Structure
The default response will be structured with a head section with meta data about the request, an optional errors section, and a data section containing the formatted response data:

{
"head": { . . . },
"errors": [{ . . }],
"data": [{ . . . }]
}

The following table provides an example of the content inside of each section (head, errors, data):

Head Section

Element	Description	Example
status	OK or ERROR if errors were encountered	OK
method	The method used to produce the response	listvehicles
context	The user_context under which the response was generated	customer
request_time	The server time at the request (in MST)	May 21 2014 10:47:38
session_start	The server time at the start of the current session (in MST)	May 21 2014 10:44:47
request_count	The number of times the request has been issued from the current account	1

Error Section

Element	Description	Example
code	Usually a standard HTTP error code such as 400, 404, 500, etc.	403
message	The standard HTTP message that accompanies the code. For security purposes we do not provide detailed error logs	Forbidden (session does not exist)

Body Section

Formatted response varies by method. Refer to the API Reference for examples

Real-World Example

How you process the response depends entirely on your purpose for using the API and the programming language in which the interfacing application is written. GPS Insight provides you with the following simple JavaScript example for how you might use the GPS Insight API to display vehicle location information--in this case on a third-party web map that resides outside of the GPS Insight portal (e.g., your company's website).

https://api.gpsinsight.com/v2/examples/javascript_example.html

IP Whitelist

Due to how frequently the IPs will change our Cloud-Hosted environment, it is not recommended that users whitelist IPs for API purposes. Generally, it will be difficult to keep up with the changing addresses. If you want to try, here is some documentation from AWS about how to stay up to date on the IP addresses.

We recommend, if your policy requires whitelisting, that you whitelist either of our DNSs.

• gpsinsight.com (preferred)
• api.gpsinsight.com