Call at Mappls
Product release

Boost your businesses with Mappls’ industry-leading optimisation APIs and SDKs to bring the best and most efficient ways to deliver goods, save time and increase profits.

or

Intouch Android SDK

Easy integration on your android displaying raster map tiles to make location aware applications for a much larger reach

Mappls InTouch Android SDK

Introduction

Get Real-Time Location Tracking for your apps with Mappls InTouch SDK. Track a user's live location with our simplified InTouch SDK integration (for Android), highly customizable to your specific needs.

The InTouch SDK comes with a variety of events that enable better control and power over your tracking needs. Get readymade events to create Geo-Fences, Event Alerts, and Trails of telematics/ phone devices. Also get location benefits built for various applications including logistics, delivery tracking, employee tracking, and live location sharing.

To get started, explore the InTouch Demo App.

Already have an application? Give it a boost with the powerful features of InTouch. Learn how to Integrate the InTouch SDK.

Setup

We use your Client ID to identify your account details and assign all your user's devices under a single account.

To get your Outh2 Rest API Client ID and Client Secret please login to Mappls API Dashboard

Please contact apisupport@mappls.com to get InTouch SDK access to your Client ID

After getting the access, you can start with the InTouchDemo app, or Integrate the InTouch SDK in your app.

InTouchDemo app

This guide allows you to add live location tracking to an Android app. Android Studio is the recommended development environment for building an app with the Mappls InTouch SDK for Android.

Step 1. Download the InTouchDemo App.

Click here to download the InTouchDemo App Project. Open this project in Android Studio

Step 2. Set your Publishable key

  1. Add the publishable key to SetUpKeyFragment Fragment file.
  2. Run project on your device using simulator instance.
  3. Go through run-time permission flow (applicable for Android M and later).

Step 3. Check your location on the InTouch dashboard

Integrate the InTouch SDK

Step 1: Setup a project

  1. Start Android Studio.
  2. Create a new project as follows:
    • If you see the Welcome to Android Studio dialog, choose Start a new Android Studio project, available under 'Quick Start' on the right of the dialog.
    • Otherwise, click File in the Android Studio menu bar, click New-> New Project.
    • Select the form factors you need for your app. If you're not sure what you need, just select Phone and Tablet.
    • Select Add No Activity and click Next.
  3. Enter your app name, package name, project location, language and minimum API version as prompted. Click Next.
  4. Create a Basic Activity in the 'Add an activity to Mobile' dialog. Click Next.
  5. Enter the activity name, layout name and title as prompted. Click Finish.

Android Studio starts Gradle and builds your project. This may take a few seconds. For more information about creating a project in Android Studio, see the Android Studio documentation.

The next few sections contain the code samples that you need to add to your activity's java file as well as its xml layout file for creating an app with Mappls InTouch SDK for live tracking.

Step 2. Add InTouch SDK

Add following lines to your applications build.gradle:

// Import the SDK within your repositories block
allprojects {  
    repositories {  
        google()  
        jcenter()  
       maven {  
            url 'https://maven.mapmyindia.com/repository/mapmyindia/'  
  }  
    }  
}
//Add to build.gradle
android{
	-----
	compileOptions {
       	sourceCompatibility 1.8
        	targetCompatibility 1.8
   	}
 	-----
}
dependencies {
    implementation 'com.mapmyindia.sdk:intouch-sdk:0.3.0'
    ...
}
 Required Minimum sdk version
minSdkVersion 16

Step 3: Initialize InTouch SDK

Initialize the SDK with your Client ID and Client Secret.

 // Add the following to your AndroidManifest.xml file.
<uses-permission android:name="android.permission.INTERNET" />
// IAuthListener - returns authorization results in the forms of callbacks.
InTouch.initialize(<device name>, <your client id>, <your client secret>, new IAuthListener() {
	@Override
	public void onSuccess() {
			  //write your code here                      
	}
	@Override
	public void onError(String reason, String identifier, String description) {
	         // reason gives the error type. 
            // errorIdentifier gives information about error code. 
          // errorDescription gives a message for a particular error.
} 
});

Step 4: Start Tracking

Track your app user's phone live location by using the below method.

InTouch.startTracking();

Dashboard

Check your device live location in the Intouch Web dashboard. Login to Intouch Dashboard using your Mappls Username and password.

Utility Methods

Identify devices

All devices tracked on InTouch are uniquely identified using UUID. You can get this identifier programmatically in your app by calling getDeviceID() after initialization. Another approach is to tag the device with a name that will make it easy to distinguish them on InTouch Dashboard.

Intouch sdkInstance = Intouch.initialize(deviceName, clientId, clientSecret, iAuthListener);

To Update Device Name

Intouch.updateDeviceName(<device name>);

Check whether location tracking is started or not. This method returns boolean value.

Intouch.isRunning();

Stop Location Tracking

You can stop tracking the user location using below method.

 Intouch.stopTracking();

Customize foreground service notification

MapmyIndiaIntouch tracking runs as a separate foreground service, so when tracking is started, users will see a persistent notification. By default, it displays your app icon with text {app name} is running but you can customize it anytime after initialization by calling:

Intouch.getInstance().addNotificationIconsAndTitle(
R.drawable.ic_small,
R.drawable.ic_large,
notificationTitleText,
notificationBodyText
 );

Change the data Polling configuration

Custom Configuration

User can customize data polling configuration using below mentioned Config class.

(1) With predefine priorities:-

new Config.Builder(getContext())  
.setPriority(InTouch.BEACON_PRIORITY_FAST)  
.build();

(2) With custom parameters:-

new CustomConfig.Builder(context)
.setBeaconStandByTimeInMins(15)
.setDetectDrive(true)
.setTimeWhileMovingInSec(15)
.build();

Note:- it should be set before startTracking() method.

There are three predefined properties are there. InTouch.BEACON_PRIORITY_FAST - Recommended for short haul delivery tracking. InTouch.BEACON_PRIORITY_SLOW - Recommended for Long haul delivery tracking. InTouch.BEACON_PRIORITY_OPTIMAL - Recommended for all the other tracking. Data polling frequency based on the user movement.

By default, InTouch SDK uses the optimal property.

Intouch Telematics API's

Device Details

Get live device details by single or multiple IDs.

a) Get the list of all devices live data in your account.

InTouch.getDevices(<includeInActive>,<ignoreBeacon>,<lastUpdateTime>, new IDeviceListener() {
       @Override
       public void onSuccess(DevicesResponse devicesResponse) {
	           // write your code here.
	  }
	  @Override
	  public void onError(String reason, String identifier, String description) {
	            // reason gives the error type. 
               // errorIdentifier gives information about error code. 
              // errorDescription gives a message for a particular error.
	            }
});

