Skip to content

Searches for places within a specified area. You can refine the results by providing a keyword or specifying a place type.

Endpoint

https://maps.track-asia.com/api/v2/place/nearbysearch/{outputFormat}

Output Format

outputFormat Description
json (recommended) JSON format
xml XML format

Parameters

Parameter Value Require Description Example
location String ✔ The latitude and longitude of the center of the search radius, specified as {latitude},{longitude}. Example: 10.76865,106.6681899 (latitude: 10.76865, longitude: 106.6681899) 10.76865,106.6681899
radius Number ✔ Defines the distance (in meters) within which to return place results. Example: 100 = 100 meters. The maximum radius is 50,000 meters (50km). Results outside the defined radius may be displayed depending on the area's density. 100
key String ✔ Your API key (use your own key; public_key is limited and for testing only). public_key
type String Restricts the results to places of the specified type. Multiple types can be specified by separating them with a pipe symbol (e.g., hospital|pharmacy). hospital|pharmacy
new_admin true , false (default) Return address according to new administrative boundaries true
include_old_admin Boolean Return both the old and new addresses (only available when new_admin=true) true

Code Examples

This example demonstrates how to request data in JSON format:

https://maps.track-asia.com/api/v2/place/nearbysearch/json?location=10.76865,106.6681899&radius=100&key=public_key&new_admin=true

This example demonstrates how to request data in JSON format:

https://maps.track-asia.com/api/v2/place/nearbysearch/xml?location=10.76865,106.6681899&type=hospital|pharmacy&radius=100&key=public_key&new_admin=true&include_old_admin=true

# JSON
curl -G "https://maps.track-asia.com/api/v2/place/nearbysearch/json" \
--data-urlencode "location=10.76865,106.6681899" \
--data-urlencode "type=`hospital|pharmacy`" \
--data-urlencode "radius=100" \
--data-urlencode "key=public_key" \
--data-urlencode "new_admin=true" \
--data-urlencode "include_old_admin=true"

# XML
curl -G "https://maps.track-asia.com/api/v2/place/nearbysearch/xml" \
--data-urlencode "location=10.76865,106.6681899" \
--data-urlencode "type=`hospital|pharmacy`" \
--data-urlencode "radius=100" \
--data-urlencode "key=public_key" \
--data-urlencode "new_admin=true" \

// JSON
const response = await fetch("https://maps.track-asia.com/api/v2/place/nearbysearch/json?location=10.76865,106.6681899&radius=100&key=public_key&new_admin=true")
const data = await response.json()
console.log(data)

// XML
const responseXML = await fetch("https://maps.track-asia.com/api/v2/place/nearbysearch/xml?location=10.76865,106.6681899&type=hospital|pharmacy&radius=100&key=public_key&new_admin=true&include_old_admin=true")
const dataXML = await responseXML.text()
console.log(dataXML)

Response

JSON Response

The response is a JSON object with the following structure:

  • status: String status (e.g., "OK")
  • html_attributions: Array of HTML attribution strings
  • results: Array of result objects. Each object includes:
    • place_id: Unique identifier for the place
    • official_id: The official administrative code from the National Administrative Catalogue. This field is only returned when the result is an administrative unit (e.g., ward, city/province)
    • name: The name of the place
    • formatted_address: The standardized, human-readable address of the place
    • adr_address: Address string with HTML tags for display
    • address_components: Array of objects with:
      • long_name: The full text description or name
      • short_name: An abbreviated textual name for the address component
      • official_id: The official administrative code from the National Administrative Catalogue. This field is only returned when the result is an administrative unit (e.g., ward, city/province)
      • types: Array of types for the address component
    • geometry: Object with:
      • location: The latitude and longitude coordinates (lat/lng)
      • location_type: The type of location returned
      • viewport: The preferred viewport when displaying the result (northeast/southwest)
    • plus_code: Object with:
      • compound_code: A compound code
      • global_code: A global code
    • types: Array of feature types describing the given result
    • icon: The name of the icon
    • icon_background_color: The background color for the icon
    • url: (Optional) Link to the place detail page
    • utc_offset: (Optional) Local timezone offset (minutes)
    • vicinity: (Optional) Nearest address or area description
    • old_address_components: (Only present when include_old_admin=true) Array of address components according to the old boundaries, same structure as address_components.
    • old_formatted_address: (Only present when include_old_admin=true) Full formatted address according to the old boundaries.
XML Response

The XML response has a similar structure; fields will be corresponding XML tags to the JSON fields above. Some differences:

  • The XML results are wrapped in a <PlaceSearchResponse> root element
  • Arrays in JSON (like results, address_components, types) will be repeating elements in XML
  • Empty fields are represented by empty arrays in JSON but will have no elements in XML

Important Notes

Status

Status Description
OK indicates that no errors occurred; the search was successful and at least one result was returned.
ZERO_RESULTS indicates that the search was successful but returned no results. This may occur if no places are found within the search radius.
INVALID_REQUEST indicates that the API request was malformed (e.g., missing required parameters, invalid parameter values).

Error

When the API returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the given status code.

Next steps