MyGeotab URLs

This guide explains how to format a URL (Uniform Resource Locator) to obtain access to a specific page/feature in MyGeotab. This can be used to link to MyGeotab from an Internet application, sending an email notification, third-party applications and other customized functions.

Link to a page

To create a link to a page, the following URL structure is used:

https://<serverName>/<databaseName>/#<page>,<parameters>

Note: The portions of the examples noted with < and > (e.g. <serverName>) indicate where the user will enter information specific to their requirements.

Item

Description

serverName

The name of the server the database is on. For example, my.geotab.com

databaseName

The name of the database. This is typically the company name used during registration. If there are spaces in the name, they are replaced with underscore characters (_)

page

The MyGeotab web application page name

parameters

Additional arguments to apply to the request. For example, ‘currentSortMode:deviceName’ will sort the devices on the device list page by name. Note: each additional parameter is separated by a comma

Example:

Browse to your database using this URL format

https://<my3.geotab.com>/<g560>/#devices

Note: If you are not yet logged in, you will be prompted for your credentials.

Standalone pages

Standalone pages are used to get a my.geotab.com page without the header and side menu. This is useful when specific functionality is required, for example adding a new vehicle to the system.

To create a link to a page, the following URL structure is used:

https://<serverName>/<databaseName>/geotab/checkmate/ui/<page>,<parameters>

Example:

https://my3.geotab.com/g560/geotab/checkmate/ui/devices.html

Note: If you are not yet logged in, you will be prompted for your credentials.

Passing parameters to a page

Parameters are added at the end of the URL and each is separated by a comma. They work the same for both the normal and standalone page types. It is also important to note when no parameters are requested, the page will load with the default settings. The parameter and its value are always separated by a colon (“:”).

Example:

These links will navigate to the map pages showing the live position of a device with id ‘b21’, and with the group ‘b1234’ highlighted.

https://<serverName>/<databaseName>/#map,highlightGroup:b1234,liveVehicleIds:!(b21)

https://<serverName>/<databaseName>/geotab/checkmate/ui/map.html#highlightGroup:b1234,liveVehicleIds:!(b21)

List of pages and accepted parameters

Page: devices

The list of devices in the system.

Default: list of all devices sorted by name.

Parameter

Description

Values

sortMode

Sorts the list of devices in a specific way

byType — sort by device
byName — sort by name

groupSelection

Divides the device list into subheadings, which are children groups of the selected parent

<groupName> — parent group name that the device belongs to

Examples:

https://<serverName>/<databaseName>/#devices,groupSelection:someGroup
https://<serverName>/<databaseName>/#devices,sortMode:byName
https://<serverName>/<databaseName>/#devices,sortMode:byType

Page: device

Edit an individual device.

Default: no default page, you must have an id parameter.

Parameter

Description

Values

id

Goes to a devices edit page

<deviceId>

Example:

https://<serverName>/<databaseName>/#device,id:<b12>

Page: deviceSerialNo

Add a new device.

Default: add new device page. No parameters required.

Example:

https://<serverName>/<databaseName>/#deviceSerialNo

Page: map

The map viewer page.

Default: shows the map with your default map settings.

Parameter

Description

Values

liveVehicleIds

Used to show the live location of a device by its id

<list of deviceIds>

planRoutes

Show a route on the map

<list of deviceIds>

highlightGroup

Will highlight all devices in that group on the map display

<groupId>

Examples:

https://<serverName>/<databaseName>/#map,liveVehicleIds:!(b12,b65,b3)
https://<serverName>/<databaseName>/#map,planRoutes:!(b2,b3,b1)

Page: tripsHistory

The detailed vehicle trip history page.

Default: will request you to select settings from the drop down menus. You can define the settings using the parameters.

Parameter

Description

Values

dateRange

Sets the range of dates for the trips

(interval:<value>) — values: ‘Today’, Yesterday’, ‘This Week’, ‘Last Week’, ‘This Month’, ‘Last Month’

(interval:custom,startDate: ‘<date1>’,endDate:‘<date2>’)

entityType

Show activity for drivers or devices

