+27 87 310 6400 | products@afrigis.co.za
bclose

Locate-a-phone

The location based service (LBS) allows users to locate mobile devices (with prior consent).

LocateAPhone_2

AfriGIS Locate-a-phone Web Services

The AfriGIS Locate-a-phone web services may be used to find the approximate position of any mobile device with an active SIM on the Vodacom and MTN cellular networks in South Africa.

 

See also:

www.locateaphone.co.za

API DOCUMENTATION

1. Introduction

2. How to try

3. Quick locate process (overview)

4. Normal locate process (overview)

5. SuperLocate methods (overview)

 

1. Introduction

This document serves as a guide on how to implement the AfriGIS Locate-a-phone web methods for the process flows and describes methods used for managing users and contacts.The AfriGIS Locate-a-phone web services may be used to find the approximate* position of any mobile device with an active SIM on the Vodacom and MTN cellular networks in South Africa.  In order to protect a person’s privacy, the system manages the permissions required to locate the SIM, by requesting a reply from the person in possession of the device.

The following terminology is used for the remainder of this document: A “user” locates a mobile device (“locatee”) identified by its “MSISDN” (which can be saved as a “contact”).

*  The position returned is a location-based service (LBS) position, the accuracy of which depends on the cellular network coverage.  In higher density urban areas the accuracy will be better than in rural areas.  It is not as accurate as a Global Positioning System (GPS) position.

Features:

  • Locate a SIM based on an MSISDN number.
  • Manage a user’s Locate-a-phone contacts.
  • Enables automated systems to locate MSISDN numbers.
There are three process flows available in order to successfully locate contacts (MSISDNs):
  • Normal locate process
    • A logged in user can locate saved contacts, as well as create, edit and delete contacts. The user must register and authenticate himself with a one-time password (OTP) first.
  • Quick locate process
    • The user is not logged in, so does not have access to saved contacts. Each locate request to a MSISDN must therefore be authenticated with an OTP to the user first. The MSISDN is also saved as a new contact.
  • SuperLocate process
    • A trusted user can locate any MSISDN, without requesting permission from the locatee. Optionally, the proximity to a Street Address, SEOID or coordinate can be checked.
Except for the SuperLocate process, the locatee must authorise each locate request by replying with an SMS or by following a link to the website.  The options available are:

  • yes (once only)
  • 30 (days)
  • no (not now)
  • block (this person)
If the 30 days option is selected, no authorisation SMS will be sent for another request from that user for the next 30 days.

 

2. How to try:

Contact AfriGIS to obtain a ClientID and ClientPassword.  Create a SOAP request and POST (or GET) the parameter data to:

https://www.locateaphone.co.za/service.asmx/<MethodName>

e.g. https://www.locateaphone.co.za/service.asmx/QuickLocate

The Active Server Method File (.asmx) can be found at: https://www.locateaphone.co.za/service.asmx which will provide a list of all the methods as well as the WSDL definition.

 

3. Quick locate process (overview)

locateaphone_overview

 

Step 1: Initialise quick locate

QuickLocate (int ClientID, string ClientPassword, string UserMSISDN, string UserName, string ContactMSISDN)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserMSISDNThe user’s cellphone number.
UserNameThe user’s name.
ContactMSISDNCellphone number to locate.

e.g. https://www.locateaphone.co.za/service.asmx/QuickLocate?ClientID=1&ClientPassword=pa$$word&UserMSISDN=27821234567&UserName=John&ContactMSISDN=27829876543

Returns:

On success:

{“contactID”:123,”status”:true,”message”:”Expired”}

On failure:

{“contactID”:-1,”status”:false,”message”:”Invalid Client”}

Note:

message above indicates contact’s last reply status.

 

Step 2: Verify user

VerifyUserPassword (int ClientID, string ClientPassword, string MSISDN, string UserPassword)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
MSISDNThe user’s cellphone number.
UserPasswordPassword sent to user’s cellphone.

e.g. https://www.locateaphone.co.za/service.asmx/VerifyUserPassword?ClientID=1&ClientPassword=pa$$word&MSISDN=27821234567&UserPassword=12345

Returns:

On success:

{“userID”:12,”userName”:”John”,”status”:true,”message”:”Verified”}

On failure:

{“userID”:-1,”userName”:”Unknown”,”status”:”false”,”message”:”Invalid credentials”}

 

Step 3: Check if authorisation was granted and then locate

This method may be polled until a successful result has been returned or the timeout limit expires.

LocatePhone (int ClientID, string ClientPassword, int ContactID)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
ContactIDID specifying the contact to locate (see response from Step 3 or 4).