b) Get the list of selected devices live data.

 InTouch.getDevices(<Long[] List of deviceIds>,<includeInActive>,<ignoreBeacon>,<lastUpdateTime>,new IDeviceListener() {
 @Override
 public void onSuccess(DevicesResponse devicesResponse) {
   // write your code here.
    }
   @Override
    public void onError(String reason, String errorIdentifier, String errorDescription) {
		// reason gives the error type. 
   // errorIdentifier gives information about error code. 
  // errorDescription gives a message for a particular error.
 }
});

c) Get a single device live data

 InTouch.getDevice(<deviceId>,<lastUpdateTime>, new IDeviceListener() {  
   @Override  
    public void onSuccess(DevicesResponse devicesResponse) {  
       // write your code here.
    }    @Override  
    public void onError(String reason, String errorIdentifier, String errorDescription) {  
		       // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // errorDescription gives a message for a particular error.
   }  
});
Request Parameters
  1. deviceId(Long) - This is the device ID
  2. includeInActive (Boolean) -If "true" then API response will include inactive devices along with active devices. If "false" then API will return only active devices.
  3. ignoreBeacon ((Boolean) - If set to "true" then API will return all devices except those with device type as a beacon(mobile).
  4. lastUpdateTime (Long) - Give EPOCH timestamp to fetch only those live locations of devices which have come after the given timestamp. If "lastUpdateTime" is given then by default only active devices will be fetched irrespective of the status of "includeInActive" attribute else set the value as 0.
Response Code (as HTTP response code)

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, It comes during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found

Response Parameter

DevicesResponse class object returns the API response as JSON object.

DeviceResponse result parameters:
  1. id (Long) - Id of the device.
  2. active (string) - Device active status
  3. status (string) - Device movement status
  4. vehicleBattery (Double) - Device battery status
  5. location (Location) - Device live location object like latitude, longitude etc.
  6. deviceDetails(DeviceDetails) - Device info object like name etc.
  7. alerts (Alerts) - Alert object
  8. canInfo (CanInfo) - Device CanInfo object.
  9. deviceFaults (ArrayList<DeviceFault>) - List of various fault.
  10. currentGeofence (ArrayList<Long>) - list of current geofences id.
  11. todaysDrive (TodaysDrive) - TodaysDrive object.

Location parameters:

  1. gpsTime (Long)
  2. gprsTime (Long)
  3. latitude (Double)
  4. longitude (Double)
  5. altitude (Double)
  6. heading (Double)
  7. speedKph (Double)
  8. address (String)
  9. odometer (Double)

DeviceDetails parameters:

  1. deviceId (Long) - Id of device.
  2. registrationNumber (String) Device registration number.
  3. deviceType (String) - Type of device like: car, truck, bus, bike, tractor, JCB, excavator etc.

Alerts parameters:

  1. deviceId (Long) - Id of device.
  2. timestamp (Long) - EPOCH time at which alarm was generated
  3. latitude (Double)- Location latitude of alarm.
  4. longitude (Double) - Location longitude of alarm.
  5. address (String) - Location address at which the alarm got generated
  6. alarmType (Integer) - Type of alarm to create. Following are the alarm types & their corresponding IDs.
    IGNITION: 21, OVERSPEED: 22, UNPLUGGED: 23, PANIC: 24, GEOFENCE: 26, STOPPAGE: 27, IDLE: 28, TOWING: 29, GPRS CONNECTIVITY: 126, VEHICLE BATTERY: 129, MILEAGE: 133, GPS CONNECTIVITY: 146, DISTANCE COVERED: 151, INTERNAL BATTERY VOLTAGE:161
  7. limit (Integer)- Alarm limit as set in the config. For example, if an Overspeed alarm set on the limit of 44 km/hr in the alarm config setting, then this attribute will return 44 km/hr
  8. duration (Long) - Alarm duration limit as set in the alarm config section. For example, if the duration of Overspeed alarm is set as 20 secs, then the alarm will generate when the vehicle over speeds for a duration of 20 secs
  9. actualLimit (Integer) - The actual data received from the device at that particular moment when the alarm got generated. For example, when the over-speed alert generated the vehicle actual speed was 56km/hr.
  10. actualDuration (Integer) - Actual duration for which the device breached the alarm config limit
  11. severity (Integer) - 0:Low Severity. 1:High Severity
  12. data (Integer) - Describes the state of the alarm. IGNITION(type = 21), 0: OFF & 1: ON. AC(type=25), 0: OFF, 1: ON. GEOFENCE(type=26), 1: Entry & Exit Geofence 2: Entry Geofence, 3: Leaving Geofence & 4: Long Stay In Geofence
  13. geofenceId (Long) - Unique ID of the geofence for which the alarm got generated.

CanInfo parameters:

  1. calcEngineVal (Integer) - Calculated Engine value.
  2. greenDriveType (String) - HA(Harsh acceleration), HB(Harsh Braking), HC(Harsh Cornering).
  3. canTimestamp (Long) - Exact EPOCH time at which the CAN data got generated by the device.
  4. coolantTemp (Integer) - Coolant temperature.
  5. engineRPM (Integer) - Rpm value of engine.
  6. accelPedal (Double) - This is accelerator pedal value in percentage.
  7. pedoMeter (Integer) - Pedometer value in steps.
  8. parkBrake (Double) - This is the parking brake. 0 means parking brake is disengaged & 1 means parking brake is engaged.
  9. brakePedal (Double) - 1 means brake pedal is engaged & 0 means brake pedal is disengaged.
  10. fuelLevel (Integer) - The level of the fuel in litres.
  11. driverDoor (Double) - 1 means door is open & 0 means door is closed.
  12. passDoor (Double) - 1 means door is open & 0 means door is closed.
  13. headLights (Double) - 1 means ON & 0 means OFF.
  14. blinker (Double) - 1 means ON & 0 means OFF.
  15. ac (Integer) - 1 means AC is ON & 0 means AC is OFF.
  16. fuelConsAVG (Integer) - Fuel constant average.
  17. intakeAirTemp (Double) - Intake air temperature of the engine.
  18. intakeabsolutePress (Integer) - Intake absolute pressure of the engine. It is defined in Pa(Pascal)

DeviceFault parameters:

  1. code (String) - Fault code.
  2. timestamp (Long) - Duration as EPOCH Time.
  3. status (Integer) - Describes the status of the fault which was detected. 0: OPEN & 1: Close.
  4. closedOn (Long)- The EPOCH time at which fault code closed. This will come for the closed case.

TodaysDrive parameters:

  1. todayKms (Double) - Distance in Km(s).
  2. todayMovementTime (Long) - Movement time in sec(s).
  3. todayIdleTime (Long) - Idle time in sec(s).
  4. todayDriveCount (Long) - Drive count for today.

Event's Data

Get the Trails (Travelled path) of a device in your account using below methods.

InTouch.getLocationsEvents(<deviceId>,<startTime>,<endTime>,<skipPeriod> new ILocationEventsListener() {
	 @Override
	 public void onSuccess(LocationEventsResponse locationEventsResponse) {
          // Write your code here.
     }
      @Override
      public void onError(String s, String s1, String s2) {
            // reason gives the error type. 
           // errorIdentifier gives information about error code. 
           // error description gives a message for a particular error.
            }
});
Request Parameters
  1. deviceId (Long) Id of the device for which the location data need to be fetched.
  2. startTime (Long) Start Epoch timestamp from which the events need to be fetched.
  3. endTime (Long) End Epoch timestamp till which the events need to be fetched.
  4. skipPeriod(int) Defined in minutes. For example, if 2 is passed then returned data packet will have a minimum difference of 2 mins else 0.
Response Code

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found
Response Parameter

LocationEventResponse class object returns the API response as JSON object.

LocationEventResponse result parameters:

  1. deviceId (Long) - Device id of selected device.
  2. drivingBehaviourCount (DrivingBehaviourCount) - Driving behavior count in the selected device.
  3. summary (Summary) - Brief summary of all locations.
  4. positionList (List<PositionList>) - List of location positions.

Summary parameters:

  1. distance (Double) - Total drive distance in KM(s).
  2. duration (Long) - Total drive duration in seconds.
  3. avgSpeed (Double) - Average speed in km/hr.
  4. startAddress (String) - Start address of the location.
  5. endAddress (String) - End address of the location.
  6. startTimestamp (Long) - Start Epoch time of the event. i,e) the time at which the data first came from the device for the selected day
  7. endTimestamp (Long) - End Epoch time of the event. i,e) the time at which the last data came from the device for the selected day.

