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, in the same project you set up for the Maps SDK.

Copy and paste the generated access token from your API keys available in the dashboard in the sample code for interactive map development.
- This APIs follow OAuth2 based security.
- Access Token can be generated using Token Generation API.
- To know more on how to create your access tokens, please use our authorization API URL. More details available here
- The access token is a valid by default for 24 hours from the time of generation. This can be configured by you in the API console.
Security Type

This APIs follow OAuth2 based security. To know more on how to create your authorization tokens, please use our authorization token URL. More details available here

Input URL ¶

https://atlas.mappls.com/api/places/geo-location

Method ¶

POST

Request Type ¶

Content-Type: application/json

Response Type ¶

Content-Type: application/json

Request Parameters ¶

Part of Body

a. Mandatory Parameters ¶

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.

Sample cURL Request ¶

2G Connections¶

curl --location --request POST 'https://atlas.mapmyindia.com/api/places/geo-location' \
--header 'Authorization: Bearer 0XXXXXXf-dXX0-4XX0-8XXa-eXXXXXXXXXX6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "radioType": "gsm",
    "cellTowers": [
        {
            "cellId": 900372,
            "locationAreaCode": 57,
            "mobileCountryCode": 405,
            "mobileNetworkCode": 872
        }
    ]
}'

4G Connections¶

curl --location --request POST 'https://atlas.mapmyindia.com/api/places/geo-location' \
--header 'Authorization: Bearer 0XXXXXXf-dXX0-4XX0-8XXa-eXXXXXXXXXX6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "radioType": "lte",
    "cellTowers": [
        {
            "cellId": 900372,
            "locationAreaCode": 57,
            "mobileCountryCode": 405,
            "mobileNetworkCode": 872
        }
    ]
}'

5G Connections¶

curl --location --request POST 'https://atlas.mapmyindia.com/api/places/geo-location' \
--header 'Authorization: Bearer 0XXXXXXf-dXX0-4XX0-8XXa-eXXXXXXXXXX6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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.