API – MyCarTracks Web Services (Deprecated)

Please note that this API is deprecated and will be terminated at date we will release soon. The documentation for new API version 2 is located here: https://www.mycartracks.com/api-docs/index.html

REST API enables you to interact with MyCarTracks web site programmatically via HTTP requests. This is useful in situations when you want to connect your third party software (CRM, ERP, …) with MyCarTracks.

There are several ways to make MyCarTracks Web Services REST requests using Java or another language.

An HTTP GET request is all you need to retrieve basic results from the MyCarTracks Web Service. GET requests are easy to debug because you can paste it in your web browser and quickly see if the query has been constructed properly.

Every method call needs apiKey=API_KEY parameter. You can generate new API key for every user in Settings. Don’t forget to press Save button when you generate new API key.

Make Web Service REST calls

This example is a request for all cars to specific user:

String request = "http://www.mycartracks.com/services/rest/v1/cars?apiKey=API_KEY";

To get JSON result add “.json” to the url:

String request = "http://www.mycartracks.com/services/rest/v1/cars.json?apiKey=API_KEY";

To explicitly define XML output ( XML is default but sometimes you need to specify it etc. in Excel import) add “.xml” to the url:

String request = "http://www.mycartracks.com/services/rest/v1/cars.xml?apiKey=API_KEY";

Now we make a simple HTTP GET request to retrieve the XML/JSON results:

HttpClient httpClient = new HttpClient();
GetMethod getMethod = new GetMethod(request);
int statusCode = httpClient.executeMethod(getMethod);

To process response from MyCarTracks Web Services and print the XML/JSON response to the console:

InputStream inputStream = getMethod.getResponseBodyAsStream();
BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(inputStream));
String line = null;
while ((line = bufferedReader.readLine()) != null) {
 System.out.println(line);
}
bufferedReader.close();

Sample XML response looks like:

<car>
 <id>137</id>
 <name>Ford Focus</name>
 <description>My personal car</description>
 <color>#ff3366</color>
 <userId>1341</userId>
</car>

Error Handling

If there is a problem serving your request, you’ll receive a response with an HTTP error code:

int statusCode = httpClient.executeMethod(method);
switch (statusCode) {
 case 400: {
   System.out.println("Bad request. The parameters passed to the service did not match as expected.");
   break;
 }
 case 403: {
   System.out.println("Forbidden. You do not have permission to access this resource.");
   break;
 }
 case 503: {
   System.out.println("Service unavailable. An internal problem.");
   break;
  }
}

Available endpoints

/user

Returns current or specific user, limited by the view of the user with API key.

Request parameters:

  • userId – The ID of the user whose information you want to retrieve. Optional parameter.
  • apiKey – User API key to access the data.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/user?apiKey=API_KEY
http://www.mycartracks.com/services/rest/v1/user?apiKey=API_KEY&userId=USER_ID

/users

Returns list of all users (drivers) connected to API key owner.

Request parameters:

  • apiKey – User API key to access the data.
  • excludeOwnerUser – if set to TRUE the list will exclude API key owner user from list. (Default is FALSE)

  • searchTerm – can be used to search for drivers by name.

 

/car

Returns a car limited by the view of the user with API key.

Request parameters:

  • carId – The ID of the car whose information you want to retrieve.
  • apiKey – User API key to access the data.

Sample request URL:
http://www.mycartracks.com/services/rest/v1/car?apiKey=API_KEY&carId=CAR_ID

/cars

Returns all cars for current or specific user, limited by the view of the user with API key.

Request parameters:

  • userId – The ID of the user whose car information you want to retrieve. Optional parameter.
  • apiKey – User API key to access the data.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/cars?apiKey=API_KEY
http://www.mycartracks.com/services/rest/v1/cars?apiKey=API_KEY&userId=USER_ID

/track

Returns a track limited by the view of the user with API key.

Request parameters:

  • trackId – The ID of the track whose information you want to retrieve.
  • humanReadable – Define output format (TRUE | FALSE) for date, time, speed, distance with or without units. Default is TRUE. Optional parameter.
  • showGeofences – if you want the result to contain geofences that start and end in returned track set this parameter to TRUE.
  • apiKey – User API key to access the data.