DrivingBehaviourCount parameters:

  1. haCount (Integer) - Harsh acceleration count.
  2. hbCount (Integer) - Harsh braking count.
  3. hcCount (Integer) - Harsh cornering count.

PositionList parameters:

  1. address (String) - Address of particular location.
  2. timestamp (Long) - Epoch Time at a particular location.
  3. longitude (Double) - Location longitude.
  4. latitude (Double) - Location latitude.
  5. heading (Double) - Device heading direction in degrees from North.
  6. speed (Double) - Device speed at this particular location.
  7. powerSupplyVoltage (Double) - Battery voltage value in millivolts.
  8. ignition (Boolean) - Whether vehicle ignition is On or Off. 0 means ignition is OFF and 1 means ignition is ON.
  9. gpsFix (Boolean) - GPS fixes or not for the device. true means GPS is fixed and false means GPS is not fixed.
  10. validGPS (Boolean) - Checks whether GPS is valid or not.
  11. accOff (Boolean) - Checks for whether adaptive cruise control is enabled or not.
  12. movementStatus (String) - Checks the movement status of the device. 1:Moving, 2:Idle, 3:Stopped, 4:Towing, 5:No Data 6:Power Off, 7:No Gps, 8:On Trip, 9:Free Vehicle
  13. mobileInfos (MobileInfo) - MobileInfo object

MobileInfo parameters:

  1. locationSource (Integer) - Returns location source i.e 1 - GPS connected, 2 - GPRS connected.
  2. mockLocation (Boolean) - If true means mock location is enabled else false means real GPS location being sent by the user.
  3. isAirplanemode (Boolean) - Checks whether mobile's aeroplane mode is ON or OFF.
  4. callStatus (Integer) - Current call status like 0:CALL_STATE_IDLE, 1:CALL_STATE_RINGING, 2:CALL_STATE_ONCALL
  5. deviceStatus (Integer) - Status of the device in the current location. 0:IN_VEHICLE, 1:ON_BICYCLE, 2:ON_FOOT, 3:STILL, 4:UNKNOWN, 5:TILTING, 6:WALKING, 7:RUNNING.
  6. phoneEvent (Integer) - Checks the location permission that the user enables/disables in the mobile phone. For eg:- 5 for location permission denied. 6 for location provider off etc.

Drive's Data

Get the drive details of a vehicle/user in an InTouch account using the below method. A drive is a list of reported geo-positions with start and end location of a vehicle according to pre-defined conditions. Time duration, distance covered during the drive, HA, HB, HC events are also returned along with the drive details.

InTouch.getDrive(deviceId, startTime, endTime, new IntouchDrivesCallBack() {
@Override
public void onSuccess(IntouchDriveResponse intouchDriveResponse) {
}
@Override
public void onError(String reason, String errorIdentifier, String errorDescription) {  
}
});
Request Parameters

1.deviceId(Long)- Id of the device for which the drives need to be fetched. 2. startTime (Long)- The start Epoch timestamp from which the drives need to be fetched. 3. endTime (Long)- The end Epoch timestamp till which the drives need to be fetched.

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found
Response Parameter

DriveResponse Class object returns the API response as JSON object.

DriveResponse result parameters:

  1. deviceId (Long) - Device id of selected device.
  2. drivingBehaviourCount (DrivingBehaviourCount) - Driving behavior count in the selected drive.
  3. movement(Movement) - Movement info object.
  4. location (Location) - Location info object.

Movement parameters:

  1. duration (Long) - Drive duration in seconds.
  2. distance (Long) - The driving distance in KMs.
  3. idleTime (Long) -Idle time in seconds.
  4. movementTime (Long) - Movement time in seconds.
  5. stoppageTime (Long) - Stoppage time in seconds.

DrivingBehaviourCount parameters:

  1. haCount (Integer) - Harsh acceleration count.
  2. hbCount (Integer) - Harsh braking count.
  3. hcCount (Integer) - Harsh cornering count.

PositionList parameters:

  1. startAddress(String) - Start address of particular drive.
  2. startTimestamp(Long) - Start Epoch time of particular drive.
  3. endAddress(String) - End address of particular drive.
  4. endTimestamp(Long) - Start Epoch time of particular drive.
  5. avgSpeed(Double) - Speed in km/hr.

GeoFences

