Yahoo! Travel Web Services: Trip Search

REST Request

The Yahoo! Travel Trip Search request (tripSearch) follows standard HTTP GET syntax. See constructing REST queries for details.

The base URL for tripSearch is:

http://travel.yahooapis.com/ TripService/V1/tripSearch?

In this section Request Summary describes the available request parameters; Request Parameters shows a table summarizing those parameters.

Summary

The Yahoo! Travel service enables you to search for trip plans created through Yahoo! Travel Trip Planner. The only required parameter is appid, which indicates your application ID. You can use YahooDemo as a sample appid for testing. See Requesting an Application ID for information on requesting your own application ID.

You can search for public trip plans containing a specific keyword with the query parameter. The trip plan's title, description and tags are searched:

http://travel.yahooapis.com/TripService/ V1/tripSearch? appid=YahooDemo&query=paris

You can also search for plans created by a specific Yahoo! user with the yahooid parameter:

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&yahooid=ydn

Note if you request a specific user's trip plans those plans must have been defined to be public trip plans.

The query must contain the yahooid parameter or the query parameter, or both. If you leave off both the yahooid and query parameters an error is returned.

Your request may return a large number of trip plan 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 trip plan results to return. So, for example, to return twenty results per request, use this request:

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&query=paris&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 trip plan results. To get the next 20 in the list, use the start parameter with the value 21:

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&query=paris&results=20 &start=21

Note that the trip plans are ordered by trip ID so you can ensure that each block of trip plans are unique. The total number of trip plans available to request is in the totalResultsAvailable attribute of the ResultSet element of the response.

By default, Yahoo! Travel 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.
yahooid	string	Search only within the public trip plans created by the user with this Yahoo! ID. Either the `yahooid` or `query` parameter (or both) must be specified.
query	string	Search keyword(s). Public trip plans that contain the given text in the title, description or tags are returned. Either the `yahooid` or `query` parameter (or both) must be specified.
results	integer	The number of trip plans to return. The default value is 10; the maximum allowed value is 50.
start	integer	The result from which to start the block of trip plan 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! Travel Trip Search REST response conforms to XML 1.0. The schema document for this response is located at http://travel.yahooapis.com/TripService/V1/TripSearchResponse.xsd

Top-Level Elements

Element	Description
xml	The Yahoo! Travel Trip Search conforms to XML 1.0. No child elements.
ResultSet	Parent element for the all results (element). Child element: tripplan Attributes: totalResultsAvailable: The total number of results found from the query (which may be larger than the number of results in this response. totalResultsReturned: The number of results in this response. This value is determined by the results parameter. firstResultPosition: The position of the first result in the total number of responses, for response pagination. This value is determined by the start parameter
Result	Parent element for individual trip plan results (element). Child elements: YahooID, Title, Summary, Destinations, CreateDate, UpdateDate, Duration, Image, Geocode, Url Attribute: id: The ID of the trip plan.

Result Elements

The Result element contains information about each trip plan and its contents.

Element	Description
Result	Parent element for the trip plan (element). Child elements: YahooID, Title, Summary, Destinations, CreateDate, UpdateDate, Duration, Image, Geocode, Url Attribute: id: The ID of the trip plan.
YahooID	The Yahoo! ID of the user who created this trip plan (string).
Title	The title of the trip plan, for example "Paris Vacation in June" (string).
Summary	A summary of the items available in the trip plan (string).
Destinations	One or more destinations for the trip plan, separated by commas (string).
CreateDate	The date this trip plan was created, in Unix timestamp format (integer).
UpdateDate	The date this trip plan was most recently updated, in Unix timestamp format (integer).
Duration	The number of days this trip plan covers (integer).
Image	The image used to identify this trip plan. See Image Elements for element descriptions (element). Child elements: Url, Width, Height
Geocode	The location for the destination for this trip plan. See Geocode Elements for element descriptions (element).
Url	The URL of the trip plan on Yahoo! Travel Trip Search (string).

Image Elements

The image element describes the image or icon used to identify the trip plan. The image element can be contained inside the Result element.

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).

Geocode Elements

The geocode element describes the location of a destination or an item.

Element	Description
Geocode	The parent element for the location (element). Child elements: Latitude, Longitude Attribute: precision: the precision of the geocoder, or "not available".
Latitude	The latitude of the location (float).
Longitude	The longitude of the location (float).

Examples

To get a list of trip plans created by the user with the Yahoo ID YDNgeek: (the first ten are returned):

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&yahooid=YDNgeek

To get a list of trip plans created by YDNgeek (the first 20 are returned):

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&yahooid=YDNgeek &results=20

To get a list of trip plans created by YDNgeek (the second 20 are returned):

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&yahooid=YDNgeek&results=20 &start=21

To get a list of trip plans containing the word "mardi gras":

http://travel.yahooapis.com/ TripService/V1/tripSearch? appid=YahooDemo&query=mardi%20gras

To get a list of trip plans containing the word "mardi gras", and get JSON output wrapped in a callback function called get_plan:

http://travel.yahooapis.com TripService/V1/tripSearch? appid=YahooDemo&query=mardi%20gras &output=json&callback=get_plan

A sample XML response is shown below:

<?xml version="1.0" encoding="utf-8" ?>

<ResultSet firstResultPosition="1" totalResultsAvailable="218" totalResultsReturned="2" xmlns="urn:yahoo:travel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:yahoo:travel http://travel.yahooapis.com/TripService/V1/TripSearchResponse.xsd">

    <Result id="397415">

        <YahooID>YDNgeek</YahooID>

        <Title>Paris, France</Title>

        <Summary>Things to do: Musee du Louvre, Cathedrale ... </Summary>

        <Destinations>Paris</Destinations>

        <CreateDate>1134572151</CreateDate>

        <Duration>7</Duration>

        <Image>

            <Url>http://us.i1.yimg.com/us.yimg.com/i/travel/tg/lp/a9/100x100_a963e6ad7aa4caee31c99370f7a60aaa.jpg</Url>

            <Height>65</Height>

            <Width>100</Width>

        </Image>

        <Url>http://travel.yahoo.com/trip/?pid=1234&action=view</Url>

    </Result>

    <Result id="398901">

        <YahooID />

        <Title>Paris</Title>

        <Summary>Things to do: Cathedrale Notre-Dame de Par... Hotel: Le Meridien Etoile</Summary>

        <Destinations>Paris</Destinations>

        <CreateDate>1134617729</CreateDate>

        <Duration>7</Duration>

        <Image>

            <Url>http://us.i1.yimg.com/us.yimg.com/i/travel/tg/lp/93/100x100_93021ee4843ab4aa53b50b56dececbfd.jpg</Url>

            <Height>100</Height>

            <Width>67</Width>

        </Image>

        <Url>http://travel.yahoo.com/trip/?pid=4567&action=view</Url>

    </Result>

</ResultSet>

Errors

The Yahoo! Travel Web Services return the standard errors. See Error Messages for details.

Note that it may take an hour or two after you create a trip plan before that trip plan is available to the Yahoo! Travel Web Services.

Rate Limit

The Yahoo! Travel Web Services are limited to 5,000 queries per IP address per day. See Rate limiting for details.

Acceptable Use

The Yahoo! Travel services are limited to non-commercial use only. See information on our Usage Policy to learn about acceptable uses.

Support & Community

The Yahoo! Travel Trip Search web service is part of Yahoo! Travel Web Services which are discussed on the yws-travel mailing list.