Definitive reference for Google Maps Placemark object

Question

I am using the following method to reverse geocode a google maps latlng:

[GClientGeocoder.getLocations(address:String, callback:function)][1]

Which states as follows:

As this method requires a call to a Google server, you must also pass a callback method to handle the response. This response will contain a Status code, and if successful, one or more Placemark objects.

Can anyone point me to a definitive reference of what a Placemark object is as it seems to return different attributes for different locations. e.g. sometimes I get a ThoroughfareName and others an AddressLine. I would like to understand if I will always get one or other of them and whether they are interchangeable.

Answer 1

You have to hunt for it, but Google does in fact have some documentation about Placemarks hidden away.

Answer 2

The contents of the Placemark object do vary based on the data available. I found the best way to work out what I was getting back was to use JSON.stringify to examine the response (for debugging):

function onGeocode (resp)
{
    document.getElementById("cd_output").innerHTML = JSON.stringify (resp);
}

This gave me the following results when I GeoCoded an address in Sydney, Australia:

Placemark
{
    id, address, 
    AddressDetails
    {
        Country, CountryNameCode, CountryName, 
        AdministrativeArea
        {
            AdministrativeAreaName, 
            Locality
            {
                LocalityName
                Thoroughfare { ThoroughfareName }
                PostalCode { PostalCodeNumber }
            }
        }
    }
    Accuracy,
    ExtendedData
    {
        LatLonBox { north,south,east,west }
        Point { coordinates }
    }
}

Answer 3

This page is from the Google Maps API documentation, and contains a pretty straightforward explanation of what a Placemark object is.

However, the part you probably want to focus on is where it states what format Google uses for the AddressDetails object in a Placemark, which is xAL (eXtensible Address Language). There is a link to the spec there, which leads to a downloadable schema (xsd file), which essentially defines the entire format. A word of warning: the spec is pretty extensive, but you may not need to worry about a great deal of it for your project.

EDIT:
Apologies for not being allowed to add links to the relevant pages for you.