A geofence is a user-defined bounded area to trigger Entry and Exit alert of the user/vehicle. Custom areas or places can be created as a Geofence under your account, For example, it could be a hotel, Restaurant, Office, work area, retail store and so on.

Mappls InTouch SDK supports Point, Circle and Polygon (Custom Region/Area) geofences. You can Create, Update or Delete geofences using below methods.

4.1 Create Geofence

The create geofence method helps you to create a geofence under your account. Three types of geofence can be created: Point, Circle, Polygon.

4.1.1 Point Geofence

Input the Lat, long and the name of the geofence to create the point geofence. A point geofence has a fixed radius of 100 meters, so the user need not put the radius of the geofence. To customize the radius of geofence refer circle geofence method.

// Point type geofence
// ICreateGeoFenceListener - returns success if geofence created else error as callback methods.
InTouch.createGeoFence("<geofence name>", new GeoFencePoint(<Latitude>, <Longitude>), new ICreateGeoFenceListener() {  
	 @Override public void onSuccess() { 
	 // write your code here.
	 }
	 @Override public void onError(String reason, String errorIdentifier,  String errorDescription) {  
			   // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
     } 
});

4.1.2 Circle Geofence

Create a circle geofence with a radius of your choice. Input Lat, long, Radius and name of the geofence to create the circle geofence.

// Circle type geofence, the radius will be in meters.
// ICreateGeoFenceListener - returns success if geofence created else error as callback methods.
InTouch.createGeoFence("<geofence name>", new GeoFencePoint(<Latitude>, <Longitude>), <range>, new ICreateGeoFenceListener()  {
	 @Override public void onSuccess(CreateGeoFenceResponse response) { 
		 // writeyour code here
	 }
	 @Override public void onError(String reason, String errorIdentifier, String errorDescription) {  
           	 // reason gives the error type. 
             // errorIdentifier gives information about error code. 
              // error description gives a message for a 
	 }
});

4.1.3 Polygon Geofence

To draw a polygon geofence we need at least three points. Multiple points can be added to create the custom shape Geofence. Input a list of geofence points (Lat,long) in the comma-separated format.

  // Polygon Geofence
 // ICreateGeoFenceListener - returns success if geofence created else error as callback methods.
InTouch.createGeoFence("<geofence name>", <list of GeoFencePoint>, new ICreateGeoFenceListener() {  
	 @Override public void onSuccess(CreateGeoFenceResponse response) { 
		 // writeyour code here 
	 }  
	 @Override public void onError(String reason, String identifier, String description) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
	 }
});
Request Parameters

1.geoFenceName(String) name of the geofence. 2. geoFencePoint(GeoFencePoint) Geofence point(s). List of "GeoFencePoint" for polygon else single object required.

Response Code

Success:

  1. 201: To denote successful record is being created.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found
Response Parameter

CreateGeoFenceResponse class object returns the API response as JSON object.

CreateGeoFenceResponse result parameters:

id (Long) Id of the newly created geofence.

4.2 Get Geofence(s)

InTouch Get Geofences methods can be used to request the list of geofence areas using the unique geofence IDs which is being assigned by InTouch.

4.2.1 Get All Geofence(s)

Get all the geofences created under your account using the below method. It returns the name and unique Id of the geofence.

// Get all geofences
// IGetGeoFenceListener- returns all geoFences in response if success else error as callback methods.
InTouch.getGeoFences(new IGetGeoFenceListener() {  
   @Override  
    public void onSuccess(InTouchGeoFenceResponse response) {     	
   	  // write your code here.     
    }  
    @Override  
   public void onError(String reason, String errorIdentifier, String   errorDescription) {  
			   // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
    }  
});

4.2.2 Get All Geofence(s) with geometry

Get the geofence response with shape by setting ignore geometry value as false. for example, the type will be either a point, polygon or circle.

// ignoreGeometry is a boolean value. If the user doesn't need geometry with geofence pass true else false. 
// IGetGeoFenceListener- returns all geoFences with geometry in response if success else error as callback methods.
InTouch.getGeoFences(<ignoreGeometry>, new IGetGeoFenceListener() {  
    @Override  
    public void onSuccess(InTouchGeoFenceResponse response){
	    // write your code here.     		       
    }  
    @Override  
    public void onError(String reason, String identifier, String   description) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
    } 
});

4.2.3 Get single Geofence

Input Geofence Id to get a single geofence detail in the get method.

// Get single geofence
// IGetGeoFenceListener- returns single geoFence in response if success else error as callback methods.
InTouch.getGeoFences(<id of geofence>, new IGetGeoFenceListener() {  
    @Override  
    public void onSuccess(InTouchGeoFenceResponse response){ 
	    // write your code here.    		       
    }  
   @Override  
public void onError(String reason, String identifier, String   description) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
             // error description gives a message for a 
   }  
});

4.2.4 Get single Geofence with geometry Value.

Get a geofence with the geometry value like circle, polygon or point. Set ignoreGeometry value as false.

// Get single geofence with geometry value
// IGetGeoFenceListener- returns single geoFence with geometry in response if success else error as callback methods.
InTouch.getGeoFences(<id of geofence>,<ignoreGeometry>, new IGetGeoFenceListener() {  
   @Override  
  public void onSuccess(InTouchGeoFenceResponse response) {    
    // write your code here.
 }  
 @Override  
   public void onError(String reason, String identifier, String   description) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
   }
});

4.2.5 Get multiple Geofence with geometry Value.

Get multiple geofences for an array of geofence Ids with ignoreGeometry parameter value set as false.

// Get multiple geofences with geometry value
// IGetGeoFenceListener- returns multiple geoFences in response if success else error as callback methods.
InTouch.getGeoFences(<Long array of geofence ids>, <id of geofence>,<ignoreGeometry>, new IGetGeoFenceListener() {  
    @Override  
    public void onSuccess(InTouchGeoFenceResponse response){ 
	    // write yor code here.    		       
    }  
    @Override  
    public void onError(String reason, String identifier, String   description) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
    }  
});
Request Parameters

1.id(Long) Geofence id. Use this if you want to get details of specific multiple geofence IDs. 2. ignoreGeometry(boolean) Non-mandatory field, boolean value to fetch geometry details.

Response Code

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer's key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer's key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found
Response Parameter

CreateGeoFenceResponse Class object returns the API response as JSON object.

InTouchGeoFenceResponse result parameters:

- List<GeoFenceResult> List of GeoFenceResult.

