6.3. Meet the Yahoo! Web Services
Before you go looking at the web services we'll use to build this application, you need to get some paperwork out of the way first.
Most API services require you to register to use their APIs, and Yahoo! is no exception. Every time you make a Yahoo! service call, you need to pass an appid parameter. The value of this parameter is a unique identifier assigned to your application. Not passing this value, or passing an invalid value, will result in the call failing. Before you can play with the application in this chapter, you will have to register and get your own appid. Ist's a painless process that you can go through by accessing the following page:
http://api.search.yahoo.com/webservices/register_application
You should plug your own appid into the LocalBusinessSearch.js file (in the aptly named appID field) before you spend time with the application, just so you are playing nice with Yahoo!. I'll use XXX in the following sections when referencing appid to indicate that you should plug your ID in there.
There are some limitations associated with using the APIs in terms of request volume, but the upper limit is so high as to not be a realistic concern for your adventures with this application. In any case, the limits are based on requests made from a given IP address over a 24-hour period, so even if you run over the limit just try again tomorrow and you should be good to go. If you are intent on building a production-level application by using these services, you will need to consult with Yahoo! for other registration options that allow for high volumes. Again, for our purposes, the number of requests allowed is more than sufficient.
6.3.1. The Yahoo! Local Search Service
Yahoo! offers some very nice search services that you can play with, and one of them is the Yahoo! Local search service. It enables you to search for businesses in a given geographic location. For each search result, the service provides a plethora of information, including the business location, contact information (phone number, web site, and so forth), and user rating information.
Using this service requires you to access a given URL, for example:
http://local.yahooapis.com/LocalSearchService/V3/localSearch?appid=XXX&query=pizza&zip=94306&results=2
The query parameter enables you to specify a keyword to search for, zip is just a US zip code to center the search around, and results is the maximum number of results you want to return. The appid is an ID you get when you register for the services, as discussed in the previous section. If you go ahead and paste that into the address bar of your web browser, assuming you replace the XXX appid with a valid ID, you'll see the following response:
<?xml version="1.0"?><ResultSet xmlns:xsi=http://www.w3.org/2001/XMLSchema-instancexmlns="urn:yahoo:lcl" xsi:schemaLocation="urn:yahoo:lclhttp://api.local.yahoo.com/LocalSearchService/V3/LocalSearchResponse.xsd" totalResultsAvailable="459"
totalResultsReturned="1" firstResultPosition="1"><ResultSetMapUrl>http://maps.yahoo.com/broadband/?q1=Palo+Alto%2C+CA+94306&tt=pizza&tp=1</ResultSetMapUrl><Result id="28734629"><Title>Patxi's Chicago Pizza</Title><Address>441 Emerson St</Address><City>Palo Alto</City><State>CA</State><Phone>(650) 473-9999</Phone><Latitude>37.445242</Latitude><Longitude>-122.163427</Longitude><Rating><AverageRating>4.5</AverageRating><TotalRatings>30</TotalRatings><TotalReviews>21</TotalReviews><LastReviewDate>1203959693</LastReviewDate><LastReviewIntro>I'd give this place 4.5 Stars, butsince I can't tie goes to the Restaurant. This isa good alternative to the legendary Zachary's withthe benefit that there isn't usually a wait. Inmany ways I like this place better than Zachary'ssince it seems to have figured out a way to doChicago deep dish without the heaviness of theoils, It could be the sauce being more of a pureeinstead of chopped tomatoes balances the oils out.While I am mostly a NY Thin Crust kind of guy, thisis top notch pizza.</LastReviewIntro></Rating><Distance>2.67</Distance><Url>http://local.yahoo.com/details?id=28734629&stx=pizza&csz=Palo+Alto+CA&ed=5Ft25a160SwgYwogEsXfvFF62jUOrNK1trfxXbRawD4AClLtHub4_iH_GpomidnTfCwCqJBK</Url><ClickUrl>http://local.yahoo.com/details?id=28734629&stx=pizza&csz=Palo+Alto+CA&ed=5Ft25a160SwgYwogEsXfvFF62jUOrNK1trfxXbRawD4AClLtHub4_iH_GpomidnTfCwCqJBK</ClickUrl><MapUrl>http://maps.yahoo.com/maps_result?name=Patxi%27s+Chicago+Pizza&desc=6504739999&csz=Palo+Alto+CA&qty=9&cs=9&gid1=28734629</MapUrl><BusinessUrl>http://www.patxispizza.com/</BusinessUrl><BusinessClickUrl>http://www.patxispizza.com/</BusinessClickUrl><Categories><Category id="96926243">Pizza</Category><Category id="96926236">Restaurants</Category><Category id="96926237">American Restaurants</Category><Category id="96926190">Italian Restaurants</Category></Categories></Result></ResultSet> <!-- ws02.search.re2.yahoo.com compressed/? chunked Fri Jul 25 22:45:33 PDT 2008 -->
To turn this into a JSON-P request, we have only to add two parameters to the request: output, with a value of json, and callback, with a value of the name of the function to call. So, if we do this:
http://local.yahooapis.com/LocalSearchService/V3/localSearch?appid=XXX&query=pizza&zip=94306&results=1&output=json&callback=myCallback
...the response we get is now this:
myCallback({"ResultSet":{"totalResultsAvailable":"459",
"totalResultsReturned":"1","firstResultPosition":"1",
"ResultSetMapUrl":"http://maps.yahoo.com/broadband/
?q1=Palo+Alto%2C+CA+94306&tt=pizza&tp=1","Result":
{"id":"28734629","Title":"Patxi's Chicago Pizza",
"Address":"441 Emerson St","City":"Palo Alto","State":"CA","Phone":
"(650) 473-9999","Latitude":"37.445242",
"Longitude":"-122.163427","Rating":{"AverageRating":"4.5",
"TotalRatings":"30","TotalReviews":"21",
"LastReviewDate":"1203959693","LastReviewIntro":
"I'd give this place 4.5 Stars, but since I can't
tie goes to the Restaurant. This is a good alternative
to the legendary Zachary's with the benefit that there
isn't usually a wait. In many ways I like this place
better than Zachary's since it seems to have figured out
a way to do Chicago deep dish without the heaviness of
the oils, It could be the sauce being more of a puree
instead of chopped tomatoes balances the oils out. While
I am mostly a NY Thin Crust kind of guy, this is top notch
pizza."},"Distance":"2.67","Url":"http://
local.yahoo.com/details?id=28734629&stx=pizza&
csz=Palo+Alto+CA&ed=5Ft25a160SwgYwogEsXfvFF62jUOr
NK1trfxXbRawD4AClLtHub4_iH_GpomidnTfCwCqJBK",
"ClickUrl":"http://local.yahoo.com/details?
id=28734629&stx=pizza&csz=Palo+Alto+CA&ed=5Ft25
a160SwgYwogEsXfvFF62jUOrNK1trfxXbRawD4AClLtHub4
_iH_GpomidnTfCwCqJBK","MapUrl":"http://
maps.yahoo.com/maps_result?name=Patxi%27s+
Chicago+Pizza&desc=6504739999&csz=Palo+Alto+
CA&qty=9&cs=9&gid1=28734629","BusinessUrl":
"http://www.patxispizza.com/","BusinessClickUrl":
"http://www.patxispizza.com/","Categories":
{"Category":[{"id":"96926243","content":"Pizza"},
{"id":"96926236","content":"Restaurants"},
{"id":"96926237","content":"American Restaurants"},{"id":"96926190",
"content":"Italian Restaurants"}]}}}});It's not much to look at on the page, I admit, but it's golden in the code: if we called this by using the <script> injection trick, myCallback() would get called and passed an object with a bunch of data fields we can reference. For instance, the Latitude and Longitude fields tell us where this business is located, Rating tells us the average user rating, and Distance tells us how far away the business is. The set of data returned by the service is pretty large, and a lot of it won't be used in this application, but if you cruise on over to http://developer.yahoo.com/search/local/V3/localSearch.html, you can get all those details, plus a lot more, about this particular service.
6.3.2. The Yahoo! Map Image Service
Yahoo! is also going to be providing the maps that you can see on the Map pane of the application (yes, take a break and go play with the application a bit now!). Yahoo! Maps is a service that has been around for a while, even before a public JSON-P interface was provided for it. It enables you to get maps for a given address, as well as access other features, such as traffic and local places of interest. The API Yahoo! provides a number of different services, but for our purposes, We'll be focusing on the Map Image service.
The Yahoo! Maps Map Image API enables you to get a reference to a graphic of a map generated according to the parameters you specify in your request. You may specify latitude and longitude or address in your request (We'll be specifying longitude and latitude in the application itself, but in this discussion it'll just be an address, more precisely, a component of an address).
This service is referenced via a simple HTTP request, such as the following:
http://local.yahooapis.com/MapsService/V1/mapImage?appid=XXX&location=11719
The location parameter specified is just a US zip code, and the appid is once again your registered application ID. If you go ahead and paste that into the address bar of your web browser, you'll see the following response:
<?xml version="1.0"?><Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">http://gws.maps.yahoo.com/mapimage?MAPDATA=n60ehud6wXUJUYM_tJcfOwsQpG9JUAzuPggQRTTce9N8zspONMdiDVuUVXTcOkJcBUZXUolGqZulnHzcPOkjcpYTF82_DXtJgf4ISRYS8gqVHaBiWhmY3OqSK9C9PR4.k.HNxwaJJ02UQq0OexH6&mvt=m?cltype=onnetwork&.intl=us</Result><!-- ws01.search.re2.yahoo.com compressed/chunkedFri Jul 25 10:32:36 PDT 2008 -->
What You've gotten back includes a reference to an image now sitting on Yahoo's servers. If you pluck out the following URL:
http://gws.maps.yahoo.com/mapimage?MAPDATA=n60ehud6wXUJUYM_tJcfOwsQpG9JUAzuPggQRTTce9N8zspONMdiDVuUVXTcOkJcBUZXUolGqZulnHzcPOkjcpYTF82_DXtJgf4ISRYS8gqVHaBiWhmY3OqSK9C9PR4.k.HNxwaJJ02UQq0OexH6&mvt=m?cltype=onnetwork&.intl=us
...and put that in the address bar of a web browser, you'll see an image that is a map of the Bellport/Mastic Beach area of Long Island, New York, as shown in Figure 6-2.
Figure 6.2. The map resulting from assessing the URL in the example
You can also add some parameters to the original request. For instance, you can specify that you want a GIF back (by default, you get a PNG file), and you can specify that instead of XML, you want JSON back. The URL would then look like this:
http://local.yahooapis.com/MapsService/V1/mapImage?appid=XXX&location=11719&image_type=gif&output=json&callback=myCallback
Now the response you get is this:
myCallback({"ResultSet":{"Result":"http://gws.maps.yahoo.com/mapimage?
MAPDATA=cxsuGud6wXXyiBJ69MPrKK..1HUkskJsw7lifuUcFkwxzQ4OjwJp.wHqkuSE
pCr9RhHUtwrTtNO.b4WNfkBNid1D6TAblazXIF8anq5PqbaLIF5iAmHGbbh8LZtPjnvs
LP8Ndkoiu1qWNWduAGHC&mvt=m?cltype=onnetwork&.intl=us"}});A few other parameters are used in the application, and these are summarized in Table 6-1.
| Parameter | Meaning |
|---|---|
| latitude | The latitude that is the center of the map. |
| longitude | The longitude that is the center of the map. |
| image_width | The width of the map image. |
| image_height | The height of the map image. |
| zoom | The zoom factor to apply to the map. This is a value in the range 1-12, where 1 represents street level and 12 represents regional level (a little wider than state level). |
As with the local search service, I encourage you to examine the Yahoo! Maps APIs (http://developer.yahoo.com/maps/rest/V1) because they can definitely do more than this application demonstrates. This is about all we need for the purposes of this chapter, though, so you're now armed with all the knowledge you need to go forth and dissect this application!