e.g. https://www.locateaphone.co.za/service.asmx/LocatePhone?ClientID=1&ClientPassword=pa$$word &ContactID=123

Returns:

On success:

{“longitude”:28.234080,”latitude”:-25.746670,”located”:true,”message”:”Phone located”, “location”:”Main Street, Waterkloof, Pretoria, Gauteng”}

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Waiting”,”location”:null}

Notes:

  • Method should only be polled while message value is ‘Waiting’.
  • An authorisation SMS will only be sent to the contact on the first call of this method, or after the resend timeout has elapsed (currently 5 minutes).

 

4.Normal locate process (overview)

locateaphone_normal

Step 1: Register a new user

RegisterUser (int ClientID, string ClientPassword, string UserMSISDN, string UserName, string UserSurname)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserMSISDNThe user’s cellphone number.
UserNameThe user’s name.
UserSurnameThe user’s surname.

e.g. https://www.locateaphone.co.za/service.asmx/RegisterUser?ClientID=1&ClientPassword=pa$$word&UserMSISDN=27821234567&UserName=John&UserSurname=Smith

Returns:

On success:

{“userID”:12,”status”:”true”,”message”:”User registered successfully”}

On failure:

{“userID”:-1,”status”:”false”,”message”:”User account suspended”}

 

Step 2: Verify User (Login)

VerifyUserPassword (int ClientID, string ClientPassword, string MSISDN, string UserPassword)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
MSISDNThe user’s cellphone number.
UserPasswordPassword sent to user’s cellphone.

e.g. https://www.locateaphone.co.za/service.asmx/VerifyUserPassword?ClientID=1&ClientPassword=pa$$word&MSISDN=27821234567&UserPassword=12345

Returns:

On success:

{“userID”:12,”userName”:”John”,”status”:true,”message”:”Verified”}

On failure:

{“userID”:-1,”userName”:”Unknown”,”status”:”false”,”message”:”Invalid credentials”}

 

Step 3: Retrieve user’s contacts

GetUserContacts (int ClientID, string ClientPassword, int UserID)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserIDID of the user whose contacts are to be returned.

e.g. https://www.locateaphone.co.za/service.asmx/GetUserContacts?ClientID=1&ClientPassword=pa$$word&UserID=12

Returns:

On success:

[{“contactID”:123, “MSISDN”:”27829876543″, “name”:”Jane”, “message”:”Success”}, {“contactID”:124, “MSISDN”:”27828765432″, “name”:”Jill”, “message”:”Success”}] On failure:

[{“contactID”:-1,”MSISDN”:””,”name”:””,”message”:”There are no contacts for this user”}]

 

Step 4: Add a new contact

AddContact (int ClientID, string ClientPassword, int UserID, string ContactMSISDN, string ContactName)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserIDID of the user adding a contact.
ContactMSISDNThe cell phone number of the new contact.
ContactNameThe name of the new contact.

e.g. https://www.locateaphone.co.za/service.asmx/AddContact?ClientID=1&ClientPassword=pa$$word&UserID=12&ContactMSISDN=27828765432&ContactName=Jill

Returns:

On success:

{“contactID”:124,”status”:”true”,”message”:”Successfully added contact”}

On failure:

{“contactID”:124,”status”:”false”,”message”:”Contact already exists”}

 

Step 5: Locate a contact

This method may be polled until a successful result has been returned or the timeout limit expires.

LocatePhone (int ClientID, string ClientPassword, int ContactID)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
ContactIDID specifying the contact to locate (see response from Step 3 or 4).

e.g. https://www.locateaphone.co.za/service.asmx/LocatePhone?ClientID=1&ClientPassword=pa$$word &ContactID=123

Returns:

On success:

{“longitude”:28.234080,”latitude”:-25.746670,”located”:true,”message”:”Phone located”,”location”:”Main Street, Waterkloof, Pretoria, Gauteng”}

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Waiting”,”location”:null}

Notes:

  • Method should only be polled while message value is ‘Waiting’.
  • An authorisation SMS will only be sent to the contact on the first call of this method, or after the resend timeout has elapsed (currently five (5) minutes).

 

Other management functions

A user may want to edit or delete contacts or edit his own user details (including changing his own password).  Also the user’s password can be sent via SMS to his mobile number.  For these management functions, call the following methods:

  • DeleteContact
  • EditContact
  • EditUser
  • SMSUserPassword
DeleteContact (int ClientID, string ClientPassword, int ContactID)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
ContactIDID of the contact to delete.

e.g. https://www.locateaphone.co.za/service.asmx/DeleteContact?ClientID=1&ClientPassword=pa$$word&ContactID=123

Returns:

On success:

{“status”:”true”,”message”:”Successfully deleted contact”}

