PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store
Related Articles

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):

Listing 2 The XML response when looking up the White House (listing-2.xml)
<?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>

Within the 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 Placemark element 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 Accuracy are:

  • 0: Unknown
  • 1: Country
  • 2: Region
  • 3: Sub-region
  • 4: Town
  • 5: Postcode
  • 6: Street
  • 7: Intersection
  • 8: Address

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 1).

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).

In This Article


Additional Files