Yahoo! Search Web Services - Local Search (V3) Documentation

Support & Community

The Local Search service is discussed on the yws-search-general mailing list.

Request URL

http://local.yahooapis.com/LocalSearchService/V3/localSearch

Request parameters

See information on constructing REST queries

Parameter	Value	Description
appid	string (required)	The application ID. See Application IDs for more information.
query	string	The query to search for. Using a query of "*" returns all values that match other criteria in the search (category, radius, and so on).
listing_id	string	The id associated with a specific business listing. It corresponds with the id attribute of Result entities. At least one of query or listing id must be specified.
results	integer: default 10, max 20	The number of results to return.
start	integer: default 1	The starting result position to return (1-based).
sort	relevance (default), title, distance, or rating	Sorts the results by the chosen criteria.
radius	float	How far (in miles) from the specified location to search for the query terms. The default radius varies according to the location given.
street	string	Street name. The number is optional.
city	string	City name.
state	string	The United States state. You can spell out the full state name or you can use the two-letter abbreviation.
zip	integer or <integer>-<integer>	The five-digit zip code, or the five-digit code plus four-digit extension. If this location contradicts the city and state specified, the zip code will be used for determining the location and the city and state will be ignored.
location	free text	This free field lets users enter any of the following: city, state city, state, zip zip street, city, state street, city, state, zip street, zip If location is specified, it will take priority over the individual fields in determining the location for the query. City, state and zip will be ignored.
latitude	float: -90 to 90	The latitude of the starting location.
longitude	float: -180 to 180	The longitude of the starting location. If both latitude and longitude are specified, they will take priority over all other location data. If only one of latitude or longitude is specified, both will be ignored.
category	integer	The id of a category to search in. This id corresponds to the id attribute of the Category entity. If you specify multiple categories (category=1234&category=5678), results are taken from entries that appear in all of the specified categories.
omit_category	integer	The id of a category to omit results from. Multiple categories may be omitted (omit_category=1234&omit_category=5678), and a result will not be returned if it appears in any of the specified categories.
minimum_rating	integer	The minimum average rating (on a five point scale) for a result. If this is specified, no results without ratings will be returned.
output	string: xml (default), json, php	The format for the output. If json is requested, the results will be returned in JSON format. If php is requested, the results will be returned in Serialized PHP format.
callback	string	The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the Yahoo! Developer Network JSON Documentation.

Sample Request Url: http://local.yahooapis.com/LocalSearchService/V3/localSearch?appid=YahooDemo&query=pizza&zip=94306&results=2

Response fields

The schema document for this service response is located at http://local.yahooapis.com/LocalSearchService/V3/LocalSearchRepsonse.xsd

Field	Description
ResultSetMapUrl	The URL of a webpage containing a map graphic with all returned results plotted on it.
ResultSet	Contains all of the query responses. Has attributes: totalResultsAvailable: The number of query matches in the database. totalResultsReturned: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available. firstResultPosition: The position of the first result in the overall search.
Result	Contains each individual response. Has attributes: id: The id of this listing. It may be fed back into the search using the listing_id parameter to retrieve this specific record.
Title	Name of the result.
Address	Street address of the result.
City	City in which the result is located.
State	State in which the result is located.
Phone	Phone number of the business, if known.
Latitude	The latitude of the location.
Longitude	The longitude of the location.
Rating	An enclosure tag for rating information.
AverageRating	Average score of end-user ratings for the business or service.
TotalRatings	The total number of ratings submitted for the business or service.
TotalReviews	The total number of reviews submitted for the business or service. Reviews can be viewed at the location pointed to by the ClickUrl tag.
LastReviewDate	The date of the last review submitted for the business or service unix timestamp format.
LastReviewIntro	The first few words of the last review submitted for the business or service.
Distance	The distance as calculated by one of the following methods: When you enter a street address along with your search term, this is the distance from that particular street address to each result. When you enter your search term along with a city or a city and state, this is the distance from the city center to the business you're looking for.
Url	The URL to the detailed page for a business.
ClickUrl	The URL for linking to the detailed page for a business. See URL linking for more information.
MapUrl	The URL of a map for the address.
BusinessUrl	The URL of the businesses website, if known.
BusinessClickUrl	The URL for linking to the businesses website if known. See URL linking for more information.
Categories	Contains all the categories in which this listing is classified.
Category	A category for this listing. Has attributes: id: The id of this category. It may be fed back into the search using the category parameter to retrieve listings from this category.

Sample response

