The Telematics Guru API supports the generating of multi-asset location-sharing links via API call. 

This allows you to share a temporary link. This link grants anyone who has it a view of the live location of the asset(s) for the configured period - without needing to create/remove Telematics Guru Logins. 

Multi-Asset Location Sharing can be useful for applications such as:

• Transport Companies: share the location of delivery vehicles while they are on route
   
• Rental Companies: share hired assets with the end customer while they are on hire. 

The ability to generate a link via API call allows for integration into other systems such as a dispatch, invoice, or other job system - so that the links are programmatically generated when an asset goes on hire for example. 

Authentication

To use this API, first authenticate using your login details for Telematics Guru.

POST to https://api-<instance>.telematics.guru/user/authenticate, where instance refers to the Telematics Guru server you are on, such as EMEA03 for example. See TG Region Specific Details for more information. The following body must be used: 

The last key and value are optional, and depend on whether you have 2-factor authentication enabled.

Please note that the above body must be URL encoded.

After posting this, you will receive a bearer access token, with an associated expiration time. This token must be used as the authentication bearer token for the following messages.

Retrieving Organisation ID

The link must be received from a certain organisation, and so the organisation ID is required. As a rule, you will only have access to whichever organisations and assets you have direct access to within the Telematics Guru User Interface. To retrieve this, you must GET from the following endpoint:

https://api.instance.telematics.guru/v2/user/organisations

This will return a list of accessible organisations and their associated IDs.

Retrieving Asset ID

Following this, you must retrieve the IDs of the specific assets you would like to create a link for. To do this, you must GET from https://api-instance.telematics.guru/organisation/OrgID/asset, where OrgID is the previously found organisation ID. 

This will return a list of accessible assets on that organisation, as well as their live view data. It will look as follows:

{

    "id": 12354,

    "assetTypeId": 2,

    "name": "Generic Asset",

    "code": null,

    "statusHumanized": "Driving from Location for Number of Days",

    "speedKmH": 10,

    "inTrip": true,

    "batteryLevelStatus": 1,

    "lastConnectedUtc": "2017-01-26T13:11:03.23",

    "allocatedDriverId": null,

    "lastLatitude": -0.0000000,

    "lastLongitude": 0.0000000,

    "isEnabled": true,

    "heading": 45

  }

The ID in the above snippet will be used in the command for the link.  If you set up an array of Asset IDs, you will receive location sharing for those assets. 

Calling for an Asset Location Share Link

Calling for the Multi-Asset Location Sharing link requires using the POST command to Telematics Guru to receive your temporary link. This needs to be done using the endpoint: 

https://api-[instance].telematics.guru/organisations/OrganisationID/SharedMultiAssetLocationCreate

When POSTing to the above endpoint, the body needs to be in raw JSON, and must be structured as follows:

{
	"StartDateTimeUtc": "2013-01-01T00:00:00Z"
	"SharedForMinutes": 60
	"ShareName": "Example Share Name"
	"Message": "Your message along with the link will go here"
	"AssetIds": [X, Y, Z]
}

Where Asset IDs is an array of all the assets you want to create the link for, with the minimum being one asset. 

If you call for an asset-sharing link after it is meant to expire, a message will be returned saying that the link has expired due to the specified date range.
 

cURL Example of Retrieving Multi-Asset Location Sharing Link

The following example follows the above guide in cURL format, demonstrating how to use this API call.

Authentication

curl --location "httpss://api-emea03.telematics.guru/v2/user/authenticate" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "username=Your Username" \
--data-urlencode "password=Your Password" \
--data-urlencode "grant_type=password" \
--data-urlencode "otp=Your one time pin"

Note that since this is URL encoded, the username of name@email.com must be encoded name%40email.com.

After this, you will receive your valid bearer token.
 

Retrieving Organisation ID

curl --location "https://api-emea03.telematics.guru/v2/user/organisations" \
--header "Authorization: Bearer (Your Bearer Token received in the previous step)"

After this step, you will receive a list of the organisation IDs for all the organisations visible to your account.

Retrieving List of Assets

curl --location "https://api-emea03.telematics.guru/organisation/OrgID/asset" \
--header "Authorization: Bearer (Your Bearer Token)"

Where OrgID is the previously chosen organisation ID.

This will return a list of all assets accessible in the chosen organisation, with some general associated information. You will retrieve the asset ID from this step.

Retrieving Multi-Asset Location Share Link

curl --location "http://api-emea03.telematics.guru/organisation/OrgID/SharedMultiAssetLocationCreate" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer [BEARER TOKEN]" \
--data "{
  \"StartDateTimeUtc\": \"2024-04-11T12:00:00Z\",
  \"SharedForMinutes\": 60,
  \"ShareName\": \"Example Share\",
  \"Message\": \"This is a sample message\",
  \"AssetIds\": [X, Y, Z]