MiX Telematics REST API Documentation

GET /trips/:since

Requests trips for vehicles or drivers visible to the authenticated user which occurred on or after the specified :since parameter. Use this call to retrieve near real-time updates. Pass the latest DeviceTimestamp returned by the previous call with each subsequent call.

Note: The time passed in the since parameter may not be more than 1 hour earlier than the current server time or else '413 Request Entity Too Large' will be returned.

Parameters

:since

(required)

Indicates that only trips generated on or after this date and time should be returned. Pass a date/time as seconds since 1970 or a date/time string in the format YYYYMMDDHHmmss. If the authenticated user's globalisation preferences (see GET account/profile) are passed with this request, the value passed in this parameter should be in the time zone specified by the globalisation preferences. Otherwise the value passed should be UTC.

auth

(required)

The authentication token received in response to the call to POST authentication_credentials or GET authentication_token. Applications should pass the authentication token in the custom "X-auth" HTTP header to avoid passing it in in the query string.

system_type

(optional)

Indicates that only trips for vehicles or drivers from the specified system should be returned.

organisation_id

(optional) *

Indicates that only trips belonging to the specified organisation should be returned. * Required when retrieving data from the Fleet Manager system. Ignored when retrieving data from the X-Drive system.

vehicle_ids

(optional)

A comma separated list of vehicle identifiers indicating that only trips for the vehicles with the specified identifiers should be returned.

driver_ids

(optional) *

A comma separated list of driver identifiers indicating that only trips for the drivers with the specified identifiers should be returned. NOTE: This parameter cannot be used in conjunction with the vehicle_ids parameter and will be ignored if both are passed. * Ignored when retrieving data from the X-Drive system.

include_sub_trips

(optional) *

Indicates whether or not to include the sub trips which make up the trips that are returned. Passing a value of 1, t, or true will result in sub trips being included. * Ignored when retrieving data from the Asset Management or X-Drive system.

include_locations

(optional)

Indicates whether or not to include locations/addesses resolved by reverse-geocoding for the positions that are returned. Passing a value of 1, t, or true will result in locations being included. NOTE: Including locations is substantially slower, and should only be done when absolutely necessary! Where possible, applications should call GET geocoding/location or POST geocoding/coordinates to retrieve locations/addresses when required.

callback

(optional)

Only available for JSON format. If supplied, the response will use JSONP format with a callback of the given name.

date_format

(optional)

Only available for JSON format. If supplied, the response will contain JSON dates serialized in the specified format. 0 = Timestamp with offset e.g. "\/Date(1346080140000+0500)\/". 2 = ISO8601 e.g. "2012-08-27T15:09:00.0000000+05:00". Applications may pass this parameter in the custom "X-DateFormat" custom HTTP header instead of this query parameter.

globalisation

(optional)

The authenticated user's globalisation preferences as received in response to the call to GET account/profile or in the custom "X-Globalisation" HTTP header returned in response to authenticated calls. Applications should pass this back to the server with every call, either in this parameter, or in the the custom "X-Globalisation" HTTP header if automatic conversion of values is required.

Request Content Type

N/A

Response

Returns a maximum of 100 Trip resources in the requested format. If 100 are returned, it is likely that more data is available and an additional call should be made using the latest DeviceTimestamp that was returned as the since parameter.

Response Content Type

application/json, application/javascript (JSONP), application/xml or text/csv as requested

Give It A Try...

Enter appropriate parameter values then click on the link which appears to try the API call...

Note: You must have JavaScript support enabled in your browser to use this feature.

:since

(required)

auth

(required)

system_type

(optional)

organisation_id

(optional) *

vehicle_ids

(optional)

driver_ids

(optional) *

include_sub_trips

(optional) *

include_locations

(optional)

callback

(optional)

date_format

(optional)

globalisation

(optional)

Response format

Request Examples