The following is a sample response for the query pizza in zip code 94306:

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xsi:schemaLocation="urn:yahoo:lcl http://local.yahooapis.com/LocalSearchService/V3/LocalSearchResponse.xsd" totalResultsAvailable="401" totalResultsReturned="2" firstResultPosition="1">
   <ResultSetMapUrl>http://local.yahoo.com/mapview?stx=pizza&csz=Palo+Alto%2C+CA+94306&city=Palo+Alto&state=CA&radius=15&ed=BVD56a131DxIV6V7_5O_wO8KQY1.bxtOAd8qew--</ResultSetMapUrl>
      <Result id="21395990">
      <Title>Round Table Pizza Palo Alto</Title>
      <Address>3407 Alma St</Address>
      <City>Palo Alto</City>
      <State>CA</State>
      <Phone>(650) 494-2928</Phone>
      <Latitude>37.419862</Latitude>
      <Longitude>-122.126129</Longitude>
      <Rating>
         <AverageRating>NaN</AverageRating>
         <TotalRatings>0</TotalRatings>
         <TotalReviews>0</TotalReviews>
      </Rating>
      <Distance>0.19</Distance>
      <Url>http://local.yahoo.com/details?id=21395990&stx=pizza&csz=Palo+Alto+CA&ed=OtVQW6160SwBXrynJIx8rirX3iaOtFHwFBC480.oEQVLaK1tM9x1WN.BrJASDzg2asPklg--</Url>
      <ClickUrl>http://local.yahoo.com/details?id=21395990&stx=pizza&csz=Palo+Alto+CA&ed=OtVQW6160SwBXrynJIx8rirX3iaOtFHwFBC480.oEQVLaK1tM9x1WN.BrJASDzg2asPklg--</ClickUrl>
      <MapUrl>http://maps.yahoo.com/maps_result?name=Round+Table+Pizza+Palo+Alto&desc=6504942928&csz=Palo+Alto+CA&qty=9&cs=9&ed=OtVQW6160SwBXrynJIx8rirX3iaOtFHwFBC480.oEQVLaK1tM9x1WN.BrJASDzg2asPklg--</MapUrl>
      <BusinessUrl>http://www.roundtablepizza.com/</BusinessUrl>
      <BusinessClickUrl>http://www.roundtablepizza.com/</BusinessClickUrl>
      <Categories>
         <Category id="96926243">Pizza</Category>
         <Category id="96926236">Restaurants</Category>
      </Categories>
   </Result>
   <Result id="21395062">
   <Title>Papa Murphys Pizza Take & Bake</Title>
   <Address>2730 Middlefield Rd</Address>
   <City>Palo Alto</City>
   <State>CA</State>
   <Phone>(650) 328-5200</Phone>
   <Latitude>37.433243</Latitude>
   <Longitude>-122.129291</Longitude>
   <Rating>
      <AverageRating>4</AverageRating>
      <TotalRatings>8</TotalRatings>
      <TotalReviews>5</TotalReviews>
      <LastReviewDate>1140040245</LastReviewDate>
      <LastReviewIntro>Great place to have pizza with the family.</LastReviewIntro>
   </Rating>
   <Distance>0.99</Distance>
   <Url>http://local.yahoo.com/details?id=21395062&stx=pizza&csz=Palo+Alto+CA&ed=0runZK160SyuzGmb4f1aQLs1KJTXAH56bJ_0HffsK.rhcWN62yU_7KJzff4AZ8TX2LILpT.nu6KJiQQ-</Url>
   <ClickUrl>http://local.yahoo.com/details?id=21395062&stx=pizza&csz=Palo+Alto+CA&ed=0runZK160SyuzGmb4f1aQLs1KJTXAH56bJ_0HffsK.rhcWN62yU_7KJzff4AZ8TX2LILpT.nu6KJiQQ-</ClickUrl>
   <MapUrl>http://maps.yahoo.com/maps_result?name=Papa+Murphys+Pizza+Take+%26amp%3B+Bake&desc=6503285200&csz=Palo+Alto+CA&qty=9&cs=9&ed=0runZK160SyuzGmb4f1aQLs1KJTXAH56bJ_0HffsK.rhcWN62yU_7KJzff4AZ8TX2LILpT.nu6KJiQQ-</MapUrl>
   <BusinessUrl>http://www.papamurphys.com/</BusinessUrl>
   <BusinessClickUrl>http://www.papamurphys.com/</BusinessClickUrl>
   <Categories>
      <Category id="96926242">Fast Food</Category>
      <Category id="96926234">Carry Out & Take Out</Category>
      <Category id="96926243">Pizza</Category>
      <Category id="96926236">Restaurants</Category>
   </Categories>
   </Result>
</ResultSet>

Rate Limit

The Local Search service is limited to 5,000 queries per IP address per day and to noncommercial use. See information on rate limiting and our Usage Policy to learn about acceptable uses and how to request additional queries.

Errors

The Local Search service returns the standard errors. There are no service-specific errors.