The Yahoo! Local collectionSearch service enables you to search for public collections created with the Yahoo! Local Collections service, through a REST-like API. With this web service you can get a list of collections based on specific criteria, including the name of the user who created the plan. Only Collections that have been defined as public can be retrieved using Yahoo! Local Collections Search. Use the information from this search to retrieve more information about a collection with the getCollection service.
To use the collectionSearch service you will need an application ID to identify your application, and a query string, such as "pizza" or "hawaii." You may also optionally enter a username to narrow your search to a single user's public collections or a city to narrow it down to a geographical location.
The base URL for collectionSearch is:
The collectionSearch request follows standard HTTP GET syntax. See constructing REST queries for details.
|appid||string (required)||An identifier for your application. See Application IDs for more information.|
|query||string||Search keyword(s). Public collections that contain the given text in the title or description are returned. Either the username or query parameter (or both) must be specified.|
|username||string||Search only within the public collections created by this user. Either the username or query parameter (or both) must be specified.|
|city||string||Search for public collections that contains reference to this city. Use this along with query parameter.|
|results||integer||The number of collections to return. The default value is 10; the maximum allowed value is 50.|
|start||integer||The result from which to start the block of collection results. By default the results start from 1.|
|output||string||The output format. The default is XML. If output=json, the results are returned in JSON format. If output=php, 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 is ignored. More information on callbacks can be found in the JSON documentation.|
The Yahoo! Collection Search REST response conforms to XML 1.0. The schema document for this service response is located at http://local.yahooapis.com/LocalSearchService/V1/CollectionSearchResponse.xsd
|xml||The Yahoo! Local Collection Search conforms to XML 1.0. No child elements.|
|ResultSet||Parent element for the all results (element). |
Child element: collection
|Result||Parent element for individual collection results (element).
Child elements: YahooID, Title, Summary, Destinations, CreateDate, UpdateDate, Duration, Image, Geocode, Url
Attribute: id: The ID of the collection.
The Result element contains information about each collection and its contents.
|Result||Parent element for the collection (element).
Child elements: Title, Description, CreatedTime, Username, CommentCount
Attribute: id: The ID of the collection.
|Title||The title of the collection, for example "My Favorite Pizza Joints" (string).|
|Description||A summary of the items available in the collection (string).|
|CreateTime||The date this collection was created, in Unix timestamp format (integer).|
|Username||The username of the creator of this collection (string).|
|CommentCount||Number of comments for this collection(integer).|
You can search for public collections containing a specific keyword with the query parameter. The collection's title, description and tags are searched:
You can restrict the search to a city using the city parameter. The location of items in the collection is searched to limit to this city
You can also search for collections created by a specific user with the username parameter:
Your request may return a large number of Collection results; use the results and start parameters to determine how many results you get back and from which result you want to start the display. By default, the response returns ten results, starting from result 1. The results parameter indicates how many Collection results to return. So, for example, to return twenty results per request, use this request:
Use the start parameter to start the block of results from some result number other than 1. So, for example, the previous request returned the first 20 collection results. To get the next 20 in the list, use the start parameter with the value 21:
To get a list of collections containing the phrase "mardi gras": (the first ten are returned):
To get a list of collections containing the phrase "mardi gras": (the second 20 are returned):
To get a list of collections containing the phrase "thai", and get JSON output wrapped in a callback function called get_collection:
Here's a sample XML response:
The Yahoo! Local Web Services return the standard errors. See Error Messages for details.
Note that it may take a day after you create a collection before that collection is available to the Yahoo! Local Web Services.
The Yahoo! Local Web Services are limited to 5,000 queries per IP address per day. See Rate limiting for details.
The Yahoo! Local services are limited to non-commercial use only. See information on our Usage Policy to learn about acceptable uses.
The Yahoo! Local CollectionSearch web service is part of Yahoo! Local Web Services which are discussed on the yws-search-general mailing list.