By Travis Winfrey, Mobile Development Manager
- Do use /modified_since/timestamp. Every response from our server is timestamped, e.g., 1259029173. This opaque value can be resubmitted on your next request with /modified_since. You will only get objects related to your request when they have changed since that timestamp. This tiny modification speeds up the updates to your client by a fantastic degree, as it will not have to process unchanged information. If your client manages Trip data and Point Tracker (frequent flyer) data, then track those with separate timestamp values.
- Do use JSON instead of XML with TripIt. Many people turn to XML first, because there’s native support in many client libraries, and it’s the default format for the API. Just add /format/json to your queries, though, and you will reap an immediate benefit of 30% smaller data on average. There’s no processing time difference, but your customers will pay a heavy price when that data comes to their phone over a slow network protocol like EDGE. Travelers in general are going to deal with sketchier networks than a non-traveler. There are dozens of public domain libraries for JSON. It is easy to write either recursive-descent parsers or sequential access parsers similar to SAX using these libraries.
- Do request compressed data. Our JSON-formatted data can compress down 80-90% with gzip. Simply add “gzip” into the “Accept-Encoding” header on your outgoing requests.
- Do avoid multiple roundtrips. When you have high ping times, which is frequently true for mobile users, you want to minimize the roundtrips made to our API servers, especially since your phone has to set up a full HTTPS session for each request. If your client needs all the TripIt objects, then you can use “/list/trip/include_objects/true” as the base request. This call returns all the trip, profile, and object level data in one go.
- Do consider using /exclude_types/weather — weather objects are present for every day of a trip. As I write, we provide only historically oriented weather data, which is not helpful to a mobile user who is currently on a trip. If you’re not using that data, don’t request it. Weather data can take up 20-40% of the trip + profile + object data in the response from our servers.
- Do add a meaningful user-agent to your requests. We would prefer the format AppName/versionNumber.
How would this play out in practice? Well, cruise and rail confirmations are notorious for being skimpy, without addresses or phone numbers. If you assume that some data “must be there” when you display or combine them for display, then you risk crashes or displaying unfortunate values like “(null) 43” to your customers. Even if it’s “logical” that one value should be present, we still might not have it available. Your clients must be robust in the face of all possible omissions in the fields.
Don’t expect data in any particular format. Again, our servers extract information from confirmations, which contain an amazingly wide variety of formats.
- Phone numbers might have a generally usable international phone number, e.g., +1-212-555-1212 or they might be in any of a number of regional phone formats.
- Addresses might be in a geo-locatable format, or they might not.
- Any values with actual costs in them have values like “300” or “US$300” or “300 USD”. It’s best not to prefix or suffix any cost value.
It’s conceivable that TripIt may standardize these lower-level details in the future, as each one represents a tiny roadblock for a user who might not know how to navigate around the local conventions.
- Items with no dates are shown last. People will sometimes put no-date notes on a trip, typically reviews.
- Items with dates but no times are shown first in that day.
- Hotel and car activities on the same day should be shown in the correct order when there is no time on the object. Cars must be picked up before they can be dropped off, and you cannot check out before you check in.
- Times are converted to one timezone before sorting. Times we send down in the API will almost always have timezones.
- Finally, trip objects are sorted with the time or start-time for each object as the primary key, and end-time as the secondary key.
“EndDateTime”: “2011-03-30 11:00:00″,
“ScheduledDepartureDateTime”: “2011-03-30 07:30:00″,
“EstimatedDepartureDateTime”: “2011-03-30 08:45:00″,
“ScheduledArrivalDateTime”: “2011-03-30 11:00:00″
“EstimatedArrivalDateTime”: “2011-03-30 12:10:00″