The Geocoding API is a service that provides geocoding and reverse geocoding of addresses. Geocoding converts addresses (such as a street address) into geographic coordinates (latitude and longitude), which you can use to place markers on a map or position the map. Reverse geocoding converts geographic coordinates into a human-readable address.
Coordinate Parameters: All spatial data fields (inputs and 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 models. While granular-to-macro sequencing remains consistent (e.g., premise → country), implementation specifics vary according to ISO 19160-1:2015 localization protocols.
ImportantDomestic 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.
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.
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
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 official website. | Mandatory | None |
address | Structured Address Data | When inputting structured addresses, 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. - If there is no corresponding adcode for a region, use the country-specific adcode as a substitute. For example, for the United States, use "840000000". - If there is no country-specific adcode, 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 |
|
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
Name | Description | Specification |
status | Result Status Value | 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 are returned in info. Otherwise, "OK" is returned. For details, refer to the info 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 | 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 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
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 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, nearby POIs that meet the specified requirements are also returned (only when extensions is all). Setting the POI type parameter specifies the requirements for the operation. Only POI TYPECODE can be passed as a parameter. Multiple POI TYPECODE values can be passed, separated by `"\ | "`. To obtain POI TYPECODE, refer to the POI classification code table. | Optional |
radius | Search Radius | The radius parameter range is 0 to 3000. Unit: meters. | Optional | 1000 |
extensions | Control of Return Results | By default, this parameter 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 values: 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 |
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 | 0: Request failed; 1: Request succeeded |
info | Return Status Description | When status is 0, specific error reasons are returned in info. Otherwise, "OK" is returned. For details, refer to the info 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 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 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 |
|
NoteSome return values are returned as string type when they exist; when they do not exist, they are returned as array type.