GeoFenceResult Parameters:

  1. id(Long)- Geofence ID
  2. name(String)- Name of the geofence
  3. geometry(Geometry)- Geofence Geometry object.
  4. type(String)- Depending on the type of geofence this value can be Circle(buffer > 50 meters), Polygon or Point(buffer = 50 mtrs)
  5. buffer(Double)- Radius(in meters) of a circular geofence
  6. creationTime(long)- Epoch Timestamp at which the geofence was created.
  7. updationTime(Long)- Epoch Timestamp at which the geofence was updated.

Geometry Parameters:

  1. type(String)-This defines the type of geofence, it can be point or polygon.
  2. coordinates(Object)- Geofence geometry coordinates.
  3. latLng(GeoFencePoint)- GeoFencePoint object. Use this in case of geofence type "Point or Circle".
  4. points(List<List<GeoFencePoint>>)- List of GeoFencePoint list. Use this in case of geofence type "Polygon".

4.3 Update Geofence(s)

Use Geofence ID to update Geofence name, latitude, longitude and radius in below method

4.3.1 Update point Geofence

Update geofence values like geofence name and lat, long using below method

// update single geofence 
// IUpdateGeoFenceListener - returns success if gefence updated successfully, else error as callback methods.
InTouch.updateGeoFence(<geofence id>, <name of geofence>, <GeoFencePoint>, new IUpdateGeoFenceListener() {  
    @Override  
  public void onSuccess() {  
	  // write your code here.
    }  
    @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
    } 
});

4.3.2 Update circle Geofence

Update geofence name, latitude, longitude and Radius for a circle geofence using below method.

// update single geofence with buffer value. Buffer is like radius in meters.
InTouch.updateGeoFence(<geofence id>, <name of geofence>, <GeoFencePoint>, <buffer>, new IUpdateGeoFenceListener() {  
    @Override  
  public void onSuccess() {  
	  // write your code here. 
    }  
  
    @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a 
   }  
});
});

4.3.3 Update Polygon Geofence

Update the geofence name, and the latitude, longitude of the polygon geofence using below method.

// Update polygon geofence.
InTouch.updateGeoFence(<geofence id>, <name of geofence>, <list of GeoFencePoint>, new IUpdateGeoFenceListener() {  
   @Override  
  public void onSuccess() {  
	  // write your code here.
  }    
  @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
             // errorIdentifier gives information about error code. 
              // error description gives a message for a 
    }  
});
Request Parameters
  1. geoFenceId(Long) -Id of the existing geofence.
  2. geoFenceName(String) - Name of the geofence. If you need to update the existing one then use this else pass null.
  3. geoFencePoint(GeoFencePoint) -List of "GeoFencePoint" for polygon geofence else single object required.
Response Code

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found
Response Parameter

UpdateGeoFenceResponse Class object returns the API response as JSON object.

UpdateGeoFenceResponse parameters:

message<String> Describes the type of error based on the type of response code.

4.4 Delete Geofence

Delete Geofences by mentioning the geofence IDs in the following methods

4.4.1 Delete single Geofence

Use the below method to delete a particular geofence by mentioning geofence ID.

// Delete single geofence
 // IResultListener- returns success if gefence deleted successfully, else error as callback methods.
InTouch.deleteGeoFence(<geofence id>, new IResultListener() {  
	 @Override public void onSuccess() { 
		 // write your code here. 
	 }  
	 @Override public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
             // error description gives a message for a 
	 }
});

4.4.2 Delete multiple Geofence

Use the below method to delete a list of geofence Ids at once.

// Delete multiple geofences
InTouch.deleteGeoFence(, new IResultListener() {  
	 @Override public void onSuccess() {  
		 // write your code here.
	 }  
	 @Override public void onError(String reason, String errorIdentifier, String errorDescription) {  
			   // reason gives the error type. 
             // errorIdentifier gives information about error code. 
              // error description gives a message for a 
	 }
});
Request Parameters
  1. geoFenceId(Long) Id or array of Ids of existing geofence(s).
Response Code

Success:

  1. 200: To denote a successful API call.

Client-side issues:

  1. 400: Bad Request, User made an error while creating a valid request.
  2. 401: Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403: Forbidden, Developer.s key has hit its daily/hourly limit.

Server-sde issues:

  1. 500: Internal Server Error, the request caused an error in our systems.
  2. 503: Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200: Success
  2. 203: Device Not Found
  3. 400: Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute "id" is an integer but string value gets passed.
  4. 401: Unauthorized Request. Access to API is forbidden.
  5. 404: Not Found - URL Not Found

Alarm

User can get an alert whenever a particular event occurs by configuring alarm to your vehicle or user. For example, an alert can be sent to the user whenever user or vehicle Enters/Exits the particular area or if the vehicle or user is Over Speeding or vehicle battery is low, etc. etc. These alerts are highly configurable based on different requirements.

5.1 Configure Alarms

Some of the important and more frequently used alarms for different use cases are listed below.

  • Geofence
  • Ignition
  • OverSpeed
  • UnPlugged
  • Panic
  • Stoppage
  • Idle
  • Towing
  • GPRS Connectivity
  • Vehicle Battery
  • Mileage
  • GPS connectivity
  • Distance Covered
  • Internal Battery Voltage

5.1.1 Geofence Alarm

Configure geofence alarm by assigning the vehicle to particular Geofence to get an alert when the user or vehicle enters/ exits the particular area. Geofence should be created before assigning the vehicle to geofence in alarms configuration. Refer Create Geofence documentation to create Geofence. Get Geofence method will fetch Geofence Ids.

Mandatory parameters:
  • Alarm Type, id(s) of device(s), Id(s) of geofence(s)and Type of geofence

5.1.2 Ignition Alarm

Configure Ignition alarm to trigger an alert when the vehicle ignition is switched On or Off. Assign vehicles against this alarm.

Manadatory Parameters
  • Alarm Type, Id(s) of the device(s) and type of Ignition

5.1.3 Over Speed Alarm

Configure Overspeed alarm to trigger an alert when user or vehicle crosses the configured speed limit.

Mandatory parameters:
  • Alarm Type, Id(s) of the device(s), Limit and Duration

5.1.4 Unplugged Alarm

Configure an unplugged alarm to trigger an alert when a vehicle tracking device is removed from the vehicle battery

Mandatory parameters:
  • Alarm Type and Id(s) of the device(s)

5.1.5 Panic Alarm

Configure Panic alert using the below method. Assign this alert to the device to trigger an alert whenever the user presses the panic button.

Mandatory parameters:
  • Alarm Type and Id(s) of the device(s)

5.1.6 Stoppage Alarm

Configure Stoppage alarm to alert you when the user or vehicle continuously stays in the stopped condition for more than the defined duration.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s) and Duration

5.1.7 Idle Alarm

Configure Idle alarm to alert you when the vehicle continuously stays in the Idle condition (Engine is on but the speed is less than 7 km/hr) for more than the defined duration.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s) and Duration

5.1.8 Towing Alarm

Configure Towing alarm to alert you when the vehicle moves at more than 7km/hr speed in Engine off state.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s) and Duration

5.1.9 GPRS Connectivity Alarm

GPRS connectivity alarm alerts you when the user or vehicle doesn't send the data to server for more than the defined duration as per configuration.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s) and Duration

5.1.10 Vehicle Battery Alarm

Configure Vehicle battery alarm to alert you when the vehicle battery goes below the configured voltage value.

Mandatory parameters:
  • Alarm Type, Id(s) of the device(s), Limit and Duration

5.1.11 Mileage Alarm

Configure Mileage alarm to alert you when the vehicle or user travels the configured distance within the time duration. The distance can be configured for Daily and Monthly limit.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s), Type and Duration

5.1.12 GPS Connectivity Alarm

Configure GPS connectivity alarm to trigger an alert when the user or vehicle doesn't send the valid location to the server for more than the defined duration as per configuration.

Mandatory parameters:
  • Alarm Type, Id(s) of device(s) and Duration

5.1.13 Distance Covered Alarm

Configure Distance covered alarm to trigger an alert when the vehicle or user covers the particular distance in the given duration or if the user travels less than the limit in the given duration then the alert will be triggered.

There are two types of distance covered alarm.
  • At least
  • At Most.

For example At least will be used whenever a user doesn't travel 30 km within 1 hr.

At most can be used when the user travels more than 30 km in 1hr.

Mandatory parameters:
  • Alarm Type, Id(s) of the device(s), Type, Limit and Duration

5.1.14 Internal Battery Voltage Alarm

Configure Internal battery alarm to alert you when the Vehicle Tracking device Internal battery goes below the configured voltage value for a certain duration.

Mandatory parameters:
  • Alarm Type, Id(s) of the device(s), Limit and Duration

Create Alarm Method

Define the hashmap as mentioned above based on the required alarm then call the below method.

// ICreateAlarmListener - returns success if alarm created successfully, else error as callback methods.
InTouch.createAlarm(hashMap, new ICreateAlarmListener() {  
        @Override  
  public void onSuccess(CreateAlarmResponse createAlarmResponse) {  
	  // write your code here.
  }  
        @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
             // errorIdentifier gives information about error code. 
             // error description gives a message for a particular error.
        }  
    });   
});
Request Parameters based on different Alarms.
  1. deviceId - Device id(s). You can pass a single device Id or multiple device Ids in the array.
  2. type - Type is based on different alarms. Only required in case of the Geofence, Ignition, Mileage and Distance Covered alarm. For this directly you can enter the respective integer values as mentioned below or else you can use the InTouch Constants. e.g: for AlarmType - Geofence(value-26), one of the type value is InTouchConstants.ALARM_GEOFENCE_ENTRY (value -2). Click to see more values.
  3. duration - Time duration in seconds. Only required in case of Overspeed, stoppage, idle, towing, GPRS connectivity, vehicle battery, GPS connectivity, distance covered, internal battery alarm.
  4. limit - Limits for various alarms based on alarm type. It is an integer. eg: 55. Unit changes for different alarm type.
    • Overspeed Alarm - km/hr
    • vehicle battery - millivolts
    • mileage - in km/hr
    • distance covered - meters
    • internal battery alarm - millivolts
  5. geofenceId- Geofence Id(s). Only required in case of alarm Type Geofence. You can pass a single geofence ID or multiple geofence IDs in array.
  6. alarmType- For each type of alarm constant value is being assigned. Type of alarm to create. Following are the alarm types & their corresponding IDs. Ignition: 21, Overspeed: 22, Unplugged: 23, Panic: 24, Geofence: 26, Stoppage: 27, Idle: 28, Towing: 29, GPRS Connectivity: 126, Vehicle Battery: 129, Mileage: 133, GPS Connectivity: 146, Distance Covered: 151, Internal Battery Voltage:161

Note:- User can use these request parameters as key in HashMap<String, String> according to different alarms type and mandatory fields required for that alarm type.

User may use InTouchConstants class of InTouch Sdk for different alarm type values like for geofence alarm type is 26, user can use InTouchConstants.ALARM_GEOFENCE instead of 26.

Response Code

Success

  1. 201 To denote successful record is being created.

Client-side issues

  1. 400 Bad Request, User made an error while creating a valid request.
  2. 401 Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403 Forbidden, Developer.s key has hit its daily hourly limit.

Server-sde issues

  1. 500 Internal Server Error, the request caused an error in our systems.
  2. 503 Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200 Success
  2. 203 Device Not Found
  3. 400 Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute id is an integer but string value gets passed.
  4. 401 Unauthorized Request. Access to API is forbidden.
  5. 404 Not Found - URL Not Found
Response Parameter

CreateAlarmResponse class object returns the API response as JSON object.

Create Alarm Response result parameters

id (Long) Id of the newly created Alarm.

5.2 Get Alarm configurations

Use the below methods to retrieve the configured alarms in your account with unique alarm ID.

5.2.1 Get All Alarm configurations

In the getAlarmConfigs(), Input parameters like devices or Alarm type or Alarm Ids can be passed to filter the particular set alarm configurations.

\\\ Get all Alarm config
// IGetAlarmsListener - returns all alarms configurations if success, else error as callback methods.
InTouch.getAlarmConfigs(new IGetAlarmsListener() {  
  @Override  
  public void onSuccess(InTouchAlarmResponse inTouchAlarmResponse) {  
		 // write your code here. 
    }  
  @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
             // error description gives a message for a particular error.
    }  
});

5.2.2 Get alarm configurations based on the selected parameter

In the getAlarmConfigs(), Input parameters like devices or Alarm type or Alarm Ids can be passed to filter the particular set alarm configurations.

// Alarms configurations on the basis of different selected parameters. User can pass null if none of the given parameters is required.
InTouch.getAlarmConfigs(array of alarmIds, array of deviceIds, array of alarmTypes,new IGetAlarmsListener() {  
  @Override  
  public void onSuccess(InTouchAlarmResponse inTouchAlarmResponse) {  
		 // write your code here.
    }  
  @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
    }  
});
Request Parameters

