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:
[fancy-ul variation=”blue” style=”arrow”]

• Locate a SIM based on an MSISDN number.
• Manage a user’s Locate-a-phone contacts.
• Enables automated systems to locate MSISDN numbers.

[/fancy-ul] There are three process flows available in order to successfully locate contacts (MSISDNs):
[fancy-ul variation=”blue” style=”arrow”]

• 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.

[/fancy-ul] 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:

[fancy-ul variation=”blue” style=”arrow”]

• yes (once only)
• 30 (days)
• no (not now)
• block (this person)

[/fancy-ul] 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?op=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)

 

Step 1: Initialise quick locate

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

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)

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)

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:

[fancy-ul variation=”blue” style=”arrow”]

• 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).

[/fancy-ul]

 

4.Normal locate process (overview)

Step 1: Register a new user

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

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)

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)

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)

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)

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:
[fancy-ul variation=”blue” style=”arrow”]

• 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).

[/fancy-ul]

 

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:
[fancy-ul variation=”blue” style=”arrow”]

• DeleteContact
• EditContact
• EditUser
• SMSUserPassword

[/fancy-ul] DeleteContact (int ClientID, string ClientPassword, int ContactID)

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)

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.

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)

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)

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

(in this case, the authenticationCode, using UserPassword = 99999, will be zxeEaq75JRaCna7ipU6Hv3qdoys= )

Notes:
[fancy-ul variation=”blue” style=”arrow”]

• 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.

[/fancy-ul] e.g. https://www.locateaphone.co.za/service.asmx/SuperLocate?UserID=12& locateeMSISDN=27829876543&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: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)

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)

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)

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}