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 Description Example
location String (required) 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 (required) 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
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
key String (required) Your API key (use your own key; public_key is limited and for testing only). public_key
new_admin Boolean Return address according to new administrative boundaries true
include_old_admin Boolean (Use with new_admin) Return both new and old addresses 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" \
--data-urlencode "include_old_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
    • 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
      • 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