GET /trips/20110101000000?auth=a78581e7935349c39873812572cda216
GET /trips/20110101000000.xml?auth=a78581e7935349c39873812572cda216&trip_type=8973754b-f084-4ba8-b954-483c6084f607
GET /trips/20110101000000.json?auth=a78581e7935349c39873812572cda216
GET /trips/20110101000000.csv?auth=a78581e7935349c39873812572cda216
GET /trips/20110101000000?auth=a78581e7935349c39873812572cda216&vehicle_id=8973754b-f084-4ba8-b954-483c6084f607
GET /trips/20110101000000?auth=a78581e7935349c39873812572cda216&driver_id=8973754b-f084-4ba8-b954-483c6084f607

Response Examples

JSON body:

[{"SystemType":"AssetManagement","VehicleId":"c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc","ReceivedTimestamp":"\/Date(1306295232870+0000)\/","TripType":"Unknown","DriverId":"047d6331-23b4-42c9-bca6-26a3f67c4e85","StartTimestamp":"\/Date(1306295250000+0000)\/","StartPosition":{"SystemType":"AssetManagement","VehicleId":"c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc","DeviceTimestamp":"\/Date(1306295250000+0000)\/","ReceivedTimestamp":"\/Date(1306295232867+0000)\/","DriverId":"047d6331-23b4-42c9-bca6-26a3f67c4e85","Odometer":116.52,"Longitude":7.567398,"Latitude":50.36023,"Speed":0,"Heading":182,"Altitude":79,"Hdop":2,"Vdop":2,"Pdop":3,"Satellites":8,"Age":0},"EndTimestamp":"\/Date(1306295259000+0000)\/","EndPosition":{"SystemType":"AssetManagement","VehicleId":"c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc","DeviceTimestamp":"\/Date(1306295259000+0000)\/","ReceivedTimestamp":"\/Date(1306295232870+0000)\/","DriverId":"047d6331-23b4-42c9-bca6-26a3f67c4e85","Odometer":116.52,"Longitude":7.567451,"Latitude":50.36024,"Speed":0,"Heading":119,"Altitude":79,"Hdop":2,"Vdop":2,"Pdop":3,"Satellites":8,"Age":0},"Distance":0}]

XML body:

<ArrayOfTrip xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Trip SystemType="AssetManagement" VehicleId="c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc">
		<ReceivedTimestamp UtcOffset="0">2011-05-25T03:47:12.87Z</ReceivedTimestamp>
		<TripType>Unknown</TripType>
		<DriverId>047d6331-23b4-42c9-bca6-26a3f67c4e85</DriverId>
		<StartTimestamp UtcOffset="0">2011-05-25T03:47:30Z</StartTimestamp>
		<StartPosition SystemType="AssetManagement" VehicleId="c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc">
			<DeviceTimestamp UtcOffset="0">2011-05-25T03:47:30Z</DeviceTimestamp>
			<ReceivedTimestamp UtcOffset="0">2011-05-25T03:47:12.867Z</ReceivedTimestamp>
			<DriverId>047d6331-23b4-42c9-bca6-26a3f67c4e85</DriverId>
			<Odometer>116.52</Odometer>
			<Longitude>7.567398</Longitude>
			<Latitude>50.36023</Latitude>
			<Speed>0</Speed>
			<Heading>182</Heading>
			<Altitude>79</Altitude>
			<Hdop>2</Hdop>
			<Vdop>2</Vdop>
			<Pdop>3</Pdop>
			<Satellites>8</Satellites>
			<Age>0</Age>
		</StartPosition>
		<EndTimestamp UtcOffset="0">2011-05-25T03:47:39Z</EndTimestamp>
		<EndPosition SystemType="AssetManagement" VehicleId="c89a9db7-46a5-4fb4-ab28-dc0ae807b5dc">
			<DeviceTimestamp UtcOffset="0">2011-05-25T03:47:39Z</DeviceTimestamp>
			<ReceivedTimestamp UtcOffset="0">2011-05-25T03:47:12.87Z</ReceivedTimestamp>
			<DriverId>047d6331-23b4-42c9-bca6-26a3f67c4e85</DriverId>
			<Odometer>116.52</Odometer>
			<Longitude>7.567451</Longitude>
			<Latitude>50.3602448</Latitude>
			<Speed>0</Speed>
			<Heading>119</Heading>
			<Altitude>79</Altitude>
			<Hdop>2</Hdop>
			<Vdop>2</Vdop>
			<Pdop>3</Pdop>
			<Satellites>8</Satellites>
			<Age>0</Age>
		</EndPosition>
		<Distance>0</Distance>
	</Trip>
