TripIt API Documentation - v1

Index

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:

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.

Language Bindings

If you are planning to use the TripIt API in any of the languages below, we recommend that you use one of our API language bindings. The bindings all provide an interface to all of the TripIt API endpoints and data object types along with a full OAuth Consumer implementation. No additional code needs to be downloaded to begin interacting with the TripIt API, and no need to worry about OAuth internal implementation details.

Our main GitHub repository is https://github.com/tripit. The specific bindings for each language are listed below:

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>
    <PrimaryLocationAddress>
        <address>New York, NY</address>
        <city>New York</city>
        <state>NY</state>
        <country>US</country>
        <latitude>40.714269</latitude>
        <longitude>-74.005973</longitude>
    </PrimaryLocationAddress>
  </Trip>
</Response>

OAuth

References

You can find more information about the OAuth specification here.

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

WhatWhenUntilDescription
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 nameparameter 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 given in UTC. Note that the server will respond with a 401 (unauthorized) if the timestamp supplied by the client is more than +/- 3 hours from what the server considers the current time.
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 nameparameter 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 nameparameter 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.

OAuth Detailed Error Codes

Here is a description for error codes that are thrown during the OAuth process:

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. When using JSON, it's not necessary to wrap the JSON in a {"Request" : ... }. Simply send the object.

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:

<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 a sample get request for a Note object using JSON: 

$ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/get/note/id/21765621/format/json
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Sep 2010 18:26:37 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private

{ "timestamp":"1285611997",
  "num_bytes":"880",
  "NoteObject": {
    "id":"217623621",
    "trip_id":"301454907",
    "is_client_traveler":"false",
    "relative_url":"\/trip_item\/show\/id\/21235681",
    "display_name":"A fine note",
    "Image":{
      "url":"https:\/\/www.tripit.com\/uploads\/images\/0\/2\/2\/00235a44aba776c3abc123def016079631ac285f622.jpg",
      "caption":"Andy's Picture"
    },
    "DateTime":{
      "date":"2009-11-10",
      "time":"14:00:00",
      "timezone":"America\/Los_Angeles",
      "utc_offset":"-08:00"
    },
    "Address":{
      "address":"444 DeHaro St., San Francisco, CA, 94107",
      "addr1":"444 DeHaro St.",
      "city":"San Francisco",
      "state":"CA",
      "zip":"94107",
      "country":"US",
      "latitude":"37.764246",
      "longitude":"-122.401694"
    },
    "text":"This is my note",
    "url":"http:\/\/www.tripit.com"
  }
}

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.

Note the following about the response object: 

$ 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>
    <PrimaryLocationAddress>
        <address>Vienna, Austria</address>
        <city>Vienna</city>
        <state>Vienna</state>
        <country>AT</country>
        <latitude>48.208488</latitude>
        <longitude>16.372075</longitude>
    </PrimaryLocationAddress>
  </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>
      <Agency>
        <agency_conf_num>RTW-123</agency_conf_num>
        <agency_name>RTW Business Travel Solutions, Inc.</agency_name>
        <agency_phone>(800) 555-7897</agency_phone>
        <agency_email_address>jane.doe@rtwtravel.com.com</agency_email_address>
        <agency_url>http://www.rtwtravel.com/</agency_url>
        <agency_contact>Ms  Jane Doe</agency_contact>
        <partner_agency_id>1</partner_agency_id>
      </Agency>
    <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>
  <PartnerAgency>
    <partner_agency_id>1</partner_agency_id>
    <partner_agency_name>RTW Business Travel Solutions, Inc.</partner_agency_name>
    <partner_agency_short_name>RTW Travel</partner_agency_short_name>
    <partner_agency_logo_small_url>https://www.tripit.com/uploads/images/4/9/9/499d464439690088810193770e9cd9d67aa.png</partner_agency_logo_small_url>
    <partner_agency_logo_medium_url>https://www.tripit.com/uploads/images/7/1/2/7124d3adfdbf63da7149cbfd06c86baa40b.png</partner_agency_logo_medium_url>
    <partner_agency_logo_large_url>https://www.tripit.com/uploads/images/9/9/2/9928a98449b064c8acc1c2159f588f078b4.png</partner_agency_logo_large_url>
  </PartnerAgency>
  <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:

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|parking
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.
points_program - - - For a TripIt Pro user account, lists all configured points programs.

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>
    <PrimaryLocationAddress>
        <address>New York, NY</address>
        <city>New York</city>
        <state>NY</state>
        <country>US</country>
        <latitude>40.714269</latitude>
        <longitude>-74.005973</longitude>
    </PrimaryLocationAddress>
  </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>
    <PrimaryLocationAddress>
        <address>Paris, France</address>
        <city>Paris</city>
        <state>Île-de-france</state>
        <country>FR</country>
        <latitude>48.866667</latitude>
        <longitude>2.333333</longitude>
    </PrimaryLocationAddress>
  </Trip>