On failure:

{“status”:”false”,”message”:”Contact does not exist”}
EditContact (int ClientID, string ClientPassword, int ContactID, string ContactNewName)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
ContactIDID of the contact to edit.
ContactNewNameThe new name of the contact.

e.g. https://www.locateaphone.co.za/service.asmx/EditContact?ClientID=1&ClientPassword=pa$$word&ContactID=123&ContactNewName=Jane

Returns:

On success:

{“status”:”true”,”message”:”Successfully edited contact”}

On failure:

{“status”:”false”,”message”:”Contact does not exist”}
EditUser (int ClientID, string ClientPassword, int UserID, string UserNewName, string UserNewSurname, string UserNewPassword)

Note: Passing an empty string to parameters for new name, surname or password will leave value unchanged.

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserIDID of the user to edit.
UserNewNameThe new name of the user.
UserNewSurnameThe new surname of the user.
UserNewPasswordThe new password of the user.

e.g. https://www.locateaphone.co.za/service.asmx/EditUser?ClientID=1&ClientPassword=pa$$word&UserID=12&UserNewName=John&UserNewSurname=&UserNewPassword=

Returns:

On success:

{“status”:”true”,”message”:”Successfully edited user”}

On failure:

{“status”:”false”,”message”:”User does not exist”}

 

SMSUserPassword (int ClientID, string ClientPassword, string UserMSISDN)

ParameterDescription
ClientIDID specifying client used.
ClientPasswordThe password of the specified client.
UserMSISDNThe user’s cellphone number

e.g. https://www.locateaphone.co.za/service.asmx/SMSUserPassword?ClientID=1&ClientPassword=pa$$word&UserMSISDN=27821234567

Returns:

On success:

{“status”:”true”,”message”:”Password sent”}

On failure:

{“status”:”false”,”message”:”Unregistered user”}

 

5. SuperLocate methods (overview)

The “SuperLocate” web methods allow a registered user (typically an automated process) with special privileges, to locate a mobile device without awaiting authorisation from the locatee of the device being located. Authorisation permission should thus be collected and stored by the system implementing this web method.

The AddressPhoneProximity, CoordPhoneProximity and SEOIDPhoneProximity extensions to SuperLocate first super locate the MSISDN and then check whether this position is within a specified range of the given Street Address, Coordinate or SEOID.

SuperLocate (int userID, string locateeMSISDN, string message, string authenticationCode)

ParameterDescription
UserIDID specifying user.
locateeMSISDNCellphone number to locate.
message*A unique string, created by concatenating the locateeMSISDN and the current ISO 8601 formatted datetime with a Pipe (“|”). See the example below.
authenticationCodeBase64 Encoded HMACSHA1 of the message parameter, using UserPassword as the shared secret.

* locateeMSISDN|yyyy-mm-ddThh:mm:ss e.g. 27829876543|2015-07-28T14:39:39

(in this case, the authenticationCode, using UserPassword = 99999, will be c/9ySpxTTIwuGG/krYs+xWDLM2E= )

Because the authenticationCode can contain URL-unsafe characters such as slash (“/”), plus (“+”) and equals (“=”), it may need to be URL-encoded (in this case, authenticationCode becomes c%2F9ySpxTTIwuGG%2FkrYs%2BxWDLM2E%3D )

Notes:

  • The time difference between the server and the time in the message parameter must be less than five (5) minutes otherwise the web service will fail. The timezone is SAST (GMT+2).
  • URL encode the parameters if the service is called via HTTP GET.
e.g. https://www.locateaphone.co.za/service.asmx/SuperLocate?UserID=12&locateeMSISDN=27829876543&message=27829876543|2015-07-28T14:39:40&authenticationCode=c%2F9ySpxTTIwuGG%2FkrYs%2BxWDLM2E%3D

Returns:

On success:

{“longitude”:28.230324,”latitude”:-25.776608,”located”:true,”message”:”Phone located”,”accuracy”:1000,”timeLocated”:”2015-07-27T16:38:43″, “location”:”Main Street, Waterkloof, Pretoria, Gauteng”}

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Unauthorised user.”,”accuracy”:1000,”timeLocated”:””,”location”:””}
AddressPhoneProximity (int userID, string locateeMSISDN, string address, double radius, string message, string authenticationCode)

ParameterDescription
UserIDID specifying user.
locateeMSISDNCellphone number to locate.
addressStreet address to compare for proximity.
radiusDistance (in metres) to check for proximity.
message*A unique string, created by concatenating the locateeMSISDN and the current ISO 8601 formatted datetime with a Pipe (“|”). See the example for SuperLocate above.
authenticationCodeBase64 Encoded HMACSHA1 of the message parameter, using UserPassword as the shared secret.

