1. Introduction

The AfriGIS service known as Locate a Phone provides the ability to determine the approximate position of any mobile device with an active SIM on the Vodacom cellular network in South-Africa.

Due to changes in legislation and requirements from the cellular network, this service is now accessible as the Locate API as part of the AfriGIS range of API’s.

This document serves as an instruction to integrate the modified AfriGIS Locate a Phone service, as an API.

 

2. Locate Process overview

Clients have to modify their existing applications to access the AfriGIS Locate API. The client application then actions the request to locate a specific MSISDN. This request is passed via cloud services, for authentication of use of the API, to the AfriGIS Location Based Service (LBS) Gateway, where records of all requests are stored. The AfriGIS LBS Gateway sends the request to the cellular provider.

This provider needs to communicate with the owner of the MSISDN, via SMS, to request permission to locate that specific MSISDN. The response from the MSISDN is received by the cellular provider and AfriGIS LBS Gateway stores this response. Based on whether consent is given, either the location of the MSISDN is passed to the client application or an error is sent with explanation why location could not be obtained.

3. Integration

AfriGIS is in the process of developing a portal where developers can sign-up for access to AfriGIS API’s. As this portal is not currently accessible to clients, AfriGIS will provide the client with the Postman collection for the API.

 

1.1 Authorisation: Requesting access token

AfriGIS uses the authorisation framework OAuth 2.0 to manage access to API’s. The client will be provided with their ClientID and ClientSecret by the AfriGIS product manager in charge of the client-specific account. Before making a request to the API a generate access token call must be made. This token will be used as authorisation for subsequent calls to follow.

This token lasts for 3600 seconds, which means the developer must request to generate a new token, before the previous token expires, to ensure uninterrupted access.

To generate an access token, use the Auth call in the Postman collection, with the following fields:

 

 

If setting up own authorisation call, use the following information:

Grant_type: client_credentials

Client_ID: “<as provided by AfriGIS product manager>”

Client_secret: “<as provided by AfriGIS product manager>”

Access token URL: https://auth.afrigis.services/oauth2/token

1.2 Locate API

The Locate API serves to return location-based information in the form of latitude and longitude for the specified MSISDN.

Locate call URL: https://afrigis.services/locate-lbs/lbs/locator

If the client requires this latitude and longitude as a street address, they must contact the AfriGIS product manager for their account to discuss the use and implementation of the Geocode API to reverse geocode the coordinates to an address.

 

1.2.1 Request

1.2.1.1 Request fields

AfriGIS product manager will provide the client with a Username and Password.

 

1.2.1.2 Sample request

 

1.2.2 Response

1.2.2.1 Response fields

 

 

1.2.2.2 Sample Response

1.2.3 Error response

1.2.3.1 Permission response not yet obtained

 

1.2.3.2 Unable to locate MSISDN

 

1.2.3.3 Location consent rejected by MSISDN owner

4.   Items for consideration

The following needs to be taken into consideration when using the AfriGIS Location API.

The accuracy of the location returned is dependent on the cellular network coverage in the specific area. Higher accuracy will be achieved in urban areas than in rural.

Once the MSISDN owner has provided consent to be located, that consent remains active until further notice. This is in the process of changing to a scenario where consent has to be obtained for each request to locate. AfriGIS will contact the client as and when the cellular providers require this.

The first time a MSISDN location request is sent, the response will always be the error response “Need to wait for permission to be granted”. This is due to the fact that the MSISDN owner must first provide response to the cellular provider and this needs to be synchronised with the AfriGIS LBS Gateway. The second time the same MSISDN locate request is submitted a location or relevant other error message should be returned.

 

5.   Support contact

Should you, as client, require and further assistance with this integration, please feel free to contact the relevant client manager at AfriGIS on +27 87 310 6400.