1.alarmIds (Long[]) Array of alarmIds. User can pass alarmIds array to get alarm configurations for provided ids otherwise pass null for all configurations. 2. deviceIds (Long[]) Array of deviceIds. User can pass deviceIds array for selected devices alarm configurations otherwise pass null for all configurations. 3. alarmTypes (Integer[]) Array of alarm types. User can pass alarm types array for selected alarm type alarms configurations otherwise pass null for all configurations.

Response Code

Success

  1. 200 To denote a successful API call.

Client-side issues

  1. 400 Bad Request, User made an error while creating a valid request.
  2. 401 Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403 Forbidden, Developer.s key has hit its daily hourly limit.

Server-side issues

  1. 500 Internal Server Error, the request caused an error in our systems.
  2. 503 Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message
  1. 200 Success
  2. 203 Device Not Found
  3. 400 Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute id is an integer but string value gets passed.
  4. 401 Unauthorized Request. Access to API is forbidden.
  5. 404 Not Found - URL Not Found
Response Parameter

InTouchAlarmResponse class object returns the API response as a JSON object.

InTouchGeoFenceResponse result parameters

- ListAlarmsConfig List of AlarmsConfig.

AlarmsConfig Parameters

  1. id(Long)- Id of alarm
  2. deviceId(Long)- Device Id(s) on which the alarm config got created.
  3. alarmType(Integer) -Type of alarm for eg - 21 (InTouchConstants.ALARM_IGNITION) etc.
  4. limit(Integer)- Min or Max limit for particular alarm.
  5. duration (integer) - Min or Max duration in second(s) for particular alarm.
  6. type(Integer)- Values depends on the type of alarm configured for eg for Mileage alarm it should be 0 (InTouchConstants.ALARM_MILEAGE_DAILY) or 1 (InTouchConstants.ALARM_MILEAGE_MONTHLY).
  7. updationTime(Long)- Epoch Time at which the alarm got updated.
  8. creationTime(Long)- Epoch Time at which the alarm got configured.
  9. geofenceId(Long[])- If returned alarm type is geofence (26), then this will return the list of geofences for which alarms were configured.

5.3 Update Alarms(s)

Already created alarms can be updated using below-mentioned methods. It is similar to create alarm but additionally, alarm ID should be the input parameter to update the respective individual alarm configurations.

Alarm Id can be fetched from the Get Alarm config

Based on the Alarm type, Mandatory parameter should be passed in the Hashmap.

// IUpdateAlarmListener - returns success if alarm updated successfully, else error as callback methods.
InTouch.updateAlarm(alarmId, HashMap of Alarm Parameters, new IUpdateAlarmListener() {  
  @Override  
  public void onSuccess() {  
		  // write your vode here.
  }  
  @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
  }  
});
Request Parameters
  1. alarmId(Long) - Id of the existing alarm.
  2. deviceId (Long[]) - Array of device id(s). You can pass a single deviceID or multiple deviceIDs in an array.
  3. type (Integer) - Type is based on different alarms i.e) Only required in case of the geofence, ignition, mileage and Distance Covered alarm.
  4. duration (Integer) - Time duration in seconds. Only required in case of Overspeed, stoppage, idle, towing, GPRS connectivity, vehicle battery, GPS connectivity, distance covered, internal battery alarm.
  5. limit (Integer) - Limits for various alarms based on alarm type.
  6. geofenceId (Long []) - Array of geofence id(s). Only required in case of alarm Type Geofence. You can pass a single geofence ID or multiple geofence IDs in an array.
  7. alarmType (Integer) - For each type of alarm constant value is being assigned. Selected alarm id's alarm type should be passed. It can be passed from the IntouchConstants or as an integer value. Following are the alarm types & their corresponding IDs. Ignition: 21, Overspeed: 22, Unplugged: 23, Panic: 24, Geofence: 26, Stoppage: 27, Idle: 28, Towing: 29, GPRS Connectivity: 126, Vehicle Battery: 129, Mileage: 133, GPS Connectivity: 146, Distance Covered: 151, Internal Battery Voltage:161
Response Code

Success

  1. 200 To denote a successful API call.

Client-side issues

  1. 400 Bad Request, User made an error while creating a valid request.
  2. 401 Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403 Forbidden, Developer.s key has hit its daily hourly limit.

Server-sde issues

  1. 500 Internal Server Error, the request caused an error in our systems.
  2. 503 Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200 Success
  2. 203 Device Not Found
  3. 400 Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute id is an integer but string value gets passed.
  4. 401 Unauthorized Request. Access to API is forbidden.
  5. 404 Not Found - URL Not Found
Response Parameter

API response will return as IUpdateAlarmListener onSuccess() or onError(String reason, String errorIdentifier, String errorDescription) methods.

5.4 Delete Alarm configuration.

deleteAlarm method can be used to delete the already configured alarm. In this method, alarm ID needs to be passed to delete the configurations.

5.4.1 Delete single Alarm configuration

// Delete single alarm
// IResultListener- returns success if alarm deleted successfully, else error as callback methods.
InTouch.deleteAlarm(alarmId, new IResultListener() {  
  @Override  
  public void onSuccess() {  
		// write your code here.
  }  
  @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
 }   
});

5.4.2 Delete Multiple Alarm configuration

Delete multiple alarm
InTouch.deleteAlarm(alarmIds array, new IResultListener() {  
 @Override  
 public void onSuccess() {  
   	// write your code here.
 }  
 @Override  
 public void onError(String reason, String errorIdentifier, String errorDescription) {  
   		   // reason gives the error type. 
             // errorIdentifier gives information about error code. 
             // error description gives a message for a particular error.
 }
});
Request Parameters
  1. alarmId(Long) Id or Long[] ids of the alarm config(s) which user wants to delete.
Response Code

Success

  1. 200 To denote a successful API call.

Client-side issues

  1. 400 Bad Request, User made an error while creating a valid request.
  2. 401 Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403 Forbidden, Developer.s key has hit its daily hourly limit.

Server-sde issues

  1. 500 Internal Server Error, the request caused an error in our systems.
  2. 503 Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200 Success
  2. 203 Device Not Found
  3. 400 Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute id is an integer but string value gets passed.
  4. 401 Unauthorized Request. Access to API is forbidden.
  5. 404 Not Found - URL Not Found

5.5 Alarm Logs

Once the alert is triggered based on the configured alarms, the below method can be used to get the Alarm log details. Alarm log gives the information about the device name, Alarm type location and time at which alert is being triggered.

5.5.1 Get All alarm Logs.

Get all type of alarm log between the start and end time of the input using the below method.