Response fields affected when you use humanReadable=FALSE option:

  • startTime, endTime – Date in Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • totalTime, movingTime – Time in millis.
  • maxSpeed, avgSpeed, avgMovingSpeed – Speed in km/h or mph depending on settings of user who owns API key.
  • totalDistance, minElevation, maxElevation – Distance in meters or foots depending on settings of user who owns API key.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/track?apiKey=API_KEY&trackId=TRACK_ID
http://www.mycartracks.com/services/rest/v1/track?apiKey=API_KEY&trackId=TRACK_ID&showGeofences=TRUE
http://www.mycartracks.com/services/rest/v1/track.json?apiKey=API_KEY&trackId=TRACK_ID&humanReadable=FALSE

/tracks

Returns all tracks for specific user or car, limited by the view of the user with API key.

Please note that output is limited to maximum of 500 tracks. Use page parameter to get next page of results or startTime and endTime to fine tune the result. You can also use omitPage parameter to turn off pagination and get all data.

Request parameters:

  • userId – The ID of the user whose tracks you want to retrieve. Optional parameter.
  • carId – The ID of the car whose tracks you want to retrieve. Optional parameter.
  • category – Define track category (PERSONAL | BUSINESS). Optional parameter.
  • startTime – Define track start time. Unix timestamp format (based on seconds since standard epoch of 1/1/1970). Optional parameter.
  • endTime – Define track stop time. Unix timestamp format (based on seconds since standard epoch of 1/1/1970). Optional parameter.
  • humanReadable – Define output format (TRUE | FALSE) for date, time, speed, distance with or without units. Default is TRUE. Optional parameter.
  • apiKey – User API key to access the data.
  • showGeofences – if you want the result to contain geofences that start and end in returned track set this parameter to TRUE.
  • showCustomers – if you want the result to contain geofences and customers including custom columns that start and end in returned track set this parameter to TRUE.
  • page – zero based pagination. By default the first 500 results are returned, use this parameter to access next page of results. If there is no next page empty result is returned.
  • omitPage – to omit pagination set this parameter to TRUE. You will then get result with all data. Note that on large amount the call can fail on timeout.

Response fields affected when you use humanReadable=FALSE option:

  • startTime, endTime – Date in Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • totalTime, movingTime – Time in milliseconds.
  • maxSpeed, avgSpeed, avgMovingSpeed – Speed in km/h or mph depending on settings of the user who owns API key.
  • totalDistance, minElevation, maxElevation – Distance in meters or foot depending on settings of the user who owns API key.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&page=2
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&omitPage=true
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&showGeofences=TRUE
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&userId=USER_ID&carId=CAR_ID
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&userId=USER_ID&category=BUSINESS
http://www.mycartracks.com/services/rest/v1/tracks?apiKey=API_KEY&userId=USER_ID&category=PERSONAL&startTime=1322784000&endTime=1322784000

/trackpoints

Returns all trackpoints for specific track, limited by the view of the user with API key.

Please note that output is by default limited to maximum of 500 trackpoints. Use ‘page’ parameter to get next page of results or startTime and endTime to fine tune the result. You can also use omitPage parameter to turn off pagination and get all data.

Request parameters:

  • trackId – The ID of the track whose trackpoints (positions) you want to retrieve.
  • humanReadable – Define output format (TRUE | FALSE) for date, time, speed, distance with or without units. Default is TRUE. Optional parameter.
  • apiKey – User API key to access the data.
  • page – zero based paging (first page = 0, second page = 1, …)
  • pageSize – the maximum size of data returned per page (default = 500)
  • omitPage – to omit pagination set this parameter to TRUE. You will then get a result with all data. Note that on a large amount the call can fail on timeout.

Response fields affected when you use humanReadable=FALSE option:

  • time – Date in Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • speed – Speed in km/h or mph depending on settings of user who owns API key.
  • altitude, accuracy – Distance in meters or foots depending on settings of user who owns API key.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/trackpoints?apiKey=API_KEY&trackId=TRACK_ID
