Developer Network Home - Help

Yahoo! Travel Web Services: Trip Search

Version 1 Travel Web Services: Trip Search

The Yahoo! Travel Trip Search service enables you to search for public trip plans created with the Yahoo! Travel Trip Planner through a REST-like API. With this web service you can get a list of trip plans based on specific criteria including Yahoo! ID of the user who created the plan. Only trip plans that have been defined as public can be retrieved using Yahoo! Travel Trip Search. Use the information from this search to retrieve more information about a plan with the Get Trip service.

To use the Trip Search service you will need an application ID to identify your application. See What is An Application ID in the FAQ for more informaton on application IDs.

This page describes the format of the tripSearch request URL and the response for developers. It contains these sections:

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:

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.

Copyright © 2005-2006 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings