Skip to content

Searches for keywords and returns a list of relevant places. API search is commonly used when the input is a full address.

Endpoint

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

outputFormat

outputFormat Description
json (recommended) indicates output in JavaScript Object Notation (JSON)
xml indicates output in XML

Parameters

Parameter Values Require Short Description Example
query String ✔ It is recommended to use a full address for the most accurate results; you can also use a specific place name or place category. Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City
key String ✔ API key (use your own key; public_key is limited and for testing only) public_key
radius Number Search radius (meters) to limit the result area 5000
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

Example Usage

Tham số query: Landmark 81, 720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh

Output: 21.0137443130001,105.798346108

Example 1: Return both new and old addresses 

https://maps.track-asia.com/api/v2/place/textsearch/json?key=public_key&query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City&new_admin=true&include_old_admin=true

Example 2: Return new administrative address 

https://maps.track-asia.com/api/v2/place/textsearch/xml?key=public_key&query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City&new_admin=true


# JSON
curl -G "https://maps.track-asia.com/api/v2/place/textsearch/json?" \
--data-urlencode "key=public_key" \
--data-urlencode "query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City" \
--data-urlencode "new_admin=true" \
--data-urlencode "include_old_admin=true"

# XML
curl -G "https://maps.track-asia.com/api/v2/place/textsearch/xml?" \
--data-urlencode "key=public_key" \
--data-urlencode "query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City" \
--data-urlencode "new_admin=true"

// JSON
const response = await fetch("https://maps.track-asia.com/api/v2/place/textsearch/json?key=public_key&query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City&new_admin=true&include_old_admin=true")
const data = await response.json()
console.log(data)

 // XML
const response = await fetch("https://maps.track-asia.com/api/v2/place/textsearch/xml?key=public_key&query=Landmark 81, 720A Dien Bien Phu, Thanh My Tay Ward, Ho Chi Minh City&new_admin=true")
const data = await response.text()
console.log(data)

Response

JSON Response

The response is a JSON object with the following structure:

  • plus_code: Object with global_code (and possibly compound_code).
  • status: Status string (e.g., "OK").
  • results: Array of result objects. Each object includes:
    • 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)
    • place_id: Unique identifier for the place.
    • name: Name of the place.
    • formatted_address: Full formatted address.
    • address_components: Array of objects with:
      • long_name: Full name of the address component.
      • short_name: Abbreviated or short name.
      • types: Array of types, e.g., street_number, route, administrative_area_level_1, etc.
    • geometry: Object describing location info, including:
      • location: Geographic coordinates with lat and lng.
      • location_type: Type of location (e.g., "ROOFTOP").
      • viewport: Suggested viewport bounds, with northeast and southwest.
    • plus_code: Object with compound_code and global_code (may repeat in each result).
    • adr_address: Address string with HTML tags (e.g., <span class=\"...\">) for UI formatting.
    • partial_match: Boolean indicating if the result is a partial match.
    • icon: Icon code representing the place type.
    • icon_background_color: Icon background color (HEX code).
    • types: Array of place types, e.g., point_of_interest, establishment, etc.
    • 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, with elements corresponding to the JSON fields above. Notable differences:

  • XML results are wrapped in a root <GeocodeResponse> element.
  • Arrays in JSON (such as results, address_components, types...) become repeated elements in XML.
  • Blank elements are indicated by empty arrays in JSON, but by the absence of such elements in XML.

Important Notes

Status

Status Description
OK Indicates no errors occurred; the address was successfully parsed and at least one geocode was returned.
ZERO_RESULTS Indicates the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.

Error messages

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field provides more detailed information about the reasons behind the given status code. This field is not always returned, and its content is subject to change.

Next steps