http://www.mycartracks.com/services/rest/v1/trackpoints.json?apiKey=API_KEY&trackId=TRACK_ID&humanReadable=FALSE

/lastPosition

Returns last car position defined by trackpoint, limited by the view of the user with API key.

Request parameters:

  • carId – The ID of the car whose last position, speed, altitude and etc. you want to retrieve.
  • humanReadable – Define output format (TRUE or FALSE) for date, time, speed, distance with or without units. Default is TRUE. Optional parameter.
  • apiKey – User API key to access the data.

  • inclPositionRequest – (TRUE or FALSE) – by defaultIf this endpoint returns last position from last recorded track. If this parameter is set to TRUE it will return also last position from actual position request made from web application.

Response fields affected when you use humanReadable=FALSE option:

  • time – Date in Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • speed – Speed in km/h or mph depending on settings of user who owns API key.
  • altitude, accuracy – Distance in meters or foots depending on settings of user who owns API key.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/lastPosition?apiKey=API_KEY&carId=CAR_ID

/actualPosition

Returns last vehicle position of whole fleet, limited by the view of the user with API key.

Request parameters:

  • apiKey – User API key to access the data.
  • humanReadable – Define output format (TRUE | FALSE) for date, time, speed, distance with or without units. Default value is TRUE. Optional parameter.

Response fields affected when you use humanReadable=FALSE option:

  • time – Date in Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • speed – Speed in km/h or mph depending on settings of user who owns API key.
  • altitude, accuracy – Distance in meters or feets depending on settings of user who owns API key.

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/actualPosition?apiKey=API_KEY

/positionRequest

Endpoint to create request for actual position of driver or vehicle. Note, that it will not return the current position. Use /actualPosition endpoint to get result of this call. Obtaining of position is asynchronous therefore you need to wait or periodically check for short time actual position endpoint.

Request parameters:

  • apiKey – User API key to access the data.
  • userId – user (driver) ID to create request for
  • carId –  vehicle ID to create request for.

/timeReport/vehicles

Returns Geofence Analytics data for Vehicles (available in we abb under GEOFENCES > Analytics / Vehicles).

Request parameters:

  • apiKey – User API key to access the data.

all these parameters are optional:

  • type – available values:
    • geofence (default if not provided)
    • customer
    • vehicle
    • vehicleAtCustomer
    • vehicleGeofenceDetailed
    • vehicleAtCustomerDetailed
    • vehicleDetailed
    • geofenceTimeTracker
    • customerTimeTracker
  • geofenceId – filter certain geofence, put ID number that you can find in the results. You can enter multiple IDs with delimiter (‘,’). (available only with some types, see above)
  • vehicleId – filter vehicle, put ID number that you can find in the results. You can enter multiple IDs with delimiter (‘,’). (available only with some types, see above)
  • dateFrom – filter from date. Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • dateTo – filter since date. Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • category – filters tracks that are made as business or private, available values: PERSONAL, BUSINESS.
  • idlesShow – available values: “none”, “seconds”, “all” (or empty, default). (available only with some types, see above)
  • idleSecondFrom – available only with idleShow=seconds , filters out idles that are shorter than this value. (available only with some types, see above)
  • idleSecondTo – available only with idleShow=seconds” , filters out idles that are longer than this value. (available only with some types, see above)
  • hideDidntStopInside – true or false. (available only with some types, see above)
  • searchString – search in the name of filtered element.
  • page – zero based pagination. By default the first 500 results are returned, use this parameter to access next page of results. If there is no next page empty result is returned.
  • omitPage – to omit pagination set this parameter to TRUE. You will then get result of all data.
  • pageSize – you can specify the page size, default (when not used) is 500.
  • hideMissed – available only with type customerTimeTracker and geofenceTimeTracker. Set if entries with zero time (missed) should be viewed.