e.g. https://www.locateaphone.co.za/service.asmx/AddressPhoneProximity?UserID=12&locateeMSISDN=27829876543&address=446+Rigel+Avenue&radius=1000&message=27829876543|2015-07-28T14:39:40&authenticationCode=zxeEaq75JRaCna7ipU6Hv3qdoys=

Returns:

On success:

{“longitude”:28.230324,”latitude”:-25.776608,”located”:true,”message”:”Phone located”,”accuracy”:1000,”timeLocated”:”2015-07-27T16:41:43″,”location”:”Main Street, Waterkloof, Pretoria, Gauteng”,”withinRange”:false,”distance”:4408.2,”searchLon”:28.25611,”searchLat”:-25.8087}

 

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Unauthorised user.”,”accuracy”:1000,”timeLocated”:””,”location”:””,”withinRange”:false,”distance”:0,”searchLon”:0,”searchLat”:0}
If the address could not be geocoded:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”address could not be located or invalid address entered.”,”accuracy”:1000,”timeLocated”:””,”location”:””,”withinRange”:false,”distance”:0,”searchLon”:0,”searchLat”:0}
CoordPhoneProximity (int userID, string locateeMSISDN, double latitude, double longitude, double radius, string message, string authenticationCode)

ParameterDescription
userIDID specifying user.
locateeMSISDNCellphone number to locate.
latitudeCoordinate to compare for proximity.
longitude
radiusDistance (in metres) to check for proximity.
message*A unique string, created by concatenating the locateeMSISDN and the current ISO 8601 formatted datetime with a Pipe (“|”). See the example for SuperLocate above.
authenticationCodeBase64 Encoded HMACSHA1 of the message parameter, using UserPassword as the shared secret.
e.g. https://www.locateaphone.co.za/service.asmx/CoordPhoneProximity?UserID=12&locateeMSISDN=27829876543&latitude=-25.8087&longitude=28.25611&radius=1000&message=27829876543|2015-07-28T14:39:40&authenticationCode=zxeEaq75JRaCna7ipU6Hv3qdoys=

Returns:

On success:

{“longitude”:28.230324,”latitude”:-25.776608,”located”:true,”message”:”Phone located”,”accuracy”:1000,”timeLocated”:”2015-07-27T16:41:43″,”location”:”Main Street, Waterkloof, Pretoria, Gauteng”,”withinRange”:false,”distance”:4408.2,”searchLon”:28.25611,”searchLat”:-25.8087}

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Unauthorised user.”,”accuracy”:1000,”timeLocated”:””,”location”:””,”withinRange”:false,”distance”:0,”searchLon”:0,”searchLat”:0}
SEOIDPhoneProximity (int userID, string locateeMSISDN, string seoid, double radius, string message, string authenticationCode)

ParameterDescription
userIDID specifying user.
locateeMSISDNCellphone number to locate.
seoidAfriGIS SEOID or DOCID to compare for proximity.
radiusDistance (in metres) to check for proximity.
message*A unique string, created by concatenating the locateeMSISDN and the current ISO 8601 formatted datetime with a Pipe (“|”). See the example for SuperLocate above.
authenticationCodeBase64 Encoded HMACSHA1 of the message parameter, using UserPassword as the shared secret.

e.g. https://www.locateaphone.co.za/service.asmx/SEOIDPhoneProximity?UserID=12&locateeMSISDN=27829876543&seoid=Ca155B0201010105055C08_30342d4F43542D3134&radius=1000&message=27829876543|2015-07-28T14:39:40&authenticationCode=zxeEaq75JRaCna7ipU6Hv3qdoys=

Returns:

On success:

{“longitude”:28.230324,”latitude”:-25.776608,”located”:true,”message”:”Phone located”,”accuracy”:1000,”timeLocated”:”2015-07-27T16:41:43″,”location”:”Main Street, Waterkloof, Pretoria, Gauteng”,”withinRange”:false,”distance”:4408.2,”searchLon”:28.25611,”searchLat”:-25.8087}

On failure:

{“longitude”:0,”latitude”:0,”located”:false,”message”:”Unauthorised user.”,”accuracy”:1000,”timeLocated”:””,”location”:””,”withinRange”:false,”distance”:0,”searchLon”:0,”searchLat”:0}

If the SEOID could not be found:

{“longitude”:0,”latitude”:-0,”located”:false,”message”:”seoid could not be located or invalid seoid entered.”,”accuracy”:1000,”timeLocated”:””,”location”:””,”withinRange”:false,”distance”:0,”searchLon”:0,”searchLat”:0}

Project Details