</Response>

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

Note the following about the response object: 

$ 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>
  <booking_site_name>Expedia</booking_site_name>
  <booking_site_email_address>customercare@expedia.com</booking_site_email_address>
  <booking_site_url>http://www.expedia.com</booking_site_url>
  <is_purchased>true</is_purchased>
  <Agency>
    <agency_conf_num>RTW-123</agency_conf_num>
    <agency_name>RTW Business Travel Solutions, Inc.</agency_name>
    <agency_phone>(800) 555-7897</agency_phone>
    <agency_email_address>jane.doe@rtwtravel.com</agency_email_address>
    <agency_url>http://www.rtwtravel.com/</agency_url>
    <agency_contact>Ms  Jane Doe</agency_contact>
    <partner_agency_id>1</partner_agency_id>
  </Agency>
  <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>
<PartnerAgency>
    <partner_agency_id>1</partner_agency_id>
    <partner_agency_name>RTW Business Travel Solutions, Inc.</partner_agency_name>
    <partner_agency_short_name>RTW Travel</partner_agency_short_name>
    <partner_agency_logo_small_url>https://www.tripit.com/uploads/images/4/9/9/499d464439690088810193770e9cd9d67aa.png</partner_agency_logo_small_url>
    <partner_agency_logo_medium_url>https://www.tripit.com/uploads/images/7/1/2/7124d3adfdbf63da7149cbfd06c86baa40b.png</partner_agency_logo_medium_url>
    <partner_agency_logo_large_url>https://www.tripit.com/uploads/images/9/9/2/9928a98449b064c8acc1c2159f588f078b4.png</partner_agency_logo_large_url>
</PartnerAgency>
</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.

Handling of Date and Time data types:

