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 Get Trips service will need an application ID to identify your application. See What is An Application ID in the FAQ for more information on application IDs.
This page describes the format of the tripSearch request URL and the response for developers.
The Yahoo! Travel Trip Search request (tripSearch) follows standard HTTP GET syntax. See constructing REST queries for details.
Request URL
http://travel.yahooapis.com/TripService/V1.1/tripSearch?
Request parameters
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.1/tripSearch?appid=YahooDemo&query=paris
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.1/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
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.
| Parameter | Value | Description |
|---|---|---|
| appid | string (required) | An identifier for your application See Application IDs for more information. |
| query | string | Search keyword(s). Public trip plans that contain the given text in the title, description or tags are returned. |
| 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 elements
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.1/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:
|
| Result | Parent element for individual trip plan results (element). Child elements: Author, 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: Author, Title, Summary, Destinations, CreateDate, UpdateDate, Duration, Image, Geocode, Url Attribute: id: The ID of the trip plan. |
| Author | The Yahoo! 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). |
Sample response
To get a list of trip plans containing the word "mardi gras":
http://travel.yahooapis.com/TripService/V1.1/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:
Rate Limits
The Yahoo! Travel Web Services are limited to 5,000 queries per IP address per day. See Rate limiting for details.
Terms of Use
The Yahoo! Travel services are limited to non-commercial use only. See information on our Usage Policy to learn about acceptable uses.
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.
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.
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
Re: How can I query the current lowest airfare for a specified fligh
Fri, 12 Oct 2007
How can I query the current lowest airfare for a specified flight
Fri, 12 Oct 2007
Re: A question about Location ID
Fri, 21 Sep 2007
Re: A question about Location ID
Thu, 20 Sep 2007
Send Your Suggestions