The Places API enables structured and fuzzy text-based queries to retrieve location data with geographic context adaptation. You can enter free-form search patterns—such as "pizza in New York", "shoe stores near Ottawa", or "123 Main Street"—and receive ranked results based on textual relevance and configured geospatial preferences.
PromptThe international Search API shares the same interface as the domestic Search API. For international use, all coordinates (both input parameters and return values) default to the WGS84 coordinate system. The international Web Service API is a premium service. To request access, submit a business consultation through the official support ticket system.
Application
Keyword Search: Retrieve detailed information about a set of locations based on a specific search term and a defined geographical area.
Nearby Search:Find locations within a specified region, with the option to filter results by place type.
Polygon Search: Search for relevant location information within a custom-defined polygonal area using specific search keywords.
ID Search: Obtain location information based on Point of Interest (POI) IDs.
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.
Keyword search
Keyword search API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/place/text?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. | Yes | None |
keywords | Search keywords | At least one of keywords and types must be provided. | Conditional | None |
types | Search POI type | At least one of keywords and types must be provided. You can use classification codes or Chinese characters (see the attached document for Chinese character options). Separate multiple types with a vertical bar (|).
The classification code is a six-digit number: the first two digits represent the major category, the middle two digits represent the medium category, and the last two digits represent the minor category. Specifying a major category includes all medium and minor categories under it.
Example: 010000 = automobile services (major) 010100 = gas stations (medium) 010101 = Sinopec (minor) 010900 = car rental (medium) 010901 = car return locations for rental (minor)
When specifying 010000, medium categories like 010100 and minor categories like 010101 are included. When specifying 010900, minor categories like 010901 are included.
**Note:** The returned results may include medium and minor category POIs, but not all. For more precise results, input minor categories or narrow the search scope. See POI classification codes. | Conditional | None |
city | Search city and administrative division | For overseas searches, this field is mandatory. Use the city code or administrative division code (adcode).
To obtain the adcode: Download the adcode table by country.
**Note:** If no corresponding administrative division adcode exists, use the country's adcode (e.g., USA: 840000000). If no corresponding country adcode exists, enter 000000000. You can also obtain the adcode via the reverse geocoding interface. | Conditional |
|
page | Current page number | — | Optional | 1 |
offset | Records per page | Range: 0–50. | Optional | 20 |
langCode | Return result language | Default is zh (Chinese). Supported 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 |
extensions | Result control | By default, only basic address information is returned. To include nearby POIs, roads, and road intersections, set this parameter to all. | Optional | base |
sig | Digital signature | See methods for obtaining and using digital signatures. | Optional | None |
callback | Callback function | The callback value is a user-defined function name. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/place/text?keywords=food&city=840380000&offset=20&types=Museum&key=<your key>
Response Parameters Description
Name | Description | Specification |
status | Result status | 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. See the info status table for details. |
infocode | Return status code | See the info status table for details. |
count | Number of returned results | The total number of results returned. |
pois | Search POI information list | Child element. |
| pois | POI information | Child element. |
| id | Unique ID | Overseas POI IDs start with P. PO represents ordinary POIs, while PS/PV represent public transit POIs. Example: P0JAK55X50. |
name | Name | — |
type | POI type | Categorized into 1–5 levels. Example: food; Latin American Restaurant; South American Restaurant; Brazilian Restaurant; Acai House. |
typecode | POI type code | — |
biz_type | Industry type | — |
address | Address | — |
location | Latitude and longitude | Format: longitude,latitude. |
tel | Phone number of the POI | — |
pcode | Province code of the POI | Returned when extensions=all. |
pname | Province name of the POI | **Note:** Due to differences in administrative divisions between overseas and domestic areas, it is currently not possible to strictly follow province, city, and district divisions. |
citycode | City code of the POI | Returned when extensions=all. |
cityname | City name of the POI | **Note:** Due to differences in administrative divisions between overseas and domestic areas, it is currently not possible to strictly follow province, city, and district divisions. |
adcode | District code | Returned when extensions=all. |
adname | District name | **Note:** Due to differences in administrative divisions between overseas and domestic areas, it is currently not possible to strictly follow province, city, and district divisions. |
gridcode | Geographic grid ID | Returned when extensions=all. |
distance | Distance from center point | Unit: meters. This value is only returned during nearby search. |
Nearby search
Nearby search API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/place/around?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. | Yes | None |
location | Center point coordinates | Format: longitude,latitude. Decimal places should not exceed 6 digits. Enter the longitude and latitude for overseas locations. | Yes | None |
keywords | Search keywords | At least one of keywords and types must be provided. | Conditional | None |
types | Search POI type | Same rules as the Keyword Search types parameter. See the Keyword Search section for details. | Conditional | None |
radius | Search radius | Value range: 0–50000. Unit: meters. | Optional | 3000 |
page | Current page number | — | Optional | 1 |
offset | Records per page | Range: 0–50. | Optional | 20 |
langCode | Return result language | Same options as the Keyword Search langCode parameter. | Optional | None |
extensions | Result control | By default, only basic address information is returned. To include nearby POIs, roads, and road intersections, set this parameter to all. | Optional | base |
sig | Digital signature | See methods for obtaining and using digital signatures. | Optional | None |
callback | Callback function | The callback value is a user-defined function name. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/place/around?key=<your key>&keywords=food&location=103.861974,1.304754&offset=20&page=1
Response Parameters Description
The response parameters for Nearby Search are the same as those for Keyword Search.
Polygon search
Polygon search API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/place/polygon?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. | Yes | None |
polygon | Latitude and longitude coordinate pairs | Format: longitude,latitude. Separate coordinate pairs with |. Decimal places should not exceed 6 digits.
**Note:** 1. For rectangular polygons, you can input the coordinates of the top-left and bottom-right vertices. In other cases, the first and last coordinate pairs must be the same. 2. If any coordinate pair falls within China, domestic POI data will be returned. | Yes | None |
keywords | Search keywords | At least one of keywords and types must be provided. | Conditional | None |
types | Search POI type | Same rules as the Keyword Search types parameter. See the Keyword Search section for details. | Conditional | None |
page | Current page number | — | Optional | 1 |
offset | Records per page | Range: 0–50. | Optional | 20 |
langCode | Return result language | Same options as the Keyword Search langCode parameter. | Optional | None |
extensions | Result control | By default, only basic address information is returned. To include nearby POIs, roads, and road intersections, set this parameter to all. | Optional | base |
sig | Digital signature | See methods for obtaining and using digital signatures. | Optional | None |
callback | Callback function | The callback value is a user-defined function name. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/place/polygon?polygon=-73.509092,40.793609|-73.487738,40.769018|-73.446643,40.768289|-73.424987,40.793844&keywords=food&key=<your key>
Response Parameters Description
The response parameters for Polygon Search are the same as those for Keyword Search.
ID search
ID search API Service URL
URL | Request Method |
https://sg-restapi.opnavi.com/v3/place/detail?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. | Yes | None |
id | POI ID | Unique identifier for the POI.
**Note:** Overseas POI IDs start with P. PO represents ordinary POIs, while PS/PV represent public transit POIs. Example: P0JAK55X50. | Yes | None |
langCode | Return result language | Same options as the Keyword Search langCode parameter. | Optional | None |
sig | Digital signature | See methods for obtaining and using digital signatures. | Optional | None |
callback | Callback function | The callback value is a user-defined function name. | Optional | None |
Examples
https://sg-restapi.opnavi.com/v3/place/detail?id=P0JAK55X50&key=<your key>
Response Parameters Description
The response parameters for ID Search are the same as those for Keyword Search.
