Yahoo! Travel Web Services: Get Trip

REST Request

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

The base URL for getTrip is:

http://travel.yahooapis.com/TripService/V1.1/getTrip?

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

Summary

For the getTrip REST request there are four parameters:

appid for the application ID.
id for the ID of the trip plan 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. You can use YahooDemo as a sample appid for testing. See Requesting an Application ID for information on requesting your own application ID.

The id is the ID of the trip plan, created in Yahoo! Travel Trip Planner, that you want to retrieve. You can find out the ID of the trip to retrieve using the Trip Search Web Service. Note that the trip plan you are retrieving must have been defined to be a public trip plan.

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.
id	integer (required)	The ID of the trip plan to retrieve. You can find out the ID of the trip you want to find using The Trip 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! Travel Get Trip REST response conforms to XML 1.0. The schema document for this response is located at http://travel.yahooapis.com/TripService/V1.1/GetTripResponse.xsd

Top-Level Elements

Element	Description
xml	The Yahoo! Travel Get Trip conforms to XML 1.0. No child elements.
Result	Parent element for the result. Child elements: Author, Title, Summary, CreateDate, UpdateDate, Duration, Image, Tag, Destination

Result Elements

The result element contains information about the trip plan and its contents.

Element	Description
Result	The parent element for the trip plan (element). Attribute: id: The trip plan ID. Child elements: Author, Title, Summary, CreateDate, UpdateDate, Duration, Image, Tag, Destination
Author	The user who created this trip plan. (string)
Title	The title of the trip plan, for example "Paris Vacation in June " (string).
Summary	The overall description of the trip plan, for example "Two weeks in Paris June 15-30 " (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
Tag	A tag associated with this result. If the result contains multiple tags there are multiple tag elements. (string).
Destination	The parent element for trip plan destinations and items. If the result contains multiple destinations there are multiple Destination elements. See Destination Elements for element descriptions. Child elements of Destination: Title, Geocode, AirportCode, WeatherCode, Item

Destination Elements

Destinations represent places to go on the trip. Each destination element describes a destination for the trip plan, including its name, geocode location, airport code, as well as specific items (places to stay, things to do, and so on) while at that destination). A trip plan can contain multiple Destination elements.

Element	Description
Destination	The parent element for a destination (element). Child elements: Title, Geocode, AirportCode, WeatherCode, Item
Title	The title of the destination, for example "Paris" (string).
Geocode	The location for the destination. See Geocode Elements for element descriptions (element).
AirportCode	The airport code for the destination. (string)
WeatherCode	The weather location ID code for the destination. (string). You can use this code to look up the current weather conditions and forecast for the destination on Yahoo! Weather.
Item	One or more scheduled things to do, places to stay, and so on, for the destination. See Item Elements for element descriptions. Child elements of item: Title, Description, Category, Image, Geocode, Address, Phone, Url, Note, UserRating, Tag

Item Elements

Items represent different activities and points of interest for a destination: hotels, things to do, 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 trip plan (element). Child Elements: Title, Description, Category, Image, Geocode, Address, Phone, Url, Note, UserRating, Tag Attributes: id: The unique ID of the item
Title	The title for this item (string)
Summary	A summary of the item (string)
Category	The category of this item. Possible categories are Transportation, City, Entertainment, Flight, Hotel, Other, Restaurant, Shopping, Things to do (string).
Image	The image used to identify this item. See Image Elements for element descriptions (element). Child elements: Url, Width, Height
Geocode	The location associated with this item, if available. See Geocode Elements for element descriptions (element).
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)
Note	A note associated with the item (string)
UserRating	The user rating for this item, if available (integer)
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 trip plan 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).

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

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

Examples

To retrieve a trip plan with the ID of 507115:

http://travel.yahooapis.com/TripService/V1.1/getTrip?appid=YahooDemo&id=507115

To retrieve a trip plan with the ID of 507115, and get JSON output (instead of XML):

http://travel.yahooapis.com/TripService/V1.1/getTrip?appid=YahooDemo&id=507115&output=json

To retrieve a trip plan with the ID of 507115, and get JSON output wrapped in a callback function named blasmo:

http://travel.yahooapis.com/TripService/V1.1/getTrip?appid=YahooDemo&id=507115&output=json&callback=blasmo

A sample XML response is shown below:

<?xml version="1.0" encoding="utf-8" ?>
<Result id="393091" xmlns="urn:yahoo:travel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:yahoo:travel http://travel.yahooapis.com/TripsService/V1.1/GetTripResponse.xsd">
    <Author>YDNgeek</Author>
    <Title>Trip Home to Boston</Title>
    <Summary>Home again</Summary>
    <CreateDate>1134068274</CreateDate>
    <UpdateDate>1134341463</UpdateDate>
    <Duration>1</Duration>
    <Image>
        <Url>http://us.i1.yimg.com/us.yimg.com/i/travel/hg/tcy_mmh/95/75x75_95622245ec1f09cc85167f26cb8bcffa.jpg</Url>
        <Height>50</Height>
        <Width>75</Width>
    </Image>
    <Destination>
        <Title>Boston</Title>
        <Geocode precision="not available">
            <Latitude>42.358028</Latitude>
            <Longitude>-71.060417</Longitude>
        </Geocode>
        <AirportCode>bos</AirportCode>
        <WeatherCode>USMA0046</WeatherCode>
        <Item id="567416">
            <Title>The Westin Copley Place Boston</Title>
            <Summary>Historic Back Bay overlooking Copley Square in downtown Boston</Summary>
            <Category>Hotel</Category>
            <Image>
                <Url>http://us.i1.yimg.com/us.yimg.com/i/travel/hg/tcy_mmh/95/75x75_95622245ec1f09cc85167f26cb8bcffa.jpg</Url>
                <Height>50</Height>
                <Width>75</Width>
            </Image>
            <Geocode precision="not available">
                <Latitude>42.348770</Latitude>
                <Longitude>-71.077324</Longitude>
            </Geocode>
            <Address>
                <Address1>10 Huntington Ave</Address1>
                <Address2 />
                <City>Boston</City>
                <State>MA</State>
                <Country>United States</Country>
                <PostalCode>02116-5707</PostalCode>
                <Neighborhood>Back Bay</Neighborhood>
            </Address>
            <Phone>617-262-9600</Phone>
            <Url>http://travel.yahoo.com/p-hotel-322871-the_westin_copley_place_boston-i</Url>
            <Tag>foo</Tag>
            <Tag>bar</Tag>
            <Tag>test</Tag>
        </Item>
    </Destination>

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 Get Trip web service is part of Yahoo! Travel Web Services which are discussed on the yws-travel mailing list.