Version 1 Yahoo! Local Web Services : getCollection
The getCollection service enables you to get detailed information about a collection created with Yahoo! Local Collections, through a REST-like API. With this web service you can get information about a public collection including its description and all the items associated with that collection. To use getCollection, you will need two things: an application ID to identify your application, and the ID of the collection you want to retrieve, available through the collectionSearch service.
Getting Started
The base URL for getCollection is:
The getCollection service follows standard HTTP GET syntax. See constructing REST queries for details.
Summary
For the getCollection REST request there are four parameters:
appid for the application ID.
collection_id for the ID of the collection to be retrieved.
output for the output type
callback to specify a callback function
The appid is your application ID -- an identifier for your application -- and is a required parameter. See Requesting an Application ID for information on requesting your own application ID.
The collection_id is the ID of the collection, created in Yahoo! Local Collections that you want to retrieve. You can find out the ID of the Collection to retrieve using the Collection Search Web Service. Note that the collection you are retrieving must have been defined to be a public collection.
By default, Yahoo! Local returns an XML document in response to this request. See Response for information on the elements contained in this document. If you use the output parameter with the value json, the output is in JSON (JavaScript Object Notation) format. The names of the objects are the same as with the XML elements. If in addition to the output parameter you also use the callback parameter with the name of a callback function, the JSON output is wrapped in that function (that is, my_function(json_text)). See Using JSON with Yahoo! Web Services for more information on using JSON web services output.
Parameters
| Parameter | Value | Description |
| appid | string (required) | An identifier for your application See Application IDs for more information. |
| collection_id | integer (required) | The ID of the collection to retrieve. You can find out the ID of the Collection you want to find using The Collection Search Web Service. |
| 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 Get Collection API conforms to XML 1.0. No child elements. |
| Result | Parent element for the result. Child elements: Title, Description, CreateTime, Username, CommentCount |
Result Elements
The result element contains information about the collection and its contents.
| Element | Description |
| Result | The parent element for the collection (element). Attribute: id: The collection ID. Child elements: YahooID, Title, Summary, CreateDate, UpdateDate, Duration, Image, Tag, Destination |
| Title | The title of the collection, for example "Paris Vacation in June " (string). |
| Description | The overall description of the collection, for example "My Favorite Places in San Francisco " (string). |
| CreateTime | The date this collection was created, in Unix timestamp format (integer). |
| Username | The Username of the user who created this collection. (string) |
Item Elements
Items represent different businesses in the collection: Restaurants, spas, mechanics and so on. Each item has a category, an address, URL, image, and other elements representing that item.
| Element | Description |
| Item | An individual item for this collection (element). Child Elements: Title, Description, Category, Image, Address, Phone, Url, Tags Attributes: id: The unique ID of the item |
| Title | The title for this item (string) |
| Description | A summary of the item (string) |
| Category | The category of this item. Example categories are Bar, Hotel, Restaurant, Shopping, Things to do (string). |
| Image | The image uploaded by a user to identify this item. See Image Elements for element descriptions (element). Child elements: Url, Width, Height |
| Address | The address associated with this item, if available. See Address Elements for element descriptions (element). |
| Phone | The phone number associated with this item, if available (string). |
| Url | A URL associated with this item. If there are multiple URLs for the item there will be multiple URL elements. (string) |
| Tag | A tag associated with this item. If the item contains multiple tags there are multiple tag elements. (string). |
Image Elements
The image element describes the image or icon used to identify the collection or item. The image element can be contained inside the Result or Item elements.
| Element | Description |
| Image | The parent element for the image (element). Child elements: Url, Width, Height |
| Url | The URL of the image (string). |
| Width | The width of the image, in pixels (integer). |
| Height | The height of the image, in pixels (integer). |
Address Elements
The address element describes an address for an item.
| Element | Description |
| Address | The parent element for the address (element). Child elements: Address1, Address2, City, State, Country, PostalCode, Neighborhood |
| Address1 | Street address (string) |
| Address2 | Second line of street address, if available (string) |
| City | City name (string). |
| State | Two-digit state code (for US addresses) (string). |
| Country | Country name (string). |
| PostalCode | Postal or ZIP code, if available (integer). |
| Neighborhood | Neighborhood of the address, if available (string). |
Samples & Examples
To retrieve a collection with the ID of 1234:
?appid=YahooDemo&collection_id=1234
To retrieve a collection with the ID of 1234, and get JSON output (instead of XML):
?appid=YahooDemo&collection_id=1234&output=json
To retrieve a collection with the ID of 1234, and get JSON output wrapped in a callback function named blasmo:
?appid=YahooDemo&collection_id=1234&output=json&callback=blasmo
Errors
getCollection returns our standard errors. See Error Messages for details.
Note that it may take upto 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 Web services are limited to non-commercial use only. See information on our Usage Policy to learn about acceptable uses.
Support & Community
The Yahoo! Local Get Collection 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
Yahoo! Groups Discussions
view all
Fri, 05 Sep 2008
Fri, 05 Sep 2008
Fri, 05 Sep 2008
BUG: Related suggestions API returning undefined entities (breaks XM
Fri, 05 Sep 2008
Send Your Suggestions