Classic ASP Class for Yahoo! Placefinder

• Download source code - 2.63 KB

Introduction 

Ever need to make pushpin maps of customers or store locations? Before you even build a map, you need to geocode the address information. Geocoding is the process of converting text address like 123 North Burgundy Street, Chicago, IL into longitude and latitude points that specify the pinpoint on a map grid. For years, this was a costly process involving third party GIS applications, quarterly data updates, and a high degree of IT expertise to keep things running. Thanks to services like Yahoo! Placefinder, you can geocode up to 5,000 addresses each day for free!

Background

Before you get started, you need to apply for an application ID from Yahoo! Placefinder. You can get the AppID here: http://developer.yahoo.com/geo/placefinder/. Paste the app ID you receive from Yahoo! in the Class_Initialize section of the class. The class itself is very simple. The next section shows just how easy it is.

Using the code

Paste the class code below into your application. To call the geocoder, first create an instance of the class, then you make a call to the geocoder.

dim ygeo
dim lon
dim lat 

set ygeo = new YGeoCoder
call ygeo.Geocode( address, city, state, zip )
'' now you can get the longitude and latitude from the object
if ygeo.iserror = false then 
   lon = ygeo.longitude
   lat = ygeo.latitude
end if
'' That's it! 

The following properties are populated from the geocoder results after making a call to Geocode:

• street - The street address passed; it may be corrected by Yahoo! geocoder and expressed in short-hand.
• city - The city found upon geocoding (if only street address and zip are passed to the geocode request).
• state- The state found upon geocoding (if only street address and zip are passed to the geocode request).
• zip - The zip code found (if only street address, city, and state are passed to the geocode request).
• latitude - the latitude portion of the geocoded address.
• longitude - the longitude portion of the geocoded address.
• country - the country of the geocoded address.
• xml - the XML data returned from Yahoo! placefinder.
• reason - if the geocode request fails, this will contain the reason.

The Code

'' YGeoCoder class
'' by Larry Boeldt
'' (C) 2010 Larry Boeldt
'' 
'***************************************************************************
' Copyright 2010 Larry Boeldt 
' Class: YGeoCoder  Version 1.0    11:11 AM Sunday, June 27, 2010
' Author: Larry Boeldt 
' Terms: 
' GPL, commercial license available
'
' Properties(s):
'   
'
' Methods:
'   Geocode( address, city, state, zip )
'
' Description:
' A class that wraps most of the functionality of yahoo geocoder. 
'
' Setup Instructions:
' Get your appid here: <a href="https://developer.apps.yahoo.com/wsregapp/">https://developer.apps.yahoo.com/wsregapp/</a>
' Copy and paste the licence code in the appid="" assignment 
' in class_initialize.
'***************************************************************************
class YGeoCoder
    private appid
    private m_street
    private m_city
    private m_state
    private m_zip
    private m_lon
    private m_lat
    private m_precision
    private m_country
    private m_xml
    private m_reason
    private m_output
    private m_url
    
 '***************************************************************************
 ' Copyright 2010 Larry Boeldt 
 ' Function:  class_initialize Version 1.0    11:11 AM Sunday, June 27, 2010
 ' Author: Larry Boeldt
 ' Terms: 
 ' GPL, commercial license available
 '
 ' Parameter(s):
 '   none
 '
 ' Return Value:
 '   none
 '
 ' Description:
 ' Initialize the class object with default values. 
 ' Remember to sign up for your yahooappid and paste it below
 '***************************************************************************
    sub class_initialize()
       '' Get your appid here: https://developer.apps.yahoo.com/wsregapp/
       '' copy and paste your app id below
        appid=""
        m_output = "xml"
    end sub
    property get output()
        output = m_output
    end property
    
    property get url()
        url = m_url
    end property
    property let output(value)
        if value="php" or value="xml" then 
            m_output=value
        else
            m_output = "xml"
        end if    
    end property    
    
    property get lon()
        lon = m_lon
    end property
    property get lat()
        lat = m_lat
    end property
    
    property get city()
        city = m_city
    end property
    
    property get state()
        state = m_state
    end property
    
    property get zip()
        zip = m_zip
    end property
    
    property get country()
        country = m_country
    end property
    property get precision()
        precision = m_precision
    end property
    
    property get address()
        address=m_street
    end property
    
    property get street()
        street = m_street
    end property
    
    
    property get xml()
        xml = m_xml
    end property
    
    property get reason()
        reason = m_reason
    end property
    
 
 '***************************************************************************
 ' Copyright 2010 Larry Boeldt 
 ' Function:  GetPrecision Version 1.0    11:11 AM Sunday, June 27, 2010
 ' Author: Larry Boeldt
 ' Terms: 
 ' GPL, commercial license available
 '
 ' Parameter(s):
 '   Doc XML Document from Yahoo
 '
 ' Return Value:
 '   Precision value from yahoo
 '
 ' Description:
 ' Get the precision value returned by yahoo
 '
 '***************************************************************************
    function GetPrecision( doc )
        Dim node
        dim value
        set node=doc.documentElement.selectSingleNode( "/ResultSet/Result" )
        if node is nothing then 
            value = "none" 
        else
            value = node.GetAttribute( "precision" )
        end if 
        set node = nothing
        
        GetPrecision = value
    end function
 '***************************************************************************
 ' Copyright 2010 Larry Boeldt 
 ' Function:  GetXMLValue Version 1.0    11:11 AM Sunday, June 27, 2010
 ' Author: Larry Boeldt
 ' Terms: 
 ' GPL, commercial license available
 '
 ' Parameter(s):
 '   Doc  XML Document from Yahoo
 ' name the tag name/value you want to retrieve
 ' Return Value:
 '   Value of specified tag or blank string
 '
 ' Description:
 ' Get one of the address return values from the yahoo XML
 '
 '***************************************************************************    
    function GetXMLValue( doc, name )
        Dim node
        dim value
        if left(name,1) = "/" then 
           '' get a custom node
           set node=doc.documentElement.selectSingleNode( name )
        else 
           '' get by name from default location
           set node=doc.documentElement.selectSingleNode("/ResultSet/Result/" & name )
        end if
        if node is nothing then 
            value = "" 
        else
            value = node.text
        end if 
        set node = nothing
        GetXMLValue = value
    end function
 '***************************************************************************
 ' Copyright 2010 Larry Boeldt 
 ' Function:  Geocode Version 1.0    11:11 AM Sunday, June 27, 2010
 ' Author: Larry Boeldt
 ' Terms: 
 ' GPL, commercial license available
 '
 ' Parameter(s):
 '   street street address to geocode
 ' city   city name to geocode
 ' state   state to geoocde
 ' zip    zip code/postal code to geocode
 '
 ' Return Value:
 '   none
 '
 ' Description:
 ' Call the Yahoo geocoder with the given address information.
 '
 '***************************************************************************
    function geocode( street, city, state, zip )
        dim url
        Dim doc
        output = m_output
        
        Set doc=CreateObject("Microsoft.XMLDOM") 
        doc.async=false 
        call doc.setProperty("ServerHTTPRequest",true)
        url="http://local.yahooapis.com/MapsService/V1/geocode" & _
            "?appid=" & appid & _
            "&street=" & street & _
            "&city=" & city & _
            "&state=" & state & _
            "&zip=" & zip & _
            "&output=" & output 
        m_url = url
        doc.load( url )
        '' Blank out the property values to defaults before continuing
        m_lat = 0.0
        m_lon = 0.0
        m_street = ""
        m_city = ""
        m_state = ""
        m_zip = ""
        m_country = ""
        m_xml = "not loaded"
        m_precision = "failed"
        
        '' Check if there was an error getting the document from yahoo

        if doc.parseError.errorcode=0 then
            '' Now check if we have a YAHOO error
            if isError( doc ) = true then
                m_reason = GetXMLValue( doc, "/Error/Message" )
            else
                ' proceed
                m_precision = GetPrecision( doc )
                m_lat = GetXMLValue( doc, "Latitude" )
                m_lon = GetXMLValue( doc, "Longitude" )
                m_street = GetXMLValue( doc, "Address" )
                m_city = GetXMLValue( doc, "City" )
                m_state = GetXMLValue( doc, "State" )
                m_zip = GetXMLValue( doc, "Zip" )
                m_country = GetXMLValue( doc, "Country" )
                m_reason = ""
            end if
            m_xml = doc.xml
        else 
            m_reason = doc.parseError.reason & " line: " & doc.parseError.line
            m_xml = doc.text
            '' Error code here
        end if
        set doc = nothing
    end function
 '***************************************************************************
 ' Copyright 2010 Larry Boeldt 
 ' Function:  isError Version 1.0    11:11 AM Sunday, June 27, 2010
 ' Author: Larry Boeldt
 ' Terms: 
 ' GPL, commercial license available
 '
 ' Parameter(s):
 '   Doc XML Document from Yahoo
 '
 ' Return Value:
 '   True if document is a Yahoo! Error document
 ' False if document is a valid data packet from yahoo
 '
 ' Description:
 ' Determine if returned documen is a Yahoo error document
 '
 '***************************************************************************
    function isError( doc )
        dim bResult
        
        if GetXMLValue( doc, "/Error/Message" ) = "" then 
            bResult = false
        else
            bResult = true
        end if
        
    end function
