Geocoding with PHP and the Google Maps API
Understanding the Geocoder Response
After you send the geocoder request, you will receive a response back in the format you specified. For example, if we request the address of the White House (using the URL
http://maps.google.com/maps/geo?q=1600+pennsylvania+ave+washington+dc&output=xml&key=123456), we will receive the following response XML (note that I have indented it to make it more easily readable):
<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://earth.google.com/kml/2.0"> <Response> <name>1600 pennsylvania ave washington dc</name> <Status> <code>200</code> <request>geocode</request> </Status> <Placemark id="p1"> <address>1600 Pennsylvania Ave NW, Washington, DC 20006, USA</address> <AddressDetails Accuracy="8" xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"> <Country> <CountryNameCode>US</CountryNameCode> <AdministrativeArea><AdministrativeAreaName>DC</AdministrativeAreaName> <SubAdministrativeArea> <SubAdministrativeAreaName>District of Columbia</SubAdministrativeAreaName> <Locality> <LocalityName>Washington</LocalityName> <Thoroughfare> <ThoroughfareName>1600 Pennsylvania Ave NW</ThoroughfareName> </Thoroughfare> <PostalCode> <PostalCodeNumber>20006</PostalCodeNumber> </PostalCode> </Locality> </SubAdministrativeArea> </AdministrativeArea> </Country> </AddressDetails> <Point> <coordinates>-77.036655,38.898774,0</coordinates> </Point> </Placemark> </Response> </kml>
Response tag, there are three key elements:
name: This is the search query sent to the geocoder
Status: This includes the response code of the request, which is a simple way to determine what actually happened when the request was performed. The possible response codes are as follows:
200: Successful request (at least one placemark was returned).
400: Bad request (the server was unable to understand the request).
500: Server error (an unknown internal error occurred).
601: Missing query. This means the q parameter was not specified (or was an empty string).
602: Unknown address. This means that the request was performed but no placemarks were found.
603: Unavailable address. The given address could not be returned due to legal or contractual reasons.
610: An invalid Google Maps API key was specified.
620: Too many queries have been performed using the given API key.
Placemark: Assuming that the status code was
200, there will be at least one
Placemarkelement in the returned XML. This element contains all the geocoder information for the given address or location.
Once we have a valid response, we can loop over each placemark and save the data accordingly.
The first useful item of information included in each placemark is a formatted address. This is extremely useful since the data is much more consistent and means you don't need to rely on user-submitted data. If you look at the above example, we submitted
1600 pennsylvania ave washington dc as the request string and received
1600 Pennsylvania Ave NW, Washington, DC 20006, USA as the formatted address.
Next is the
AddressDetails element, which uses the Extensible Address Language (xAL). This element has an attribute called
Accuracy, which specifies the accuracy level of the returned placemark. The possible values for
In our example the accuracy level is
8, meaning it is the highest level of accuracy. With the code we develop in this article you will be able to test the different accuracy levels (for example, entering
Australia as the query term will return an accuracy of
The other elements within
AddressDetails break down each part of the complete address into their corresponding categories, marked-up according to the xAL specification.
Finally, each placemark contains a Point element. This element contains a comma-separated string where the first value is the longitude; the second value is the latitude; and the third value is the elevation (typically not used). Thus in our example the longitude is
77.036655 and the latitude is
38.898774. This precision (that is, six decimal points) is accurate to 4 inches (11 centimeters).