Version 1 Yahoo! Local Web Services : collectionSearch
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.
Getting Started
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.
Parameters
| Parameter | Value | Description |
| 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. |
Response
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
Top-Level Elements
| Element | Description |
| 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 Attributes:
|
| 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. |
Result Elements
The Result element contains information about each collection and its contents.
| Element | Description |
| 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). |
Samples & Examples
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
?appid=YahooDemo&query=pizza&city=san+jose
You can also search for collections created by a specific user with the username parameter:
?appid=YahooDemo&username=ylocal_team
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:
?appid=YahooDemo&query=pizza&results=20
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:
?appid=YahooDemo&query=pizza&results=20&start=21
To get a list of collections containing the phrase "mardi gras": (the first ten are returned):
?appid=YahooDemo&query=mardi+gras
To get a list of collections containing the phrase "mardi gras": (the second 20 are returned):
?appid=YahooDemo&query=hamburger&results=20&start=21
To get a list of collections containing the phrase "thai", and get JSON output wrapped in a callback function called get_collection:
?appid=YahooDemo&query=hamburger&output=json&callback=get_collection
Here's a sample XML response:
Errors
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.
Rate Limit
The Yahoo! Local Web Services are limited to 5,000 queries per IP address per day. See Rate limiting for details.
Acceptable Use
The Yahoo! Local services are limited to non-commercial use only. See information on our Usage Policy to learn about acceptable uses.
Support & Community
The Yahoo! Local CollectionSearch web service is part of Yahoo! Local Web Services which are discussed on the yws-search-general mailing list.
Ready to get started?
By applying for an Application ID for this service, you hereby agree to the Terms of Use