Convert addresses to geographic coordinates or the reverse.The Geocoding API is a service that provides geocoding and reverse geocoding of addresses.
Coordinate Parameters: All spatial data fields (inputs/outputs) default to WGS84 (EPSG:4326) — the unaltered GPS reference framework recognized as the global geodetic standard
Definition of International Structured AddressStructured geolocation data employs hierarchical decomposition based on regional administrative tiers, with output schemas dynamically adapting to jurisdictional governance models12. While granular-to-macro sequencing remains consistent (e.g., premise → country), implementation specifics vary according to ISO 19160-1:2015 localization protocols.
Promptdomestic and overseas geocoding/reverse geocoding APIs share the same endpoint. The overseas Web Services API is categorized as a premium service requiring prior authorization. For access requests, submit a business consultation through the official support ticket system.
Application
Geocoding: Geocoding is the process of converting addresses (like a street address) into geographic coordinates (like latitude and longitude), which you can use to place markers on a map, or position the map.
Reverse Geocoding: Reverse geocoding is the process of converting geographic coordinates into a human-readable address.
Guidelines
Apply for a
【Web Service API】Key
Enable overseas permissions for the applied Key by submitting a ticket to request overseas 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。
Geocoding
Geocoding API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/geocode/geo?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
Parameter Name | Description | Specification | Mandatory | Default |
key | Service Authorization Token | Applying for a Web Service API Key and Submitting a Work Order for Overseas Permissions on Amap Map Official Website | Mandatory | None |
address | Structured Address Data | When inputting structured addresses, generally, lower-level information should come first, followed by higher-level information. Start with the door number and end with the country: "9, Madison Avenue, Manhattan, New York, New York State, USA". | Mandatory | None |
city | Geolocation Lookup | You can input either a city code (citycode) or an area code (adcode) to obtain an adcode. Methods to Obtain an Adcode: 1、Retrieve adcode from a country-specific code list: Note: ①If there is no corresponding adcode for a region, you can use the country-specific adcode as a substitute. For example, for the United States, use "840000000". ②If there is no country-specific adcode, you can input "000000000" to retrieve the 1st and 2nd administrative region adcode lists. 2、Use the reverse geocoding interface to obtain the adcode. | Conditional: Required for Overseas | Default: Search Nationwide in China |
sig | Digital Signature | Methods for Obtaining and Using Digital Signatures | Optional | None |
callback | Callback Function | The callback value is a function name defined by the user. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/geocode/geo?address=9, Madison Avenue, Manhattan, New York, New York, the United States&city=840000000&key=<your key>
Response Parameters Description
Name | Description | Specification |
status | Result Status Value, Value is 0 or 1 | 0: Request failed; 1: Request succeeded |
count | Number of Returned Results | The number of returned results |
info | Return Status Description | When status is 0, specific error reasons will be returned in info. Otherwise, "OK" will be returned. For details, refer to theinfo status table. |
infocode | Return Status Code | Refer to the info status table for details. |
geocodes | Geocoding Information List | The list of result objects, including the following fields: |
| country | Country Name | The country name (the following administrative levels only represent hierarchy and do not represent specific provinces, cities, townships, or streets). For example: United States of America |
province | Province/State/Fuv | Not necessarily returned. For example: New York |
city | City | Not necessarily returned. For example: New York City |
citycode | City Code |
|
district | District | Not necessarily returned |
street | Street | Not necessarily returned. For example: Flatiron District |
number | Door Number |
|
adcode | Area Code |
|
location | Coordinate Point | Longitude and latitude. For example: -73.98751, 40.741535 The Amap data source returns the central point longitude and latitude of the district. |
Reverse Geocoding
Reverse Geocoding API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/geocode/regeo?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
Parameter Name | Description | Specification | Mandatory | Default |
key | Service Authorization Token | Applying for a Web Service API Key and Submitting a Work Order for Overseas Permissions on Amap Map Official Website | Mandatory | None |
location | Latitude and Longitude Coordinates
| Rule: Longitude first, followed by latitude, separated by a comma. The decimal part of the coordinates should not exceed 6 digits. For example: -73.98751, 40.74129 | Mandatory | None |
poitype | Nearby POI Types | The following content requires the extensions parameter to be set to all to take effect. After reverse geocoding, in addition to returning an address description, it is also possible to return nearby POIs that meet the specified requirements (only when the extensions field value is all). Setting the POI type parameter is equivalent to specifying the requirements for the operation. Only POI TYPECODE can be passed as a parameter, and multiple POI TYPECODE can be passed, separated by "|". To obtain POI TYPECODE, refer to the POI classification code table. | Optional | None |
radius | Search Radius | The radius parameter range is 0 to 3000, with a default value of 1000. Unit: meters. | Optional | 1000 |
extensions | Control of Return Results | By default, this item returns basic address information; if the value is all, it returns address information, nearby POIs, roads, and road intersection information. | Optional | base |
langCode | Return result language | optional: zh（Chinese） en（English） es（Spanish） pt（Portuguese） fr（French） de（German） th（Thai） ja（Japanese） ko（Korean） ar（Arabic） tr（Turkish） he（Hebrew） it（Italian） ru（Russian） ms（Malay） id（Indonesian） vi（Vietnamese） pl（Polish） cs（Czech） uk（Ukrainian） az（Azerbaijani）
| Optional | None |
sig | Digital Signature | Methods to Obtain and Use Digital Signatures | Optional | None |
callback | Callback Function | The callback value is the user-defined function name. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/geocode/regeo?location=-73.98751,40.74129&key=<your key>
Response Parameters Description
Name | Description | Specification |
status | Result Status Value, Value is 0 or 1 | 0: Request failed; 1: Request succeeded |
info | Return Status Description | When status is 0, specific error reasons will be returned in info. Otherwise, "OK" will be returned. For details, refer to theinfo status table. |
regeocode | Reverse geocoding list | Returns a regeocode object; the data contained in the regeocode object is as follows: |
| addressComponent | Address element list |
|
| country | Country name of the coordinate point |
|
province | Name of the Province Where the Coordinate Point is Located |
|
city | Name of the City Where the Coordinate Point is Located |
|
citycode | City Code |
|
district | District of the Coordinate Point |
|
adcode | Administrative Division Code |
|
township | Township/Street where the coordinate point is located (this street is a community street, not a road information) |
|
towncode | Township/Street Code |
|
neighborhood | Community Information List |
|
| name | Community Name |
|
type | POI Type | For example: Science and Education Services; Schools; Higher Education Institutions
|
building | Building Information List |
|
| name | Building Name |
|
type | Type |
|
streetNumber | House Number List |
|
| street | Street name |
|
number | House number |
|
location | Coordinate point | Geographic coordinates: Longitude, Latitude |
direction | Direction | Street orientation of the coordinate point |
distance | Distance from address to requested coordinates | Unit: meters |
seaArea | Maritime information |
|
businessAreas | List of business districts by latitude and longitude |
|
| businessArea | Business District Information |
|
location | Latitude and Longitude of the Business District Center |
|
name | Business District Name |
|
id | Adcode of the Business District Area |
|
| roads | Road Information List | The following content is returned when the request parameter extensions is all |
| road | Road information |
|
| id | Road id |
|
name | Road name |
|
distance | Distance from the road to the requested coordinates | Unit: Meters |
direction | Direction | Relative Position of Input Point to This Road |
location | Coordinate Point |
|
| roadinters | List of Road Intersections | The following content is returned when the request parameter extensions is set to all |
| roadinter | Road intersection |
|
| distance | Distance from the intersection to the requested coordinates | Unit: Meters |
direction | Direction | Direction of the input point relative to the intersection |
location | Intersection latitude and longitude |
|
first_id | First road id |
|
first_name | First road name |
|
second_id | Second road id |
|
second_name | Second road name |
|
| pois | POI information list | The following content is returned when the request parameter extensions is all |
| poi | POI information list |
|
| id | POI ID |
|
name | POI name |
|
type | POI type |
|
tel | Phone |
|
distance | Distance from the center of the POI to the requested coordinates | Unit: Meters |
direction | Direction | Bearing relative to the input point |
address | poi address information |
|
location | coordinate point |
|
businessarea | poi's business district name |
|
aois | aoi information list | The following content is returned when the request parameter extensions is all |
| aoi | AOI information |
|
| id | AOI ID |
|
name | AOI name |
|
adcode | AOI region code |
|
location | AOI center point coordinates |
|
area | Area of the AOI point | Unit: square meters |
distance | Whether the input latitude and longitude are within the AOI | 0 means inside the AOI, other integers represent the distance to the AOI |
type | AOI type |
|
PromptSome return values will be returned as string type when they exist; when they do not exist, they will be returned as array type.