// Get Alarm Logs
// IGetAlarmsLogsListener - returns all alram logs if success, else error as callback methods.
InTouch.getAlarmsLogs(startTime endTime, new IGetAlarmsLogsListener() {  
    @Override  
  public void onSuccess(InTouchAlarmLogsResponse inTouchAlarmLogsResponse) {  
       // write your code here.  
    }    
    @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
    } 
});

5.5.2 Get alarm Logs with filter.

Get the filtered alarm log information between the start and end time by sending the filter details like device id, Alarm type.

 with filter
InTouch.getAlarmsLogs(deviceIds array, alarmType array,startTime ,endTime, new IGetAlarmsLogsListener() {  
    @Override  
  public void onSuccess(InTouchAlarmLogsResponse inTouchAlarmLogsResponse) {  
       // write your code here. 
    }  
    @Override  
  public void onError(String reason, String errorIdentifier, String errorDescription) {  
			  // reason gives the error type. 
              // errorIdentifier gives information about error code. 
              // error description gives a message for a particular error.
   } 
});
Request Parameters
  1. startTime(Long)- Mandatory field. This is start EPOCH timestamp in seconds.
  2. endTime(Long)- Mandatory field. This is end EPOCH timestamp in seconds
  3. deviceId(Long[]) - Non mandatory field. This is the ID of the device for which the alarm logs need to be fetched. You can pass a single device ID or multiple device IDs separated by a comma. For eg new Long[]{1L} or null.
  4. alarmType(Integer[])- Non mandatory field. This is the type of alarm for which the alarm log needs to be fetched. You can pass a single alarm type or multiple alarm type separated by a comma. For eg new Integer[]{IntouchConstant.ALARM_IGNITION} or new Integer[]{21} or null.
Response Code

Success

  1. 200 To denote a successful API call.

Client-side issues

  1. 400 Bad Request, User made an error while creating a valid request.
  2. 401 Unauthorized, Developer.s key is not allowed to send a request with restricted parameters.
  3. 403 Forbidden, Developer.s key has hit its daily hourly limit.

Server-sde issues

  1. 500 Internal Server Error, the request caused an error in our systems.
  2. 503 Service Unavailable, during our maintenance break or server downtimes.
Response Messages (as HTTP response message)
  1. 200 Success
  2. 203 Device Not Found
  3. 400 Bad Request - Invalid device ID supplied or invalid data type. For example, input attribute id is an integer but string value gets passed.
  4. 401 Unauthorized Request. Access to API is forbidden.
  5. 404 Not Found - URL Not Found
Response Parameter

InTouchAlarmResponse Class object returns the API response as JSON object.

InTouchAlarmLogsResponse result parameters

- ListAlarmLogs List of AlarmLogs.

AlarmsConfig Parameters

  1. deviceId(Long) - Id of the device for which the alarm got generated.
  2. timestamp(Long)- EPoch Time at which the alert got generated.
  3. latitude(Double) - Location latitude
  4. longitude(Double)- Location longitude.
  5. address(String) - Location address at which the alarm got generated.
  6. alarmType(Integer) - Type of alarm to create alarm. Following are the alarm types & their corresponding IDs.
    Ignition 21, Overspeed 22, Unplugged 23, Panic 24, Geofence 26, Stoppage 27, Idle 28, Towing 29, GPRS connectivity 126, Vehicle Battery 129, Mileage 133, GPS Connectivity 146, Distance Covered 151, Internal Battery Voltage 161,
  7. limit(Integer)- Alarm limit as set in the config. For example, if an Overspeed alarm set on the limit of 44 km/hr in the alarm config setting, then this attribute will return 44 km/hr.
  8. duration(Integer) - Alarm duration limit as set in the alarm config section. For example, if the duration of Overspeed alarm is set as 20 secs, then the alarm will generate when the vehicle over speeds for 20 secs.
  9. actualLimit(Integer) -The actual data received from the device at that particular moment when the alarm got generated.
  10. actualDuration(Integer) - Actual duration for which the device breached the alarm config
  11. severity(Integer) - 0 - Low Severity. 1 - High Severity
  12. data(Integer)- Describes the state of the alarm. Ignition(type = 21), 0 Off & 1 On. AC(type=25), 0 OFF, 1 ON. Geofence (type=26), 1 Entry & Exit Geofence 2 Entry Geofence, 3 Leaving Geofence & 4 Long Stay In Geofence.
  13. geofenceId(Integer)- This is the ID of the geofence for which the alarm got generated. This will come only when the 'type' field returns 26 i.e) geofence.

Tracking Error

1. [AUTHORIZATION_ERROR](Mapmyindia)
Your free trial ended or account was not renewed.

2. [GPS_PROVIDER_DISABLED_ERROR](mapmyindia)
Tracking won't start due to disabled gps.

3. [INVALID_PUBLISHABLE_KEY_ERROR](mapyindia)
The publishable key is invalid.

4. [PERMISSION_DENIED_ERROR](mapmyindia)
Tracking won't start due to denied (or absent) permission.

5. [UNKNOWN_ERROR](mapmyindia)
An error that we couldn't recognize.

InTouch Constants

Alarm Type

ALARM_IGNITION = 21;
ALARM_OVERSPEED = 22;
ALARM_UNPLUGGED = 23;
ALARM_PANIC = 24;
ALARM_GEOFENCE = 26;
ALARM_STOPPAGE = 27;
ALARM_IDLE = 28;
ALARM_TOWING = 29;
ALARM_GPRS_CONNECTIVITY = 126;
ALARM_VEHICLE_BATTERY = 129
ALARM_MILEAGE = 133;
ALARM_GPS_CONNECTIVITY = 146;
ALARM_DISTANCE_COVERED = 151;
ALARM_INTERNAL_BATTERY_VOLTAGE = 161;

type :

Geofence Alarm type:

ALARM_GEOFENCE_ENTRY_EXIT = 1;
ALARM_GEOFENCE_ENTRY = 2;
ALARM_GEOFENCE_EXIT = 3;
ALARM_GEOFENCE_STAY_LONG = 4;

Ignition alarm type:

ALARM_IGNITION_ON_OFF = 1;
ALARM_IGNITION_ON = 2;
ALARM_IGNITION_OFF = 3;
ALARM_DAY_FIRST_IGNITION = 5;

Mileage alarm type:

AALARM_MILEAGE_DAILY = 0;
ALARM_MILEAGE_MONTHLY = 1;

Distance Covered alarm type:

ALARM_DISTANCE_COVERED_ATLEAST = 1;
ALARM_DISTANCE_COVERED_ATMOST = 2;