The latest version of the Local Search Web Service allows you to search the Internet for businesses near a specified location, and now returns both the latitude and longitude and Yahoo! user ratings of the establishment, as well as search by business categories.
See information on constructing REST queries
|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, max 250||The starting result position to return (1-based).|
|sort||relevance (default), title, distance, or rating||Sorts the results by the chosen criteria.|
How far (in miles) from the specified location to search for the query terms. The default radius varies according to the location given.
This param is ignored when a route is passed in.
|street||string||Street name. The number is optional.|
|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.|
This free field lets users enter any of the following:
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.|
A group of latitude/longitude coordinate pairs that define a travel route. Coordinate pairs must be provided in order of starting point to ending point. The route parameter is defined in the following way:
Selection of coordinates for the route will affect results. Pick ones that both define the path of travel and where you want to find points of interest. For example, you could include freeway off ramps or major intersections. To cause a location on or near a route to get preference, specify a location in addition to the route, otherwise no location preference is given to points of interest found near the route.
|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.|
The schema document for this service response is located at http://local.yahooapis.com/LocalSearchService/V3/LocalSearchRepsonse.xsd
|ResultSetMapUrl||The URL of a webpage containing a map graphic with all returned results plotted on it.|
Contains all of the query responses. Has attributes:
Contains each individual response. Has attributes:
|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 in unix timestamp format.|
|LastReviewIntro||The first few words of the last review submitted for the business or service.|
The distance as calculated by one of the following methods:
|Url||The URL to the details page of a business.|
|ClickUrl||The URL for linking to the details page of a business. See URL linking for more information.|
|MapUrl||The URL of a map for the address.|
|BusinessUrl||The URL of the business' website, if known.|
|BusinessClickUrl||The URL for linking to the business. website if known. See URL linking for more information.|
|Categories||Contains all the categories in which this listing is classified.|
A category for this listing. Has attributes:
The following is a sample response for the query pizza in zip code 94306:
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.
The Local Search service is discussed on the yws-search-general mailing list.
The Local Search service returns the standard errors. There are no service-specific errors.