Skip to content

Find places or addresses near a longitude/latitude pair

Endpoint

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

outputFormat

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

Parameters

Parameter Values Require Description Example
latlng {latitude},{longitude} ✔ The latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address. 10.7952219,106.7217912
key String ✔ API key (use your own key; public_key is limited and for testing only) public_key
radius Number The search radius in meters (m) 500, 100, 50, etc.
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 code

This example demonstrates how to request data in JSON format:

https://maps.track-asia.com/api/v2/geocode/json?latlng=10.7952219,106.7217912&key=public_key&new_admin=true&include_old_admin=true

This example demonstrates how to request data in XML format:

https://maps.track-asia.com/api/v2/geocode/xml?latlng=10.7952219,106.7217912&key=public_key&new_admin

# JSON
curl -G "https://maps.track-asia.com/api/v2/geocode/json?" \
  --data-urlencode "latlng=10.7952219,106.7217912" \
  --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/geocode/xml?" \
  --data-urlencode "latlng=10.7952219,106.7217912" \
  --data-urlencode "key=public_key" \
  --data-urlencode "new_admin=true" \

 // JSON
const response = await fetch("https://maps.track-asia.com/api/v2/geocode/json?latlng=10.7952219,106.7217912&key=public_key&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/geocode/xml?latlng=10.7952219,106.7217912&key=public_key&new_admin")
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: An array of result objects. Each result contains:
    • 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.
    • types: Array of place types (e.g., "point_of_interest", "establishment"). Used to categorize the location.
    • sublabel: Additional address or context for the place.
    • formatted_address: Full formatted address.
    • address_components: Array of objects with:
      • long_name: Full text description or name
      • short_name: Abbreviated name
      • types: Array of types 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)
    • geometry: Object with location (lat/lng), location_type, and viewport (northeast/southwest bounds).
    • plus_code: Object with compound_code and global_code (may be repeated inside results).
    • partial_match: Boolean indicating if the result is a partial match.
    • icon, icon_background_color, class, subclass: Visual and classification info.
    • types: Array of place types.
    • navigation_points: Array of navigation points, each with location containing latitude and longitude. (new)
    • 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, old_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 that no errors occurred; the address was successfully parsed and at least one geocode was returned.
ZERO_RESULTS indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.

Error messages

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

Next steps