The xs:date and xs:time specifications ( http://www.w3schools.com/schema/schema_dtypes_date.asp) allow for timezone to be specified within the xs:date and xs:time data types respectively. TripIt, however, infers the timezone of a Trip object from the geographical location of that Trip object, e.g. address of a hotel, flight segment's destination, etc -- in essence, we do not make use of the timezone component in the xs:date and xs:time data types. Hence, when specifying the date/time for a Trip object, specify the date/time to be the "local" time with respect to the Trip object.

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 
<Request>
  <Trip>
    <start_date>2008-12-09</start_date>
    <end_date>2008-12-27</end_date>
    <primary_location>New York, NY</primary_location>
    <PrimaryLocationAddress>
        <address>New York, NY</address>
        <city>New York</city>
        <state>NY</state>
        <country>US</country>
        <latitude>40.714269</latitude>
        <longitude>-74.005973</longitude>
    </PrimaryLocationAddress>
  </Trip>
</Request>

Here is the equivalent request body if you were to send this in JSON (Note: the lack of the Request wrapper): 

{"Trip":
   {"start_date":"2009-12-09",
    "end_date":"2009-12-27",
    "primary_location":"New York, NY"
   }
}

Here is a sample create request for a Trip object: 

$ curl -k -D /dev/tty --data-urlencode xml@/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>
    <PrimaryLocationAddress>
        <address>New York, NY</address>
        <city>New York</city>
        <state>NY</state>
        <country>US</country>
        <latitude>40.714269</latitude>
        <longitude>-74.005973</longitude>
    </PrimaryLocationAddress>
  </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 
<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_email_address>example@united.com</booking_site_email_address>
    <booking_site_url>http://www.united.com/</booking_site_url>
    <supplier_conf_num>ABC123</supplier_conf_num>
    <Agency>
      <agency_conf_num>RTW-123</agency_conf_num>
      <agency_name>RTW Business Travel Solutions, Inc.</agency_name>
      <agency_phone>(800) 555-7897</agency_phone>
      <agency_email_address>jane.doe@rtwtravel.com</agency_email_address>
      <agency_url>http://www.rtwtravel.com/</agency_url>
      <agency_contact>Ms  Jane Doe</agency_contact>
    </Agency>
    <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>

Note the following about the above request object:

Here is a sample create request for a Air object: 

$ curl -k -D /dev/tty --data-urlencode xml@/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_email_address>example@united.com</booking_site_email_address>
    <booking_site_url>http://www.united.com/</booking_site_url>
    <supplier_conf_num>ABC123</supplier_conf_num>
    <is_purchased>true</is_purchased>
    <Agency>
      <agency_conf_num>RTW-123</agency_conf_num>
      <agency_name>RTW Business Travel Solutions, Inc.</agency_name>
      <agency_phone>(800) 555-7897</agency_phone>
      <agency_email_address>jane.doe@rtwtravel.com</agency_email_address>
      <agency_url>http://www.rtwtravel.com/</agency_url>
      <agency_contact>Ms  Jane Doe</agency_contact>
      <partner_agency_id>1</partner_agency_id>
    </Agency>
    <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>
  <PartnerAgency>
      <partner_agency_id>1</partner_agency_id>
      <partner_agency_name>RTW Business Travel Solutions, Inc.</partner_agency_name>
      <partner_agency_short_name>RTW Travel</partner_agency_short_name>
      <partner_agency_logo_small_url>https://www.tripit.com/uploads/images/4/9/9/499d464439690088810193770e9cd9d67aa.png</partner_agency_logo_small_url>
      <partner_agency_logo_medium_url>https://www.tripit.com/uploads/images/7/1/2/7124d3adfdbf63da7149cbfd06c86baa40b.png</partner_agency_logo_medium_url>
      <partner_agency_logo_large_url>https://www.tripit.com/uploads/images/9/9/2/9928a98449b064c8acc1c2159f588f078b4.png</partner_agency_logo_large_url>
  </PartnerAgency>
</Response>
$

Note the following about the response objects:

replace

A replace request is used to replace existing objects in a TripIt account. After the object is replaced it will get the same object id as the one the object had before the replace call. To replace an object make an HTTP POST request to the following URL: 

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

<object type> is one of the following strings:

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

Example:

Here is a sample replace request for a Trip object:

The following example shows XML for a trip creation followed by a replace call on that trip to extend the dates of the trip. The first step is to create a new trip. Here is the post data for the creation of a private Trip object: 

$ cat /var/tmp/create_trip.xml
<Request>
  <Trip>
    <start_date>2010-09-07</start_date>
    <end_date>2010-09-18</end_date>
    <is_private>true</is_private>
    <primary_location>Rome, Italy</primary_location>
  </Trip>
</Request>

Here is the <Response> object the API returns when you create this Trip object: 

<Response>
  <timestamp>1278433489</timestamp>
  <num_bytes>1339</num_bytes>
  <Trip>
    <TripInvitees>
      <Invitee profile_ref="VPdqwr9_2vA2j3dla_pfz9">
        <is_read_only>false</is_read_only>
        <is_traveler>true</is_traveler>
      </Invitee>
    </TripInvitees>
    <id>7501715</id>
    <relative_url>/trip/show/id/7501715</relative_url>
    <start_date>2010-09-07</start_date>
    <end_date>2010-09-18</end_date>
    <display_name>Rome, Italy, September 2010</display_name>
    <image_url>http://www.tripit.com/images/places/general.jpg</image_url>
    <is_private>true</is_private>
    <primary_location>Rome, Italy</primary_location>
    <PrimaryLocationAddress>
        <address>Rome, Italy</address>
        <city>Rome</city>
        <state>Latium</state>
        <country>IT</country>
        <latitude>41.9</latitude>
        <longitude>12.483333</longitude>
    </PrimaryLocationAddress>
  </Trip>
  <Profile ref="VParwr9_2vA2j3dla_pfz9">
    <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>https://www.tripit.com/uploads/images/8/7/2/92dadd8fb7f23455feb38212d9decdf81f4608.jpg</photo_url>
    <activity_feed_url>http://www.tripit.com/feed/activities/private/12883BD53-7D9ABDE235538A82F248234532ABDC1ACC/activities.aactivity_feed_url>
    <alerts_feed_url>http://www.tripit.com/feed/alerts/private/9123AABD-F192224ABEFD24E1C2098230985A92ABEF234C356AFB0/alerts.aalerts_feed_url>
    <ical_url>webcal://www.tripit.com/feed/ical/private/9237C55-33ABDEC145454ABCED2ABDE343477EE42ED12147E5EDA66/tripit.ics<l>
  </Profile>
</Response>

Now, if we want to update the <end_date> on this Trip object the post data for the replace method would look something like this: 

$ cat /var/tmp/trip_replace.xml
<Request>
  <Trip>
    <start_date>2010-09-07</start_date>
    <end_date>2010-10-18</end_date>
    <is_private>true</is_private>
    <primary_location>Rome, Italy</primary_location>
  </Trip>
</Request>

Notice that the post data contains the data from the original create call that is not changing along with the new end_date. This is important because the replace method will be deleting the old Trip object and creating a new one in place of the old one. If for example the post data on the replace call didn't specify <is_private>true</is_private> then the Trip object would no longer be private.

Here is a sample replace request for a Trip object: 

$ curl -k -D /dev/tty --data-urlencode xml@/var/tmp/trip_replace.xml --user <username>:<password> https://api.tripit.com/v1/replace/trip/id/7501715
HTTP/1.1 100 Continue

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

<Response>
  <timestamp>1278433576</timestamp>
  <num_bytes>1339</num_bytes>
  <Trip>
    <TripInvitees>
      <Invitee profile_ref="VParwr9_2vA2j3dla_pfz9">
        <is_read_only>false</is_read_only>
        <is_traveler>true</is_traveler>
      </Invitee>
    </TripInvitees>
    <id>7501715</id>
    <relative_url>/trip/show/id/7501771</relative_url>
    <start_date>2010-09-07</start_date>
    <end_date>2010-10-18</end_date>
    <display_name>Rome, Italy, September 2010</display_name>
    <image_url>http://www.tripit.com/images/places/general.jpg</image_url>
    <is_private>true</is_private>
    <primary_location>Rome, Italy</primary_location>
    <PrimaryLocationAddress>
        <address>Rome, Italy</address>
        <city>Rome</city>
        <state>Latium</state>
        <country>IT</country>
        <latitude>41.9</latitude>
        <longitude>12.483333</longitude>
    </PrimaryLocationAddress>
  </Trip>
  <Profile ref="VParwr9_2vA2j3dla_pfz9">
    <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>https://www.tripit.com/uploads/images/8/7/2/92dadd8fb7045feb38212d9decdf81f4608.jpg</photo_url>
    <activity_feed_url>http://www.tripit.com/feed/activities/private/12DA7D53-7D9ABDE4BF8A82F248234532ABDC1ACC/activities.atomivity_feed_url>
    <alerts_feed_url>http://www.tripit.com/feed/alerts/private/91237ABD-F192224ABEFD24E1C24CC75A92ABEF234C356AFB0/alerts.atom&ts_feed_url>
    <ical_url>webcal://www.tripit.com/feed/ical/private/91927C55-33ABDEC145454ABCED2F47377EE42ED12147E5EDA66/tripit.ics</ict;
  </Profile>
</Response>

Here's another example of how the replace method can be used but this time for a NoteObject. Here's the XML used to create the NoteObject: 

$ cat /var/tmp/note.xml
<Request>
  <NoteObject>
    <display_name>A Test Note</display_name>
    <DateTime>
      <date>2010-12-09</date>
      <time>14:00:00</time>
    </DateTime>
    <Address>
      <addr1>500 Treat Avenue</addr1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94110</zip>
      <country>US</country>
    </Address>
    <text>Test note.</text>
    <url>http://www.tripit.com/</url>
  </NoteObject>
</Request>

Here's how you create the NoteObject: 

$ curl -D /dev/tty --user <username>:<password> --data-urlencode xml@/var/tmp/note.xml https://api.tripit.com/v1/create
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 29 Jul 2010 21:19:57 GMT
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private

<Response>
  <timestamp>1280438397</timestamp>
  <num_bytes>738</num_bytes>
  <NoteObject>
    <id>68872927</id>
    <trip_id>3024907</trip_id>
    <is_client_traveler>false</is_client_traveler>
    <relative_url>/trip_item/show/id/68872927</relative_url>
    <display_name>A Test Note</display_name>
    <DateTime>
      <date>2010-12-09</date>
      <time>14:00:00</time>
      <timezone>America/Los_Angeles</timezone>
      <utc_offset>-08:00</utc_offset>
    </DateTime>
    <Address>
      <address>500 Treat Avenue, San Francisco, CA, 94110</address>
      <addr1>500 Treat Avenue</addr1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94110</zip>
      <country>US</country>
      <latitude>37.762161</latitude>
      <longitude>-122.413927</longitude>
    </Address>
    <text>Test note.</text>
    <url>http://www.tripit.com/</url>
  </NoteObject>
</Response>

In order to replace the NoteObject with one that has updated data you would post the following to the API as follows: 

$ cat /var/tmp/replace_note.xml
<Request>
  <NoteObject>
    <display_name>A Test Note, updated</display_name>
    <DateTime>
      <date>2010-12-10</date>
      <time>14:00:00</time>
    </DateTime>
    <Address>
      <addr1>500 Treat Avenue</addr1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94110</zip>
      <country>US</country>
    </Address>
    <text>Here's my test note with an updated bit of text.</text>
    <url>http://www.tripit.com/</url>
  </NoteObject>
</Request>
$ curl -D /dev/tty --user <username>:<password> --data-urlencode xml@/var/tmp/replace_note.xml https://api.tripit.com/v1/replace/note/id/68872927
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 29 Jul 2010 21:28:03 GMT
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private

<Response>
  <timestamp>1280438882</timestamp>
    <num_bytes>785</num_bytes>
    <NoteObject>
      <id>68872927</id>
      <trip_id>3024907</trip_id>
      <is_client_traveler>false</is_client_traveler>
      <relative_url>/trip_item/show/id/68872927</relative_url>
      <display_name>A Test Note, updated</display_name>
      <DateTime>
        <date>2010-12-10</date>
        <time>14:00:00</time>
        <timezone>America/Los_Angeles</timezone>
        <utc_offset>-08:00</utc_offset>
      </DateTime>
      <Address>
        <address>500 Treat Avenue, San Francisco, CA, 94110</address>
        <addr1>500 Treat Avenue</addr1>
        <city>San Francisco</city>
        <state>CA</state>
        <zip>94110</zip>
        <country>US</country>
        <latitude>37.762161</latitude>
        <longitude>-122.413927</longitude>
      </Address>
      <text>Here's my test note with an updated bit of text.</text>
      <url>http://www.tripit.com/</url>
    </NoteObject>
  </Response>

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:

<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


$

When removing user from a trip, you need to specify the trip you want to update and the user you want to remove. The format looks like this: 

https://api.tripit.com/v1/delete/trip_partcipant/trip_id/<TripIt Object ID>/profile_ref/<Unique User Identifier>

You will obtain user identifier from trip details (see get/trip API call). Sample delete request for deleting user wKieDZalTIjn0wltsyMcLQ from trip 770829: 

$ curl -k -D /dev/tty --user <username>:<password> https://api.tripit.com/v1/delete/trip_participant/trip_id/770829/profile_ref/wKieDZalTIjn0wltsyMcLQ
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 or json request parameter in the POST args would return a 400 Bad Request from the server.
401 Unauthorized An OAuth Consumer will receive a 401 Unauthorized response from the API for three reasons. 1) 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. 2) The TripIt account for which the consumer was authorized is no longer authorizing it. 3) The OAuth Consumer key has been de-activated.
403 Forbidden An OAuth Consumer will receive a 403 Forbidden response from the API when the TripIt account for which the consumer was authorized is not yet confirmed. The most common situation in which this happens is when a new account that authorizes an API client hasn't been confirmed before the API client attempts to execute a read operation on the API (e.g. /v1/list/trip).
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:

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

Following kinds of <object_type>s are categorized as Reservation Objects

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.

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.

Pagination

Pagination is activated for all requests to the /v1/list/object endpoint, and requests to the /v1/list/trip endpoint in any of the following three circumstances:

  1. request parameter 'past' == true (requesting past trip data), or
  2. request parameter 'page_num' is specified, or
  3. for upcoming trips request, the set of upcoming trips is greater than 50 trips.

Clients can specify request parameter values in their requests for 'page_num' and/or 'page_size'. If not specified by the client, the default value for page_size is 5 for trips and 25 for objects. Both of these request parameters must have positive integer values and the value for page_num must be less than or equal to the value of <max_page> (defined below).

There are 3 new response elements that are declared in the response xsd:

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:

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 delayed, which means that the (EstimatedDepartureDateTime - ScheduledDepartureDateTime) >= 15 minutes.
402 In Flight - late The flight is currently in the air and is considered to be late, 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.
405 Possibly Delayed The flight has possibly been delayed.
406 In Flight - Possibly Late The flight is in flight and may possibly be late.
407 Arrived - Possibly Late The flight has arrived but may possibly be late.
408 Unknown The flight status is unknown.

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

Point Tracker

Data from TripIt Pro's Point Tracker feature is available via the API as well. The methods to obtain this are:

and are described in the /v1/list and /v1/get documentation in more detail.

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.

Examples

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