</ArrayOfTrip>

CSV body:

SystemType,VehicleId,ReceivedTimestamp,TripType,DriverId,CoDriverId,StartTimestamp,StartPosition,EndTimestamp,EndPosition,Distance,EndOdometer,MaxSpeed,OverSpeedingCount,MaxAcceleration,HarshAccelerationCount,MaxDeceleration,HarshBrakingCount,SubTrips
AssetManagement,c519b527-c853-4047-bf61-e54d367dfa8b,"2012-07-06T07:28:58.973Z",Unknown,239965e3-ba60-4abd-91bf-e212e2af68af,,"2012-07-06T07:28:51Z","{SystemType:AssetManagement,VehicleId:c519b527-c853-4047-bf61-e54d367dfa8b,DeviceTimestamp:2012-07-06T07:28:51Z,ReceivedTimestamp:2012-07-06T07:28:58.847Z,DriverId:239965e3-ba60-4abd-91bf-e212e2af68af,Odometer:128681.3,Longitude:8.667021,Latitude:50.19679,Speed:5,Heading:265,Altitude:143,Hdop:1,Vdop:1,Pdop:1,Satellites:9,Age:1}","2012-07-06T07:29:14Z","{SystemType:AssetManagement,VehicleId:c519b527-c853-4047-bf61-e54d367dfa8b,DeviceTimestamp:2012-07-06T07:29:14Z,ReceivedTimestamp:2012-07-06T07:28:58.933Z,DriverId:239965e3-ba60-4abd-91bf-e212e2af68af,Odometer:128681.3,Longitude:8.666604,Latitude:50.19668,Speed:0,Heading:0,Altitude:141,Hdop:1,Vdop:1,Pdop:1,Satellites:9,Age:1}",0.03231571,128681.3,0,0,0,0,0,0,
AssetManagement,398e09e6-fb03-4246-88bd-2b7d5e23dcaa,"2012-07-06T07:30:03.1Z",Unknown,a5439110-4b75-48f1-85ae-b783154d5bf0,,"2012-07-06T07:28:37Z","{SystemType:AssetManagement,VehicleId:398e09e6-fb03-4246-88bd-2b7d5e23dcaa,DeviceTimestamp:2012-07-06T07:28:37Z,ReceivedTimestamp:2012-07-06T07:30:02.98Z,DriverId:a5439110-4b75-48f1-85ae-b783154d5bf0,Odometer:219888.6,Longitude:8.281301,Latitude:49.04264,Speed:8,Heading:213,Altitude:111,Hdop:1,Vdop:1,Pdop:1,Satellites:9,Age:0}","2012-07-06T07:28:41Z","{SystemType:AssetManagement,VehicleId:398e09e6-fb03-4246-88bd-2b7d5e23dcaa,DeviceTimestamp:2012-07-06T07:28:41Z,ReceivedTimestamp:2012-07-06T07:30:03.033Z,DriverId:a5439110-4b75-48f1-85ae-b783154d5bf0,Odometer:219888.6,Longitude:8.281263,Latitude:49.04262,Speed:0,Heading:0,Altitude:111,Hdop:1,Vdop:1,Pdop:1,Satellites:9,Age:0}",0.00402514,219888.6,0,0,0,0,0,0,