Using a PageMethod to Look Up City and State based on Zip Code

By: Brian Dobberteen

This one seems like a pretty good one to try and start with – the simple lookup of a city and state based on a zip code entered on a form. We’ll be using Yahoo’s map API here, for which you’ll need to grab an Application ID (freely available at

Be sure to save that in a suitable location, as we’ll need it to form our request to the API later via a simple HTTP GET request to Yahoo’s server. This GET request is about as simple as they come, only needing the Application ID and the zip code in question as query string parameters. In fact, you can build this request and paste it into your browser’s address bar to verify that you have it right. It looks like:

If you try navigating to the above URL, replacing <YOUR APP ID> with the Application ID you received from Yahoo and <ZIP CODE> with the zip you’d like to check out, you should receive an XML response that looks similar to this:

So, getting the info is simple enough, and there are countless ways to handle this, to be sure. In fact, using something like jQuery or even the Microsoft AJAX Library would be very simple and not necessitate the need for PageMethods and the like. So maybe this is a somewhat contrived use of PageMethods, but let’s do it anyway!

I must add, after giving it some more thought, it seems that moving this entire operation to the client would expose our Yahoo Maps Application ID, which is probably not an ideal situation. jQuery would certainly have no problem accomplishing our task, easily handling the parsing of the XML response and so on.

At any rate…

Go ahead and create a new ASP.NET web page and name it whatever you’d like. I’ll be using Default.aspx here, but it really isn’t important. Following the creation of the new page, we’ll be presented with the familiar blank ASP.NET page, replete with a form tag and one lonely div. I’m sure you’ve all seen it a million times, but this is what we’ll be starting with:

As you can see, we’ll be using the code-behind model rather than including the script in the .aspx file seen above. In order to access the PageMethod that we will soon be creating, we need to add a ScriptManager object to the page in order to generate the javascript proxy to our server-side method. This couldn’t be much easier, simply add:

Obviously, the EnablePageMethods attribute is key here, and the only change needed to the default ScriptManager.

Now, let’s add a quick textbox to the form:

And right underneath the asp:TextBox, let’s add an asp:Label element:

Note that we added the attribute ‘onchange’ to the TextBox – it’s set to a function that fires any time the contents of the TextBox change. The function that responds to the event:

Not a whole lot to that, clearly. However, thanks to the ScriptManager we placed on the page, the plumbing between our server-side PageMethod and our client-side javascript has been taken care of. And in this case, we are only passing one parameter to our PageMethod, whose signature is seen here:

Note the Imports System.Web.Services – this is the namespace where the WebMethod() attribute lives. As you can see, this method, which is in our code behind file (Default.aspx.vb) takes the string parameter ‘zip’ and returns a simple CityState object:

This little class is defined on the same page as our code behind file and will automatically be serialized in order for our client-side code to consume it.

The second parameter in PageMethods.GetCityStateFromZip(zip, onGetCityStateComplete) is the name of a callback function that will execute upon completion of our call to the PageMethod.

The result parameter being passed here is a CityState object, as defined in the PageMethod’s signature. It has been nicely serialized into a javascript object with properties that are easily accessed. We use the Microsoft AJAX $get() function to find the label we created earlier and then set its innerHTML to the name of the City, a comma, and the name of the state (i.e. Santa Cruz, CA).

Lastly, let’s check out what’s going on in our PageMethod in terms of actually fetching the data from the Yahoo Maps API

Hopefully the code is somewhat self-explanatory, but let’s review it. .NET is kind enough to allow us to create a new XmlReader object by calling the static method <b<XmlReader.Create() and passing it a URL (line 6). Since we already know how to build the proper URL to get our XML response from Yahoo Maps, we just pass this value. We’re getting the zip code from the zip code text box following its onchange event. In the call to XmlReader.Create() I’ve used two constants, one for the base URL to the Yahoo Maps API and the second for my Application ID. Obviously you’d need to set the Application ID to reflect the one you received earlier.

Presumably, the request went through without a hitch and you are now in possession of a successful XML response. I know, I know, there is absolutely no validation going on here or effort to do any sort of error checking. It’d probably wouldn’t hurt to make sure that the zip code was in a usable format, that the XML response was actually valid, etc. Maybe we can touch on that in a future article.

So, anyways, we now have an XmlReader object and we are going to read it line-by-line in a While loop (line 7), during which a couple of If statements look to see if we’ve come across the city and state elements in the response. I also check to make sure that our XmlReader is at an XML start element (i.e. <City> vs. </City>) so that everything goes smoothly. I don’t know if this is the best way of going about this, but it works, so I didn’t complain 😉

We created our CityState object at the beginning of the function and end up setting its two properties during the read of the XML response. Assuming all went well, the client javascript is returned a CityState object with the names we’re after. And, as we discussed earlier, we simply take that data and slightly reformat it and then add it to our page, which is what we set out to do!

2 thoughts on “Using a PageMethod to Look Up City and State based on Zip Code”

  1. Great tutorial. Though it did not work for me in VS2008 and C#.
    Error with page methods. But still seemed a good tutorial

Leave a Reply

Your email address will not be published. Required fields are marked *