end class '' YGeocoder

How It Works

The Geocode function is the main workhorse in the class; it does the work of assembling a URL and making an HTTP GET call to the Yahoo! Placefinder service. Here is the code segment that does the job; I've added comments to each line describing what it does:

Set doc=CreateObject("Microsoft.XMLDOM")  '' Create a XML Dom object
doc.async=false '' we will make a syncronus call meaning the object will wait for a response

'' This part is important if you want to call within an ASP page
call doc.setProperty("ServerHTTPRequest",true) 

'' Assemble the URL with the parameters passed in the geocode call
url="<a href="http://local.yahooapis.com/MapsService/V1/geocode">http://local.yahooapis.com/MapsService/V1/geocode</a>" & _
    "?appid=" & appid & _
    "&street=" & street & _
    "&city=" & city & _
    "&state=" & state & _
    "&zip=" & zip & _
    "&output=" & output 
'' Set a global property m_url with the url string (for debugging purposes)
m_url = url
'' Now make the call to yahoo geocoder service using the assembled URL

doc.load( url )

The doc object will now contain the XML response from Yahoo!'s Web Service. To populate the object properties, I parse the XML document, looking for each desired property value. To make this an easy task, I use a utility function GetXMLValue that takes as parameters the document object and the name of the return tag whose value I want to capture. You'll see this as a series of calls that look like this...

m_lat = GetXMLValue( doc, "Latitude" )

In the example above, I get the latitude value and assign it to m_lat. This is exposed to your calling code as the property .lat in your ygeo object. This practice might seem redundant, but it is the proper object oriented technique for dealing with classes. The following code segment illustrates how the property is created:

property get lat()
    lat = m_lat
end property 

The GetXMLValue function is a shortcut way to get the desired properties. Below you will find the full function, with line by line comments that describe what each line is doing:

function GetXMLValue( doc, name )

    Dim node   '' Placeholder for an XML Node object
    dim value  '' The value as parsed from the XML node, this is the return value

    '' To facilitate "shortcuts" for the specific yahoo code values the following
    '' If then statement is used
    if left(name,1) = "/" then '' Check if a custom node request is made
       '' get a custom node
       set node=doc.documentElement.selectSingleNode( name )
    else 
       '' Custom node request was not found, get by name from default location
       set node=doc.documentElement.selectSingleNode("/ResultSet/Result/" & name )
    end if

    '' If the node is nothing (not found) then return a blank value
    if node is nothing then 
        value = "" 
    else
        '' Then node has been found, return the text within the tags of the node
        value = node.text
    end if 
    '' Clean up by setting the node to nothing

    set node = nothing

    '' Return the value of the node (or blank if not found)
    GetXMLValue = value
end function

That covers the main set of functions that make this class work. There are two more functions worth noting: isError and GetPrecision. Each takes the XML document object as a parameter and returns a value based on what is found in the XML. isError returns true if Yahoo! Place Finder could not geocode the address for some reason (for example, if you passed all blank values). The GetPrecision function returns Yahoo's precision value which indicates whether the longitude and latitude values are from the 'address', 'zip', or 'city' depending on how accurately your address information could be matched. In the case of zip and city, the "centroid" value is provided. The centroid in most cases is the geographic center of the city or the zip code's tabulated area.

History

• 2010/09/06 - Initial article post
• 2012/03/06 - Updated code for revised API