This introductory document demonstrates how to use tools such as SoapUI to retrieve XML-formatted data from the API.

The Ctrack External API is divided into three services:

The Membership service, providing information relating to the user, such as their membership of the available business groups.
The TrackingUnit service, providing information and actions relating to the tracking units installed.
The Drivers service, providing information and actions relating to drivers.

Each service exposes WCF endpoints that return XML data via SOAP 1.2, and counterparts that return JSON. If you wish to to access data in JSON format, refer to the REST Quickstart guide instead.

Given a WCF service endpoint ~/Membership.svc/AcquireSecurityToken, the JSON equivalent may be found at ~/Membership.svc/Rest/AcquireSecurityTokenRest.

SOAP API Demonstration - Retrieving Odometer Readings

Most of the information available via the API is accessed by providing the relevant API call with a valid token and the ID of the associated entity (usually a vehicle or driver ID).

In this example, we will demonstrate one way of retrieving odometer data for a specific vehicle.

Step 1 : Configure SoapUI

First, we'll set up SoapUI for testing by loading the WSDL files for each of the Ctrack External API services.

Open SoapUI and press Ctrl+N or go to File -> New Soap Project. The window shown to the right should appear.

Add a project for each of the following WSDL files:

Step 2 : Acquire a security token

A security token is required for all web service calls. We can get one using AcquireSecurityToken and a valid username and password.

Expand the WSHttp_IMembership node in the tree and double-click on the automatically generated Request 1 entry. Replace the ? marks with your username and password, and then press the Play button.

This is your security token, which will be used to access data in future requests. If it is not used for ten minutes it will expire and you (or rather, your client) will need to authenticate again.

Enabling WS-Addressing in SoapUI

When using SoapUI, you may encounter the message "The message with To '' cannot be processed at the receiver, due to an AddressFilter mismatch at the EndpointDispatcher.". To resolve this, open the WS-A panel at the bottom of the Request window and tick the Add default wsa:To checkbox. You will need to do this once for each request window opened.

Step 3 : Retrieve a list of vehicles

Our next step will be to use the GetVehicleMappingsByVehicleRegistrations method of the TrackingUnit service to retrieve a list of the vehicles available to us.

Expand the call tree and locate the associated request. Add in your security token and then remove the tem:vehicleRegs and/or arr:string tags so that the list of vehicles is not filtered before being returned.

Click the play icon to send the request. You should see the response appear on the right hand side:

Step 4 : Find vehicle odometer readings

We are going to use the GetVehicleCurrentRunningDataByIds method to get readings from the odometers of multiple vehicles. The call takes two parameters: a valid security token and a list of vehicle ID's to look up (found using the previous call.)

Expand the call tree and locate the associated request. Add in your security token:

Click the play icon to send the request. You should see the response appear on the right hand side: