TripIt API Documentation - v1

Index

• Overview
• Authentication
• Encoding
• Resource URLs
• HTTP Status Codes
• Request/Response Objects
• TripIt Pro Data
• Deprecation Policy
• Release Notes
• Example

Overview

The TripIt API allows a developer to programatically create, delete, and retrieve objects from the TripIt platform. The v1 API supports all of the object types that the TripIt platform is currently capable of managing. The list of object types is as follows:

• AirObject
• ActivityObject
• CarObject
• CruiseObject
• DirectionsObject
• LodgingObject
• MapObject
• NoteObject
• ProfileObject
• RailObject
• RestaurantObject
• TransportObject
• TripObject
• WeatherObject read-only

In addition to being capable of directly creating, deleting, and retrieving these objects the API can retrieve lists of objects such as all of a user's upcoming trips or all travel objects contained within a specific trip.

For status on maintenance windows and operational issues related to the API please go to our status blog at status.tripit.com.

Authentication

Web Authentication

The TripIt API offers a very simple way of authenticating the API that should only be used for testing and development purposes. When building an application you should ultimately use the OAuth authentication scheme for allowing TripIt users to grant access to their data for your application. Note that this authentication scheme is off by default for every TripIt user. If you want to have this turned on for your account so you can use it for development purposes please send email to support@tripit.com. Enabling Basic Authentication for an account does not disable OAuth authentication for that same account.

The web authentication scheme relies on HTTP's authentication RFC to authenticate clients of the TripIt API using a TripIt username (i.e. email address) and password. This authentication scheme may be limited or turned off by default in future versions of the TripIt platform and therefore should not be relied upon for production application development. It is a very simple and useful way to get started with the API.

To make a web authenticated request of the API simply add the following HTTP header into the request:

Authorization: Basic <base64 encoded token>

Where <token> is a base64 encoded string that includes the TripIt user's email address and password separated by a colon (i.e. example@example.com:secretpassword). Here is an example:

TripIt user example@example.com has a password of secretpassword. A client trying to authenticate with the API as this user would send the following HTTP Authorization header with each request:

Authorization: Basic ZGVubWFya0B0cmlwaXQuY29tOnNlY3JldHBhc3N3b3Jk

The API does not manage sessions so it is required that a client send the user's credentials on every request.

Web Authentication Example

Here is a simple example of how you might use curl to query the API via the web authentication scheme:

        $ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/list/trip
        HTTP/1.1 200 OK
        Server: nginx/0.6.32
        Date: Wed, 03 Dec 2008 21:55:59 GMT
        Content-Type: text/xml; charset=utf-8
        Transfer-Encoding: chunked
        Connection: keep-alive
        Expires: Thu, 19 Nov 1981 08:52:00 GMT
        Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
        Pragma: no-cache

        <Response>
          <Trip>
            <id>770827</id>
            <start_date>2008-12-17</start_date>
            <end_date>2008-12-27</end_date>
            <display_name>New York, NY, December 2008</display_name>
            <image_url>/images/places/general.jpg</image_url>
            <is_private>false</is_private>
            <is_traveler>true</is_traveler>
            <primary_location>New York, NY</primary_location>
          </Trip>
        </Response>
        $

OAuth

References

For more information about the OAuth specification the following references are useful:

• OAuth Specification
• Reference Implementations
• Beginner's Guide to OAuth - Part I: Overview
• Beginner's Guide to OAuth - Part II : Protocol Workflow
• Beginner's Guide to OAuth - Part III : Security Architecture
• Beginner's Guide to OAuth - Part IV: Signing Requests
• How to Build an OAuth Consumer

It is beyond the scope of this document to describe the fundamental concepts of the OAuth specification. It is recommended that anyone trying to implement an OAuth Consumer of the TripIt API should be familiar with the documentation listed in the 'References' section as the rest of the documentation is written assuming the reader understands OAuth terminology and concepts. The following 4 steps is heavily modeled on the OAuth 1.0 specification document itself. The similarities are not a coincidence and each step tracks back to the relevant section in the spec so the reader can more easily follow along.

Consumer Storage Requirements

During the following steps you will need to store data from the consumer and associate it with the user account in the consumer. Here's a summary of what the consumer needs to store, when it needs to store it, and for how long.

What	When	Until	Description
oauth_token (request token)	After Step 1	After Step 3	This is the public part of the request token and is needed to obtain user authorization (step 2) and obtain an authorized access token (step 3). After step 3 it can be safely discarded and replaced with its authorized counterpart.
oauth_token_secret (request token)	After Step 1	After Step 3	This is the private part of the request token and is needed to obtain user authorization (step 2) and obtain an authorized access token (step 3). After step 3 it can be safely discarded and replaced with its authorized counterpart.
oauth_token (authorized access token)	After step 3	Indefinitely	This is the public part of the authorized access token that a consumer needs to access protected resources on behalf of a TripIt user. If all goes well and the TripIt user grants access to the consumer the consumer should be able to obtain this after step 3. It should be stored indefinitely and associated with the user's account on the consumer.
oauth_token_secret (authorized access token)	After step 3	Indefinitely	This is the private part of the authorized access token that a consumer needs to access protected resources on behalf of a TripIt user. If all goes well and the TripIt user grants access to the consumer the consumer should be able to obtain this after step 3. It should be stored indefinitely and associated with the user's account on the consumer.

Step 1: Obtaining a Request Token (Section 6.1)

To obtain a request token POST the following request parameters to the URL:

https://api.tripit.com/oauth/request_token

parameter name	parameter description
oauth_consumer_key	The Consumer's public key.
oauth_nonce	A nonce no more than 80 characters in length.
oauth_signature	The signature of the request. The algorithm to sign the request is described in the OAuth specification and examples can be found in the reference implementations.
oauth_signature_method	The method used to generate the method signature. Current supported methods are HMAC-SHA1.
oauth_timestamp	The timestamp in seconds since the epoch.
oauth_version	OPTIONAL - Assumed to be '1.0'

The server will respond with the following in the response body:

oauth_token=7d41de0eaf0d518786851a64bf7505e29177b75e&oauth_token_secret=2e8c29e961d02a1aa61b916c908c90200fcdef7e

These are the unauthorized access token and secret that will be needed to obtain user authorization in step 2. The Consumer should store both values for future use.

Step 2: Obtain User Authorization (Section: 6.2)

Using the unauthorized access token obtained in step 1 the Consumer application should redirect the user to the following page:

https://www.tripit.com/oauth/authorize?oauth_token=<oauth_token>&oauth_callback=<oauth_callback>

Alternatively, if you are trying to authorize on a mobile app such as an iPhone, direct the user to here:

https://m.tripit.com/oauth/authorize?oauth_token=<oauth_token>&oauth_callback=<oauth_callback>

The two request parameters have the following meaning:

NOTE: It is extremely important that you clearly redirect the user to the TripIt URL so they have confidence that they aren't being phished for their TripIt username and password. This means you should make sure on a regular browser that the frame you use to redirect the user has the address bar of the frame clearly visible. On a mobile device such as an iPhone you should launch Safari and not use the embedded WebView class.

parameter name	parameter description
oauth_callback	This is the callback URL that TripIt will use upon successful access token authorization. This parameter is optional if you associated a URL with your application when you registered it and obtained your OAuth consumer key and secret. If you supplied a URL when you registered the application, providing this request parameter will override that value. If neither the application URL is set nor the oauth_callback parameter is supplied the user will get an error when taken to the /oauth/authorize page and will be unable to authorize the access token. It is highly encouraged that you explicitly provide an oauth_callback URL when linking to the /oauth/authorize page. Providing this URL gives you the flexibility of defining a different URL that is associated with your action on which you can provide marketing text and a description of your application and what it does.
oauth_token	The oauth_token obtained in step 1. This is the access token the Consumer will now be trying to get the user of to authorize.

If the user is able to successfully log in to TripIt and chooses to grant authority to the Consumer application (or not), the user is redirected back to the oauth_callback or default URL with a single request parameter: oauth_token. At this point the Consumer does not know whether or not the oauth_token has been successfully authorized. To find out, the Consumer must implement step 3.

Step 3: Obtaining an Access Token (Section 6.3)

To obtain an authorized access token, POST the following request parameters to the URL:

https://api.tripit.com/oauth/access_token

parameter name	parameter description
oauth_consumer_key	The Consumer's public key.
oauth_nonce	A nonce no more than 80 characters in length.
oauth_signature	The signature of the request. The algorithm to sign the request is described in the OAuth specification and examples can be found in the reference implementations.
oauth_signature_method	The method used to generate the method signature. Current supported methods are HMAC-SHA1.
oauth_timestamp	The timestamp in seconds since the epoch.
oauth_token	The request token obtained in Step 1.
oauth_token_secret	The request token secret obtained in Step 1.
oauth_version	OPTIONAL - Assumed to be '1.0'

The server will respond with the following in the response body:

oauth_token=c174450a65d9d5e72de2910fed22fb8879fb1439&oauth_token_secret=1d1291e53cf3f9e89c377109f0ccee244a95d273

These are the authorized access token and secret that will be needed to make future API requests on behalf of the user that authorized them. The Consumer should store both values until the user asks for the Consumer to forget about them either directly or indirectly (e.g. the user delete's their account with the Consumer application).

Step 4: Accessing Protected Resources (Section: 7)

Once the Consumer has obtained an authorized access token from the service provider it can now make requests of the API on behalf of the user that authorized the acccess token. To make an OAuth authenticated request send the following parameters in the Authorization header of the request:

        Authorization: OAuth realm="https://api.tripit.com/",
          oauth_consumer_key="consumer public key",
          oauth_token="authorized access token",
          oauth_signature_method="HMAC-SHA1",
          oauth_signature="request signature",
          oauth_timestamp="1229622199",
          oauth_nonce="9b308304f41a4ac04fb4c4ce980c5277",
          oauth_version="1.0"

The parameters in the Authorization header are defined as follows:

parameter name	parameter description
oauth_consumer_key	The consumer's public key.
oauth_nonce	A nonce no more than 80 characters in length.
oauth_signature	The signature of the request. The algorithm to sign the request is described in the OAuth specification and examples can be found in the reference implementations.
oauth_signature_method	The method used to generate the method signature. Current supported methods are HMAC-SHA1.
oauth_timestamp	The timestamp in seconds since the epoch.
oauth_token	The authorized access token obtained in Step 3.
oauth_version	OPTIONAL - Assumed to be '1.0'

All other aspects of a successfully authenticated OAuth request are identical to a web authenticated request except that the authorized access token may grant the consumer less permission to read, create, and modify data than a web authenticated request which has the exact same permissions a user has when logged in to TripIt via the web.

Encoding

The TripIt API expects all data to be encoded in UTF-8. Similarly, all data out of the API will be encoded in UTF-8.

All data POSTed to the API must also be URL encoded.

Resource URLs

There are currently four types of requests supported by the API (get, list, create, and delete). Each is explained below in greater detail.

Common Query Parameters

There is one common query parameter: 'format'. It can be set to 'xml' or 'json' depending on what format the Request/Response objects are in. Note: If 'format' is not specified, 'xml' is assumed as the default.

Even thought the default format is XML, we recommend JSON over XML. Using the JSON format will reduce the size of the response data by a large factor: 50% or more. Adding "Accept-Encoding: gzip" to the HTTP request headers will also reduce the size of the response by a large factor. Finally, please add an appropriate "User-agent" to the request headers with the name and version of your application.

get

A get request is used to retrieve a specific object from the TripIt API given its TripIt object ID. Since get requests do not change data they are all made via an HTTP GET request for a URL that takes the following form:

https://api.tripit.com/v1/get/<object type>/id/<TripIt Object ID>

<object type> is one of the following strings:

• air
• activity
• car
• cruise
• directions
• lodging
• map
• note
• profile
• rail
• restaurant
• transport
• trip
• weather

<TripIt Object ID> is the object ID of the TripIt object being requested.

The get request for a trip object can take an optional filter parameter called include_objects. The default value for this parameter is false but if it is set to true then the response from the API will include all objects (e.g. air, car, lodging, etc...) that are associated with that trip. This enables an API client to request a trip and all of its associated objects in a single call.

Example:

Here is a sample get request for a Note object:

$ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/get/note/id/586853
HTTP/1.1 200 OK
Server: nginx/0.6.32
Date: Wed, 03 Dec 2008 23:05:30 GMT
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache

<Response>
  <NoteObject>
    <id>586853</id>
    <display_name>Note</display_name>
    <DateTime>
      <date>2008-12-09</date>
      <time>14:00:00</time>
      <timezone>America/Los_Angeles</timezone>
      <utc_offset>-8:00</utc_offset>
    </DateTime>
    <Address>
      <addr1>444 DeHaro St.</addr1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94107</zip>
      <country>US</country>
      <latitude>37.764169</latitude>
      <longitude>-122.402021</longitude>
    </Address>
    <text>Test note.</text>
    <url>http://www.tripit.com/</url>
  </NoteObject>
</Response>
$

Here is another example using the include_objects filter parameter set to true. Notice how you get the <Trip> plus the <AirObject>, and <WeatherObject> sections that are associated with the trip.

$ curl -D /dev/tty --user <username>:<password> 'https://api.tripit.com/v1/get/trip/id/2785341/include_objects/true'
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 03 Nov 2009 00:31:35 GMT
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: close
Cache-Control: private

<Response>
  <timestamp>1257208295</timestamp>
  <num_bytes>4630</num_bytes>
  <Trip>
    <TripInvitees>
      <Invitee profile_ref="VPNrwg9_2vW2j3DHX_pAzA">
        <is_read_only>false</is_read_only>
        <is_traveler>true</is_traveler>
      </Invitee>
    </TripInvitees>
    <id>2785341</id>
    <relative_url>/trip/show/id/2785341</relative_url>
    <start_date>2009-10-04</start_date>
    <end_date>2009-11-23</end_date>
    <display_name>Vienna, Austria, October 2009</display_name>
    <image_url>http://www.tripit.com/images/places/general.jpg</image_url>
    <is_private>true</is_private>
    <primary_location>Vienna, Austria</primary_location>
  </Trip>
  <AirObject>
    <id>4042627</id>
    <trip_id>2785341</trip_id>
    <is_client_traveler>true</is_client_traveler>
    <relative_url>/reservation/show/id/4042627</relative_url>
    <display_name>Your Flight</display_name>
    <is_purchased>true</is_purchased>
    <Segment>
      <Status>
        <EstimatedDepartureDateTime>
          <date>2009-11-09</date>
          <time>13:45:00</time>
          <timezone>America/Los_Angeles</timezone>
          <utc_offset>-08:00</utc_offset>
        </EstimatedDepartureDateTime>
        <EstimatedArrivalDateTime>
          <date>2009-11-09</date>
          <time>14:45:00</time>
          <timezone>America/Chicago</timezone>
          <utc_offset>-06:00</utc_offset>
        </EstimatedArrivalDateTime>
        <flight_status>401</flight_status>
        <is_connection_at_risk>false</is_connection_at_risk>
        <last_modified>1256770662</last_modified>
      </Status>
      <StartDateTime>
        <date>2009-11-09</date>
        <time>13:00:00</time>
        <timezone>America/Los_Angeles</timezone>
        <utc_offset>-08:00</utc_offset>
      </StartDateTime>
      <EndDateTime>
        <date>2009-11-09</date>
        <time>14:00:00</time>
        <timezone>America/Chicago</timezone>
        <utc_offset>-06:00</utc_offset>
      </EndDateTime>
      <start_airport_code>SFO</start_airport_code>
      <start_airport_latitude>37.618889</start_airport_latitude>
      <start_airport_longitude>-122.375</start_airport_longitude>
      <start_city_name>San Francisco</start_city_name>
      <end_airport_code>ORD</end_airport_code>
      <end_airport_latitude>41.978056</end_airport_latitude>
      <end_airport_longitude>-87.906111</end_airport_longitude>
      <end_city_name>Chicago</end_city_name>
      <marketing_airline>Other</marketing_airline>
      <marketing_flight_number>1234</marketing_flight_number>
      <alternate_flights_url>/trip_item/flightSearch/id/19691175/airline_code/UA</alternate_flights_url>
    </Segment>
  </AirObject>
  <WeatherObject>
    <id>19720471</id>
    <trip_id>2785341</trip_id>
    <is_client_traveler>true</is_client_traveler>
    <relative_url>/trip_item/show/id/19720471</relative_url>
    <display_name>Weather - Chicago, IL</display_name>
    <date>2009-11-23</date>
    <location>Chicago, IL</location>
    <avg_high_temp_c>8.8888888888889</avg_high_temp_c>
    <avg_low_temp_c>2.7777777777778</avg_low_temp_c>
    <avg_wind_speed_kn>13</avg_wind_speed_kn>
  </WeatherObject>
  <Profile ref="VPNrwg9_2vW2j3DHX_pAzA">
    <is_client>true</is_client>
    <is_pro>true</is_pro>
    <screen_name>denmark</screen_name>
    <public_display_name>Andy Denmark</public_display_name>
    <profile_url>people/denmark</profile_url>
    <home_city>San Francisco, CA</home_city>
    <photo_url>http://static.tripit.com/uploads/images/9/7/3/97319d8fb7045feb31172d9d7a6481f4608.jpg</photo_url>
    <activity_feed_url>http://www.tripit.com/feed/activities/private/24562ADE-7DF3452DABC4E7D7FF372C1ACC/activities.atom</activity_feed_url>
    <alerts_feed_url>http://www.tripit.com/feed/alerts/private/962356AA5-F101FC24E1C124532ACDE28C356AFB0/alerts.atom</alerts_feed_url>
    <ical_url>webcal://www.tripit.com/feed/ical/private/96333224-33BA6E42F4ABCDDEFG12347E5EDA66/tripit.ics</ical_url>
  </Profile>
</Response>
$

list

A list request is used to retrieve multiple objects given an object type and set of filter parameters. Since list requests do not change data they are all made via an HTTP GET request for a URL that takes the following form:

https://api.tripit.com/v1/list/<object type>/<filter parameter>/<filter value>

<object type> is one of the following strings:

• trip
• object

Valid values for <filter parameter> and <filter value> depend on the <object type>. The following table describes the valid combinations:

object type	filter parameter	filter value	default value	explanation
trip	-	-	-	Returns a list of upcoming trips on which the authenticated user may or may not be a traveler.
trip	traveler	true|false|all	true	Conditionally returns trips on which the authenticated user is (true) or is not (false) a traveler. If the value of this parameter is set to all then trips on which the user is and is not a traveler are returned. Whether or not the user created the trip or was invited to view and/or collaborate on the trip has no bearing on whether or not the user is determined to be a traveler on the trip.
trip	past	true|false	false	Returns past trips if set to true. Setting this to false just mimics the default behavior. A past trip is defined to be any trip whose end_date is before today's date with respect to the America/Los_Angeles timezone. All other trips, including un-dated ones, are defined to be future trips.
trip	modified_since	Integer value	-	Each Response object has a <timestamp> that may be stored by a client. If the client re-issues a request with the modified_since parameter and the timestamp from the prior invocation of the request only the trip objects that have been updated and/or created since the first invocation will be returned. Note: deleted objects will not be considered as a change when computing the list of objects in the response. Therefore, a client should periodically sync the entire object cache, avoiding the modified_since parameter.
trip	include_objects	true|false	false	If set to true then all of the trips that are included in the <Response> will be accompanied by their associated travel objects. This is useful for clients that would otherwise need to make multiple calls to obtain a list of trips and then associated trip objects (e.g. air, car, lodging, etc...).
object	-	-	-	Returns a list of all upcoming travel objects whether or not they are associated with a trip. Undated travel objects are assumed to have dates that are very far out in the future and therefore are also returned. If the travel objects are associated with a trip then they will only be returned if the account making the query is listed as a traveler on the trip or if the trip is shared with this account.
object	trip_id	The TripIt ID for a Trip object	-	Returns a list of all travel objects in the Trip object specified. If trip_id is specified then the past and traveler filters are ignored.
object	past	true|false	false	Returns past travel objects if set to true. Setting this to false just mimics the default behavior. A past travel object is defined to be any object whose end_date is before yesterday's date with respect to the America/Los_Angeles timezone. All other objects, including un-dated ones, are defined to be future objects.
object	traveler	true|false|all	true	Conditionally returns travel objects associated with trips on which the authenticated user is (true) or is not (false) a traveler. If the value of this parameter is set to all then objects associated with trips on which the user is and is not a traveler are returned. Whether or not the user created the trip or was invited to view and/or collaborate on the trip has no inherent bearing on whether or not the user is determined to be a traveler on the trip. Travel objects that are not associated with a Trip (i.e. Unfiled Items) are included in the result set when traveler=false.
object	type	air|activity|car|cruise| directions|lodging|map|note| rail|restaurant|transport|weather	-	Filter based on travel object type. The absence of this parameter implies that all travel object types will be returned.
object	modified_since	Integer value	-	Each Response object has a <timestamp> that may be stored by a client. If the client re-issues a request with the modified_since parameter and the timestamp from the prior invocation of the request only the travel objects that have been updated and/or created since the first invocation will be returned. Note: deleted objects will not be considered as a change when computing the list of objects in the response. Therefore, a client should periodically sync the entire object cache, avoiding the modified_since parameter.

Example:

Here is a sample list request for a Trip object:

      $ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/list/trip
      HTTP/1.1 200 OK
      Server: nginx/0.6.32
      Date: Wed, 03 Dec 2008 23:10:45 GMT
      Content-Type: text/xml; charset=utf-8
      Transfer-Encoding: chunked
      Connection: keep-alive
      Expires: Thu, 19 Nov 1981 08:52:00 GMT
      Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
      Pragma: no-cache

      <Response>
        <Trip>
          <id>770827</id>
          <start_date>2008-12-17</start_date>
          <end_date>2008-12-27</end_date>
          <display_name>New York, NY, December 2008</display_name>
          <image_url>/images/places/general.jpg</image_url>
          <is_private>false</is_private>
          <is_traveler>true</is_traveler>
          <primary_location>New York, NY</primary_location>
        </Trip>
        <Trip>
          <id>770828</id>
          <start_date>2009-01-17</start_date>
          <end_date>2009-01-27</end_date>
          <display_name>Paris, France, January 2009</display_name>
          <image_url>/images/places/general.jpg</image_url>
          <is_private>false</is_private>
          <is_traveler>true</is_traveler>
          <primary_location>Paris, France</primary_location>
        </Trip>
      </Response>
      $

Another example in which we're requesting all objects within Trip #115 that are of type air.

      $ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/list/object/trip_id/115/type/air
      HTTP/1.1 200 OK
      Server: nginx/0.6.35
      Date: Thu, 07 May 2009 22:00:08 GMT
      Content-Type: text/xml; charset=utf-8
      Transfer-Encoding: chunked
      Connection: close
      Cache-Control: private

      <Response>
        <timestamp>1241733608</timestamp>
        <AirObject>
        <id>319</id>
        <trip_id>115</trip_id>
        <is_traveler>true</is_traveler>
        <relative_url>/reservation/show/id/319</relative_url>
        <display_name>Your Flight</display_name>
        <is_purchased>true</is_purchased>
        <Segment>
          <StartDateTime>
            <date>2009-05-27</date>
            <time>06:15:00</time>
            <timezone>America/Los_Angeles</timezone>
            <utc_offset>-07:00</utc_offset>
          </StartDateTime>
          <EndDateTime>
            <date>2009-05-27</date>
            <time>08:20:00</time>
            <timezone>America/Los_Angeles</timezone>
            <utc_offset>-07:00</utc_offset>
          </EndDateTime>
          <start_airport_code>SFO</start_airport_code>
          <start_city_name>San Francisco</start_city_name>
          <end_airport_code>SEA</end_airport_code>
          <end_city_name>Seattle</end_city_name>
          <marketing_airline>United Airlines</marketing_airline>
          <marketing_airline_code>UA</marketing_airline_code>
          <marketing_flight_number>24</marketing_flight_number>
          <aircraft>319</aircraft>
          <distance>677 miles</distance>
          <duration>2h, 05m</duration>
          <stops>nonstop</stops>
        </Segment>
      </AirObject>
    </Response>
    $

create

A create request is used to create new objects. To create objects, make an HTTP POST request to the following URL:

https://api.tripit.com/v1/create

The client must POST a single Request object as the value of the request parameter xml in the POST body of the request.

Example:

Here is a sample create request for a Trip object:

Here is what the post data would look like for a Trip creation:

        $ cat /var/tmp/trip.xml 
        xml=<Request>
              <Trip>
                <start_date>2008-12-09</start_date>
                <end_date>2008-12-27</end_date>
                <primary_location>New York, NY</primary_location>
              </Trip>
            </Request>
        $

Here is a sample create request for a Trip object:

        $ curl -k -D /dev/tty -d@/var/tmp/trip.xml --user <username>:<password> https://api.tripit.com/v1/create
        HTTP/1.1 200 OK
        Server: nginx/0.6.32
        Date: Fri, 05 Dec 2008 22:12:35 GMT
        Content-Type: text/xml; charset=utf-8
        Transfer-Encoding: chunked
        Connection: keep-alive
        Expires: Thu, 19 Nov 1981 08:52:00 GMT
        Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
        Pragma: no-cache

        <Response>
          <Trip>
            <id>770846</id>
            <start_date>2008-12-09</start_date>
            <end_date>2008-12-27</end_date>
            <display_name>New York, NY, December 2008</display_name>
            <image_url>/images/places/general.jpg</image_url>
            <is_private>false</is_private>
            <is_traveler>true</is_traveler>
            <primary_location>New York, NY</primary_location>
          </Trip>
        </Response>
        $

Here is a sample create request for a Air object:

Here is what the post data would look like for a Air object creation:

        $ cat /var/tmp/air.xml 
        xml=<Request>
              <AirObject>
                <is_client_traveler>true</is_client_traveler>
                <booking_site_name>United Airlines</booking_site_name>
                <booking_site_phone>1-800-United-1</booking_site_phone>
                <booking_site_url>http://www.united.com/</booking_site_url>
                <supplier_conf_num>ABC123</supplier_conf_num>
                <Segment>
                  <StartDateTime>
                  <date>2009-09-04</date>
                  <time>15:04:00</time>
                </StartDateTime>
                <EndDateTime>
                  <date>2009-09-04</date>
                  <time>17:47:00</time>
                </EndDateTime>
                <start_city_name>Chicago</start_city_name>
                <end_city_name>San Francisco</end_city_name>
                <marketing_airline>UA</marketing_airline>
                <marketing_flight_number>137</marketing_flight_number>
                <seats>23J</seats>
              </Segment>
              <Segment>
                <StartDateTime>
                  <date>2009-09-08</date>
                  <time>16:32:00</time>
                </StartDateTime>
                <EndDateTime>
                  <date>2009-09-08</date>
                  <time>22:42:00</time>
                </EndDateTime>
                <start_city_name>San Francisco</start_city_name>
                <end_city_name>Chicago</end_city_name>
                <marketing_airline>UA</marketing_airline>
                <marketing_flight_number>39</marketing_flight_number>
                <seats>19B</seats>
              </Segment>
              <Traveler>
                <first_name>John</first_name>
                <last_name>Doe</last_name>
                <frequent_traveler_num>1234567890</frequent_traveler_num>
              </Traveler>
            </AirObject>
          </Request>
       $

Here is a sample create request for a Air object:

        $ curl -k -D /dev/tty -d@/var/tmp/air.xml --user <username>:<password> https://api.tripit.com/v1/create
        HTTP/1.1 100 Continue

        HTTP/1.1 200 OK
        Server: nginx
        Date: Mon, 31 Aug 2009 23:51:39 GMT
        Content-Type: text/xml; charset=utf-8
        Transfer-Encoding: chunked
        Connection: close
        Cache-Control: private

        <Response>
          <timestamp>1251762699</timestamp>
          <num_bytes>2470</num_bytes>
          <AirObject>
            <id>1413</id>
            <trip_id>426</trip_id>
            <is_client_traveler>true</is_client_traveler>
            <relative_url>/reservation/show/id/1413</relative_url>
            <display_name>Your Flight</display_name>
            <booking_site_name>United Airlines</booking_site_name>
            <booking_site_phone>1-800-United-1</booking_site_phone>
            <booking_site_url>http://www.united.com/</booking_site_url>
            <supplier_conf_num>ABC123</supplier_conf_num>
            <is_purchased>true</is_purchased>
            <Segment>
              <Status>
                <flight_status>200</flight_status>
                <last_modified>1251762699</last_modified>
              </Status>
              <StartDateTime>
                <date>2009-09-04</date>
                <time>15:04:00</time>
                <timezone>America/Chicago</timezone>
                <utc_offset>-05:00</utc_offset>
              </StartDateTime>
              <EndDateTime>
                <date>2009-09-04</date>
                <time>17:47:00</time>
                <timezone>America/Los_Angeles</timezone>
                <utc_offset>-07:00</utc_offset>
              </EndDateTime>
              <start_airport_code>ORD</start_airport_code>
              <start_city_name>Chicago</start_city_name>
              <end_airport_code>SFO</end_airport_code>
              <end_city_name>San Francisco</end_city_name>
              <marketing_airline>United Airlines</marketing_airline>
              <marketing_airline_code>UA</marketing_airline_code>
              <marketing_flight_number>137</marketing_flight_number>
              <aircraft>763</aircraft>
              <aircraft_display_name>Boeing 767-300</aircraft_display_name>
              <distance>1841 miles</distance>
              <duration>4h, 43m</duration>
              <seats>23J</seats>
              <stops>nonstop</stops>
            </Segment>
            <Segment>
              <Status>
                <flight_status>200</flight_status>
                <last_modified>1251762699</last_modified>
              </Status>
              <StartDateTime>
                <date>2009-09-08</date>
                <time>16:32:00</time>
                <timezone>America/Los_Angeles</timezone>
                <utc_offset>-07:00</utc_offset>
              </StartDateTime>
              <EndDateTime>
                <date>2009-09-08</date>
                <time>22:42:00</time>
                <timezone>America/Chicago</timezone>
                <utc_offset>-05:00</utc_offset>
              </EndDateTime>
              <start_airport_code>SFO</start_airport_code>
              <start_city_name>San Francisco</start_city_name>
              <end_airport_code>ORD</end_airport_code>
              <end_city_name>Chicago</end_city_name>
              <marketing_airline>United Airlines</marketing_airline>
              <marketing_airline_code>UA</marketing_airline_code>
              <marketing_flight_number>39</marketing_flight_number>
              <aircraft>319</aircraft>
              <aircraft_display_name>Airbus A319</aircraft_display_name>
              <distance>1841 miles</distance>
              <duration>4h, 10m</duration>
              <seats>19B</seats>
              <stops>nonstop</stops>
            </Segment>
            <Traveler>
              <first_name>John</first_name>
              <last_name>Doe</last_name>
              <frequent_traveler_num>1234567890</frequent_traveler_num>
            </Traveler>
          </AirObject>
        </Response>
       $

Note the following about the response objects:

• The <Segment> objects have considerably more information in them as the TripIt platform "enriches" the <Segment> objects (e.g. <distance>, <aircraft>, etc...).
• The TripIt user this call was executed on behalf of has a TripIt pro account and so the <Segment> objects now have <Status> objects that indicate the current status of this flight.
• All the DateTime objects now have <timezone> and <utc_offset> as the TripIt platform was able to figure that out.

delete

A delete request is used to delete existing objects. To delete an object, make an HTTP GET request to the following URL:

https://api.tripit.com/v1/delete/<object type>/id/<TripIt Object ID>

<object type> is one of the following strings:

• air
• activity
• car
• cruise
• directions
• lodging
• map
• note
• rail
• restaurant
• transport
• trip

<TripIt Object ID> is the object ID of the TripIt object being requested.

Example:

Here is a sample delete request for a Trip object:

$ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/delete/trip/id/770829
HTTP/1.1 200 OK
Server: nginx/0.6.32
Date: Thu, 04 Dec 2008 04:49:08 GMT
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache


$

HTTP Status Codes

The API will return the following HTTP Status Codes:

status code	meaning	description
200	OK	Everything went well and while there might be Warnings or Errors in the Response Object, the request was processed.
400	Bad Request	The request was either invalid or malformed in some way. For example, a create call with no xml= request parameter in the POST args would return a 400 Bad Request from the server.
401	Unauthorized	The authentication credentials passed to the API for the request were somehow invalid. This status code could be caused by an invalid username/password combination used in the web authentication scheme or an invalid OAuth token for the OAuth scheme.
404	Not Found	Either the resource URL or the object the client was requesting either does not exist or the user the client was authenticated and does not have permission to operate on the object.
500	Server Error	Something catastrophic happened while the TripIt platform was trying to complete the request. A 500 error is a pretty serious and catastrophic problem that should be reported to the TripIt engineering team through support@tripit.com.
503	Service Unavailable	The TripIt API is currently undergoing maintenance and is not available.

Request/Response Objects

There are two types of documents used to communicate with the API. A Request document is used when the client is asking something of the API (e.g. create a new object, get me a list of Trip objects, etc...). A Response document is what the API will send back to the client with an answer to the Request. The XML Schema that describe valid Request and Response documents may be found here:

• tripit-api-obj-v1.xsd - describes all the travel objects
• tripit-api-req-v1.xsd - describes the Request object
• tripit-api-res-v1.xsd - describes the Response object

These schemas completely describe all of the valid XML documents that can be posted to and received from the API.

Request Object

Used for create operations, a Request object wraps one travel object in the xml parameter of an HTTP POST. Please note that a Request object may contain no more than one travel object.

If a travel object contains a trip_id then the object will be placed in the trip with the matching id. If a travel object does not contain a trip_id and the TripIt user has their 'auto-import' account preference set to 'On', the travel object will be inserted into the trip in the user's account that it overlaps with in time. If the travel object does not overlap with any trips, and the 'auto-import' feature is turned 'Off' then the it will be placed under 'Unfiled items'.

Response Object

A Response object is used to wrap one or more travel objects as well as one or more Warning and/or Error objects in a response from either a get, create, or delete request.

When creating a new object the response will contain the travel object you sent in plus the object IDs that they are now associated with that object. A client can use this ID in subsequent get operations.

Warning Object

The presence of a Warning in a Response object means that the TripIt API was able to complete the request successfully but the API detected something about the data in the Request object that may produce unintended consequences.

An example of a condition that would produce a Warning is if the Request object contained a check-in date for a LodgingObject that was after the check-out date for that LodgingObject.

TBD - document more of these

Error Object

The presence of an Error in a Response object means that the TripIt API was not able to persist the object in question in the Request. The entire request transaction will be failed.

TBD - document examples of these

Pro Data

Any TripIt API client that is authorized to request data from the API on behalf of a TripIt user that happens to be a TripIt Pro subscriber will automatically receive Pro data in the <Response> objects. The Pro data that is currently available in the API is limited to the following:

• AirObject :: AirSegment :: FlightStatus
• AirObject :: AirSegment :: alternate_flights_url

Each one of these is discussed in more detail below.

AirObject :: AirSegment :: FlightStatus

The FlightStatus object is defined here in the object XSD here: tripit-api-obj-v1.xsd. Here's a definition of all of the properties within the FlightStatus object:

Property	Definition
ScheduledDepartureDateTime	The originally scheduled departure date and time of the flight. Note: this DateTime value does not necessarily match the StartDateTime of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
EstimatedDepartureDateTime	The current estimated departure date and time of the flight.
ScheduledArrivalDateTime	The current scheduled arrival date and time of the flight. Note: this DateTime value does not necessarily match the EndDateTime of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
EstimatedArrivalDateTime	The current estimated arrival date and time of the flight.
departure_terminal	The current departure terminal information. Note: this property's value does not necessarily match the start_terminal of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
departure_gate	The current departure gate information. Note: this property's value does not necessarily match the start_gate of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
arrival_terminal	The current arrival terminal information. Note: this property's value does not necessarily match the end_terminal of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
arrival_gate	The current arrival gate information. Note: this property's value does not necessarily match the end_gate of the enclosing AirSegment object. That value is set by the user in either the UI or via the data found within the confirmation email that was used to create the flight.
layover_minutes	If layover_minutes is contained within the FlightStatus object contained with an AirSegment that isn't the last segment in a leg the value of layover_minutes will be the number of minutes between this segment's arrival time and the next segment's departure time.
baggage_claim	The current baggage claim area.
diverted_airport_code	If the flight was diverted, this is the three-letter IATA code of the new airport.
last_modified	This is the Unix time when the status of this flight was last updated.

There is one more property called flight_status that is a new object type that can have one of the following values:

Value	Name	Description
100	Not Monitorable	An AirSegment in this state is usually in this state because the TripIt platform doesn't have enough information about the flight to monitor it. The minimum set of required data needed to monitor a flight are valid values (i.e. a real flight) for the following properties of a AirSegment: marketing_airline marketing_flight_number StartDateTime start_airport_code end_airport_code In addition to containing values for these properties, the following must also be true for the flight to be monitorable: The AirObject must be contained within a trip that has at least one Pro account traveling on the trip The AirSegment hasn't already departed. The marketing flight number of the AirSegment must not have alpha characters (i.e. [A-Za-z]) in it The marketing flight number of the AirSegment must not have more than 4 digits The marketing airline code of the AirSegment must not have a value of "--" (Other)
200	Not Monitored	This flight is not being monitored even if it meets all of the criteria to be monitorable if the following conditions are true: The flight is either not a real flight or TripIt doesn't have a record of it in its database. If TripIt can't determine the current status of the flight
300	Scheduled	The flight is monitored but the TripIt platform hasn't seen any updates to the flight yet.
301	On Time	The flight is currently considered to be on time, which means that the (EstimatedDepartureDateTime - ScheduledDepartureDateTime) <= 14 minutes.
302	In Flight - On Time	The flight is currently in the air and is considered to be on time, which means that the (EstimatedArrivalDateTime - ScheduledArrivalDateTime) <= 14 minutes.
303	Arrived - On Time	The flight has arrived and the actual arrival time was within 14 minutes of the ScheduledArrivalDateTime.
400	Cancelled	The flight has been cancelled.
401	Delayed	The flight is currently considered to be on time, which means that the (EstimatedDepartureDateTime - ScheduledDepartureDateTime) >= 15 minutes.
402	In Flight - late	The flight is currently in the air and is considered to be on time, which means that the (EstimatedArrivalDateTime - ScheduledArrivalDateTime) >= 15 minutes.
403	Arrived - late	The flight has arrived and the actual arrival time was more than 14 minutes after the ScheduledArrivalDateTime.
404	Diverted	The flight was diverted to an airport other than the one it was originally going to fly into.

AirObject :: AirSegment :: alternate_flights_url

The alternate flights URL is a relative URL that a client application can use to provide alternate flight information for a specific AirSegment object. The URL can be used to reference the alternate flight information on both http://www.tripit.com/ and http://m.tripit.com/.

Deprecation Policy

This document describes the v1 version of the TripIt API. The v1 API may be continually updated in backwards-compatible ways that won't break v1 compliant clients. Backwards compatible means that the additions to the v1 API should not break a properly written v1 client. The types of changes that may be introduce include the addition of new methods, new object properties, and new travel objects. The types of changes that would not be possible in the v1 API would include things such as the changing of object names, object properties, or the removal of methods.

The v1 API will continue to be supported until the v2 API is released and has been available in production for some period of time. After the v2 API becomes available, the v1 API will be considered deprecated and all v1 clients should migrate to use the v2 API. Within a reasonable period of time after being deprecated, TripIt may decide it's necessary to turn off the v1 API after which point v1 clients will cease to function.

Any changes or deadlines for deprecation will be announced at the TripIt API Google group.

Release Notes

This section covers all outstanding known issues and/or known gotchas that aren't more appropriately described elsewhere.

• Not all travel objects will display an image sent in via the API. This is a limitation of the current TripIt UI and not the API. This may change in the future.
• The API makes no attempt to provide feedback on whether or not an input string is too long to fit in the database it is destined for. Therefore, truncation may happen silently.

Examples

TBD - we're going to include links to Hello, World type applications here