Device — list device activity
Driver — list driver activity

selectedEntities

Vehicles to list information for

!(<listOfEnitities>) or ‘all’

Examples:

https://<serverName>/<databaseName>/#tripsHistory,dateRange:(interval:<Today>),entityType:Device,selectedEntities:!(<b1,b7,b21>)
https://<serverName>/<databaseName>/#tripsHistory,dateRange:(interval:<custom,startDate:'2015-08-08T04:00:00.000Z',endDate:'2015-08-09T03:59:59.999Z>'),entityType:<Driver>

Page: zones

The zone list page.

Default: list of all zones by name.

Parameter

Description

Values

sortOrder

The list order

 1 — list alphabetically
-1 — Invert the list

sortMode

Choose how the sort the list

zoneName — sorts by name
zoneType — sorts by type
zoneGroup — sorts by group

Examples:

https://<serverName>/<databaseName>/#zones,sortOrder:-1,sortMode:zoneGroup
https://<serverName>/<databaseName>/#zones,sortMode:zoneName
https://<serverName>/<databaseName>/#zones,sortMode:zoneType

Page: zone

The zone edit page.

Default: No default available. Needs parameters.

Parameter

Description

Values

id

Goes to edit page for the selected zone

<zoneId>

Example:

https://<serverName>/<databaseName>/#zone,id:<b12>

Page: notifications

The notification list page.

Default: full list of user notifications listed in order of most recent time.

Parameter

Description

Values

sortOrder

The list order

 1 — list the most recent time first
-1 — invert the list

sortMode

Selects the sort mode

machineName — sorts by machine

showDismissed:!t

Shows all dismissed messages

None

Example:

https://<serverName>/<databaseName>/#notifications,sortOrder:-1,sortMode:machineSort,showDismissed:!t

Page: users

The user list page.

Default: list of all current users.

Parameter

Description

Values

sortOrder

The list order

 1 — list alphabetically
-1 — invert the list

Example:

https://<serverName>/<databaseName>/#users,sortOrder:-1

Page: user

The user edit page.

Default: goes to add a new user page.

Parameter

Description

Values

id

The users id. Will link to the edit page for that user

<userId>

Example:

https://<serverName>/<databaseName>/#user,id:<b32>

Page: options

The user preferences page.

Default: edit user preferences page, no parameters required.

Example:

https://<serverName>/<databaseName>/#options

Credentials

Links That include username and database

It is possible to insert username and database credentials into a URL. Note that the user will be required to be logged in to utilize these types of links.

MyGeotab Page Example:

https://<serverName>/<databaseName>/?('userName':'<userName>','database':<databaseName>)#<page>

Standalone Page Example:

https://<serverName>/<databaseName>/geotab/checkmate/ui/<page>#credentials:(database:<databaseName>,userName:'<userName>')

We do not support passing the password credential through the URL because it is unsafe. The way around this is to use a session Id.

Links that include username, database and session id:

It is also possible to include a session id in the URL. This will not prompt the user to login if the session id is valid.

MyGeotab Page Example:

https://<serverName>/<databaseName>/#<page>,token:('userName':'<userName>','sessionId':'<sessionId>','database':'<databaseName>')

Standalone Page Example:

https://<serverName>/<databaseName>/geotab/checkmate/ui/<page>#credentials:('userName':'<userName>','sessionId':'<sessionId>','database':'<databaseName>')

Getting the session Id using the API:

Refer to the ‘Concepts’ page, under the section ‘Authentication’. Within that section the instructions explain the process of authenticating a user to obtain their session id.

Security Using the Session Id

By using the sessionId, a valid login is created for that account. Another user will be able to fully access that account as long as the sessionId credential remain valid. If an application is being created where the sessionId could potentially be viewed by another party, it is advised to generate the credentials using an account with access limited only to the necessary data.

Embedding MyGeotab inside an iFrame

Trusted domains only

Due to the risk of ClickJacking, MyGeotab will instruct the browser to prevent MyGeotab from loading inside a frame that came from an arbitrary domain. Customers wishing to utilize this feature must meet the minimum security requirements. Please contact your reseller for more details.