Welcome, guest Sign In

Local Search Web Services

Submitting Local Queries

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.

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, max 250 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.

This param is ignored when a route is passed in.
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.
route string 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:

  • lat1 long1,lat2 long2,...,latn longn
A route is limited to 100 coordinates or 100 total miles. If a route exceeds either of these limits, an error status is returned.

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.

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 in 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.
  • When you enter a route, this is the distance from the closest point along that route to each result.
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.
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:

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.

Support & Community

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

Errors

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

Ready to get started?

By applying for an Application ID for this service, you hereby agree to the Terms of Use

Copyright © 2009 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy

Help us continue to improve the Yahoo! Developer Network: Send Your Suggestions