The Geolocation API provides HTTP-based remote access for determining device location by uploading Wi-Fi and cellular base station information. The service returns latitude, longitude, and other location details.
Before You Begin
Apply for a
【Web Service API】 Key
Enable overseas access for the applied Key by submitting a ticket to request the required permissions
Construct the HTTP request URL, including the Key obtained in Step 1 as a required parameter
Receive and parse the data returned from the HTTP request (in JSON or XML format)
Unless otherwise specified, all input parameters and output data are encoded in
UTF-8.
Geolocation
Geolocation API Service URL
URL | Request Method |
http://sg-apilocate.opnavi.com/position?parameters | GET |
The parameters represent both required and optional parameters. All parameters are separated by the ampersand character (&). The list below enumerates these parameters and their usage rules.
Request Parameters
Name | Meaning | Rule Description | Required | Default |
key | Service authorization token | Apply for a Web Service API Key and submit a work order for overseas permissions on the Amap official website. | Yes | None |
accesstype | Mobile network access method | 0: mobile network; 1: Wi-Fi network | Yes | None |
imei | Phone IMEI number | Improves positioning accuracy and precision. Used for tracking and troubleshooting when positioning fails. Without it, issues cannot be investigated. | Yes | None |
idfa | iOS device IDFA | Improves positioning accuracy and precision. Used for tracking and troubleshooting when positioning fails. Without it, issues cannot be investigated. | One of imei or idfa is required | None |
smac | Phone MAC address | Improves positioning accuracy and precision. Used for tracking and troubleshooting when positioning fails. Without it, issues cannot be investigated. | No (recommended) | None |
serverip | Gateway IP corresponding to the device accessing the base station | Improves positioning accuracy and precision. Used for tracking and troubleshooting when positioning fails. Without it, issues cannot be investigated. | No (recommended) | None |
cdma | Whether the network is CDMA | 0: not CDMA; 1: CDMA | Required when accesstype=0 | 0 |
imsi | Mobile subscriber identification number | Improves positioning accuracy and precision. Used for tracking and troubleshooting when positioning fails. Without it, issues cannot be investigated. | No (recommended) | None |
network | Wireless network type | GSM, GPRS, EDGE, HSUPA, HSDPA, WCDMA | Required when accesstype=0 | - |
tel | Mobile phone number | - | No | None |
bts | Access base station information | See Table 1-2 for internal parameter description. Non-CDMA format: mcc,mnc,lac,cellid,signal CDMA format: sid,nid,bid,lon,lat,signal (lon and lat can be empty, e.g. sid,nid,bid,,,signal) | Required when accesstype=0 | None |
nearbts | Surrounding base station information (excluding access base station) | Format: base_station_info_1|base_station_info_2|base_station_info_3|... | No | None |
mmac | MAC information of the connected hotspot | Format: mac,signal,ssid Example: f0:7d:68:9e:7d:18,-41,TPLink | No (strongly recommended) | None |
macs | MAC information from the Wi-Fi list | Each entry uses the same format as mmac. Entries are separated by |. At least 2 entries are required; maximum 30 for normal positioning. Do not include mobile hotspot Wi-Fi information. | Required when accesstype=1 | None |
output | Response data format | Optional values: json, xml | No | json |
Name | Meaning | Rule Description | Required | Default |
mcc | Mobile country code | Default value is 460 (China). | Required when cdma=0 | 460 |
mnc | Mobile network code | China Mobile: 0; China Unicom: 1 | Required when cdma=0 | - |
lac | Location area code | Range: 0–65535 | Required when cdma=0 | - |
cellid | Base station cell ID | Range: 0–65535 or 0–268435455. Values 0, 65535, and 268435455 are not used. A cell ID greater than 65535 indicates a 3G base station. | Required when cdma=0 | - |
signal | Signal strength | Range: 0 to -113 dBm. If the obtained signal strength is positive, convert using the formula: positive_value * 2 – 113. | Required when cdma=0 | - |
sid | CDMA system identification code | - | Required when cdma=1 | - |
nid | CDMA network identifier | - | Required when cdma=1 | - |
bid | CDMA cell unique identifier | - | Required when cdma=1 | - |
lon | CDMA longitude value | Read from the mobile platform interface. | No | - |
lat | CDMA latitude value | Read from the mobile platform interface. | No | - |
mac | MAC address | Example: 00:0f:e2:4e:aa:3e | Required when accesstype=1 | - |
ssid | Wireless network name | - | Required when accesstype=1 | - |
Important: To ensure the most accurate positioning results, in addition to the required parameters, always include any other parameters that are available. For example, when using Wi-Fi access, you can also pass in the corresponding base station information. When using mobile network access, you can also pass in the MAC information (macs) from the Wi-Fi list.
Examples
The following examples demonstrate the three positioning scenarios based on the network access method.
Wi-Fi Access (accesstype=1)
http://sg-apilocate.opnavi.com/position?accesstype=1&imei=352315052834187&smac=E0:DB:55:
E4:C7:49&mmac=50:a7:2b:1e:56:58,-60,alibaba-inc&macs=4c:48:da:25:0b:11,-59,alibaba-inc|4c:4
8:da:25:1a:11,-77,alibaba-inc&serverip=10.2.166.4&key=<your key>
Mobile Network Access – Non-CDMA (accesstype=0, cdma=0)
https://sg-apilocate.opnavi.com/position?cdma=0&imsi=&accesstype=0&network=GPRS&bts=460%2C0%2C37335%2C545%2Cnull&platform=rest&key=<your key>
Mobile Network Access – CDMA (accesstype=0, cdma=1)
http://sg-apilocate.opnavi.com/position?accesstype=0&imei=352315052834187&smac=E0:DB:55:E4:C7:49&cdma=1&bts=13824,1,1838,1674723,575739,-52&serverip=10.2.166.4&output=xml&key=<your key>
Response Parameters Description
Name | Description | Specification |
status | Response status | 0: failure; 1: success |
info | Status description | When status is 0, info contains the error reason. Otherwise, returns 'OK'. |
result | Positioning result list | Contains child elements listed below. |
| type | Positioning type | 0: no positioning result obtained; other values: normal positioning result obtained. |
imei | Phone IMEI number | - |
location | Positioning coordinates (latitude and longitude) | - |
radius | Positioning accuracy radius (in meters) | - |
desc | Location description | - |
country | Country | Optional return field. |
province | Province | Optional return field. |
city | City | Optional return field. |
citycode | City code | Optional return field. |
adcode | Area code | Optional return field. |
road | Road name | Optional return field. |
poi | Nearby POI name | Optional return field. |