Some parameters are available only with specific type parameter option:

  • geofenceId – is available only with type = geofence, vehicleGeofenceDetailed, geofenceTimeTracker,customerTimeTracker
  • vehicleId – is available only with type = vehicleGeofenceDetailed, vehicleAtCustomerDetailed,vehicleDetailed, geofenceTimeTracker, customerTimeTracker
  • idlesShow, idleSecondFrom, idleSecondTo – are available only with type: vehicleAtCustomerDetailed,vehicleDetailed
  • hideDidntStopInside – is available only with type: vehicleAtCustomerDetailed, vehicleDetailed

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/timeReport/vehicles?apiKey=API_KEY
http://www.mycartracks.com/services/rest/v1/timeReport/vehicles?apiKey=API_KEY&type=vehicleAtCustomer
http://www.mycartracks.com/services/rest/v1/timeReport/vehicles?apiKey=API_KEY&type=vehicleAtCustomerDetailed&idlesShow=seconds&idleSecondFrom=120
http://www.mycartracks.com/services/rest/v1/timeReport/vehicles?apiKey=API_KEY&type=geofence&geofenceId=12,3324,3456

/timeReport/drivers

Returns Geofence Analytics data for Drivers (available in we abb under GEOFENCES > Analytics / Drivers).

Request parameters:

  • apiKey – User API key to access the data.

all these parameters are optional:

  • type – available values:
    • geofence (default if not provided)
    • customer
    • driver
    • driverAtCustomer
    • driverGeofenceDetailed
    • driverAtCustomerDetailed
    • driverDetailed
    • geofenceTimeTracker
    • customerTimeTracker
  • geofenceId – filter certain geofence, put ID number that you can find in the results. You can enter multiple IDs with delimiter (‘,’). (available only with some types, see above)
  • userId – filter driver by his ID number that you can find in the results. You can enter multiple IDs with delimiter (‘,’). (available only with some types, see above)
  • dateFrom – filter from date. Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • dateTo – filter since date. Unix timestamp format (based on seconds since standard epoch of 1/1/1970).
  • category – filters tracks that are made as business or private, available values: PERSONAL, BUSINESS.
  • idlesShow – available values: “none”, “seconds”, “all” (or empty, default). (available only with some types, see above)
  • idleSecondFrom – available only with idleShow=seconds , filters out idles that are shorter than this value. (available only with some types, see above)
  • idleSecondTo – available only with idleShow=seconds” , filters out idles that are longer than this value. (available only with some types, see above)
  • hideDidntStopInside – true or false. (available only with some types, see above)
  • searchString – search in the name of filtered element.
  • page – zero based pagination. By default the first 500 results are returned, use this parameter to access next page of results. If there is no next page empty result is returned.
  • omitPage – to omit pagination set this parameter to TRUE. You will then get result of all data.
  • pageSize – you can specify the page size, default (when not used) is 500.
  • hideMissed – available only with type customerTimeTracker and geofenceTimeTracker. Set if entries with zero time (missed) should be viewed.

Some parameters are available only with specific type parameter option:

  • geofenceId – is available only with type = geofence, driverGeofenceDetailed, geofenceTimeTracker,customerTimeTracker
  • userId – is available only with type = driverGeofenceDetailed, driverAtCustomerDetailed,driverDetailed, geofenceTimeTracker, customerTimeTracker
  • idlesShow, idleSecondFrom, idleSecondTo – are available only with type: driverAtCustomerDetailed,driverDetailed
  • hideDidntStopInside – is available only with type = driverAtCustomerDetailed, driverDetailed

Sample request URLs:
http://www.mycartracks.com/services/rest/v1/timeReport/drivers?apiKey=API_KEY
http://www.mycartracks.com/services/rest/v1/timeReport/drivers?apiKey=API_KEY&type=driverAtCustomer
http://www.mycartracks.com/services/rest/v1/timeReport/drivers?apiKey=API_KEY&type=driverAtCustomerDetailed&idlesShow=seconds&idleSecondFrom=120
http://www.mycartracks.com/services/rest/v1/timeReport/drivers?apiKey=API_KEY&type=driverGeofenceDetailed&userId=85679,98567

Related Articles