Geolocation API¶

Introduction ¶

The Geolocation API returns a location on the basis of cell tower information that any mobile client can detect. Any mobile user will send the information of all the connected or recently connected cell towers information in the API, Now API will articulate approximate user location on the basis of the provided cell towers information. MMI will use its cell towers geo-location database to calculate the approximate geo-location of the user.

Getting Access¶

Before using the API in the your solution, please ensure that the related access is enabled in the Mappls Console, within your app - be it for Mobile OR Web or Cloud integration.

Copy and paste the key from your credentials section from your API keys into the access_token query parameter.
- Your static key can be secured by whitelisting its usage for particular IPs (in case of cloud app usage) OR a set of domains (in case of a web app)
- Your static key obtained from your Console is to be passed as a query parameter: access_token.

Authentication Object - `access_token` mandatory query parameter.¶

access_token: "hklmgbwzrxncdyavtsuojqpiefrbhqplnm".

Input URL ¶

https://search.mappls.com/search/places/geo-location

Method ¶

POST

Request Type ¶

Content-Type: application/json

Response Type ¶

Content-Type: application/json

Request Parameters ¶

Part of Body

For 2G Connections¶

cellTowers (array of objects) : An array of cell tower objects. The following are the parameters are required in Cell Tower Objects:
- cellId (number) : Unique identifier of the cell. Required for radioType gsm (default), cdma, wcdma and lte.
- locationAreaCode (number) : The Location Area Code (LAC) for GSM and WCDMA networks.
- mobileCountryCode (number) : The cell tower's Mobile Country Code (MCC).Valid range: 0–999.
- mobileNetworkCode (number) : The cell tower's Mobile Network Code. This is the MNC for GSM, WCDMA, LTE and NR. Valid range for MNC: 0-999 and for SID: 0-32767

For 4G & 5G Connections¶

There is an additional request property that you have to send:

radioType (string): a string indicating whether the radio type for the connection is 4G or 5G. Can take in the following values:
lte - indicating that the radio of 4G connection type.
NR - indicating that the radio of 5G connection type.

Only in case of when radioType is NR, cellId variable changes to newRadioCellId.

Note: 1. A minimum of one cell tower object is required and a maximum of six cell tower objects are allowed as input. 2. To get the best result, a minimum of three cell tower objects should be input > in accordance with one active and two latest historical cell info objects

Response Parameters ¶

location(object): The estimated geolocation i.e. latitude and longitude, in degrees. Contains the following parameters:
- lon (number): longitude of the estimated location.
- lat (number): latitude of the estimated location.
accuracy(object): The estimated accuracy in meters of the provided location.
- nearest(integer): accuracy as per closest triangulation. 0 indicates unable to determine accuracy.

Sample cURL Request ¶

2G Connections¶

curl --location 'https://search.mappls.com/search/places/geo-location?access_token=hklmgbwzrxncdyavtsuojqpiefrbhqplnm' \
--header 'Content-Type: application/json' \
--data '{
    "radioType": "gsm",
    "cellTowers": [
        {
            "cellId": 900372,
            "locationAreaCode": 57,
            "mobileCountryCode": 405,
            "mobileNetworkCode": 872
        }
    ]
}'

4G Connections¶

curl --location 'https://search.mappls.com/search/places/geo-location?access_token=hklmgbwzrxncdyavtsuojqpiefrbhqplnm' \
--header 'Content-Type: application/json' \
--data '{
    "radioType": "lte",
    "cellTowers": [
        {
            "cellId": 900372,
            "locationAreaCode": 57,
            "mobileCountryCode": 405,
            "mobileNetworkCode": 872
        }
    ]
}'

5G Connections¶

curl --location 'https://search.mappls.com/search/places/geo-location?access_token=hklmgbwzrxncdyavtsuojqpiefrbhqplnm' \
--header 'Content-Type: application/json' \
--data '{
    "radioType": "NR",
    "cellTowers": [
        {
            "newRadioCellId": 900372,
            "locationAreaCode": 57,
            "mobileCountryCode": 405,
            "mobileNetworkCode": 872
        }
    ]
}'

Sample Response ¶

{
    "accuracy": {
        "nearest": 0
    },
    "location": {
        "lon": 77.268947,
        "lat": 28.550847
    }
}

Response Codes {as HTTP response codes}¶

Success ¶

200: To denote a successful API call.
204: To denote the API was a success but no results were found.

Client-Side Issues ¶

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

Server-Side Issues ¶

500: Internal Server Error, the request caused an error in our systems.
503: Service Unavailable, during our maintenance break or server downtimes.

Response Messages (as HTTP response messages)¶

200: Success.
201: Created.
204: No matches were found for the provided query.
400: Something’s just not right with the request.
401: Access Denied.
403: Services for this key has been suspended due to daily/hourly transactions limit.
500: Something went wrong.
503: Maintenance Break.
410 : Deleted
422 : Unprocessable entity
412 : Precondition Failed
428 : Precondition Required.