Developer Do’s & Dont’s: How to Make Apps that Win Over Travelers

Written on May 19, 2011 at 10:36 am, by

1992590

By Travis Winfrey, Mobile Development Manager

TripIt recently announced that we support over 330 customer and business-oriented apps. We thought it might be helpful to share a handful of tips that we've found useful in writing our own trio of applications, to help you use the TripIt API efficiently in your mobile client.
 
Do make your app as responsive and network-aware as possible. The faster your users can get their data, the happier they will be.  In addition, network efficiency turns into power efficiency, another customer-pleasing target.  As they say in the Android guidelines, "assume the network is slow" and remember the network performance on a physical device will always be worse than what you will have on an emulator.
  • 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.
Don't expect data in every field.  TripIt has a rich data model that covers all the information we regularly see in confirmations.   If our servers can extract information from a confirmation, we will happily stuff that data into the appropriate object.  However, the data is not always there.  Always refer to our XML schema, where we are very clear about what fields will and will not be present for any object.

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. 

Don't expect data in English.  We publish traveler data in UTF-8, and we have extremely large coverage in non-English sources of travel confirmations.  You should always be using appropriate character types and string functions for fully internationalized data.
 
Don’t expect times on your objects.  Obviously, exact times are crucial to a traveler’s working schedule — but we don’t always have the data.  Hotels commonly do not put a check-in time on their confirmations, assuming the traveler knows that is is usually 3pm.  This occurs about 2% of the time for hotels, in fact.   Objects like Notes rarely have times, even when they contain restaurant reviews or notes for meetings.  
 
The sorting rule that we follow on the TripIt web site may be useful to copy:
  1. Items with no dates are shown last. People will sometimes put no-date notes on a trip, typically reviews.
  2. Items with dates but no times are shown first in that day. 
  3. 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.
  4. Times are converted to one timezone before sorting.  Times we send down in the API will almost always have timezones.
  5. 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.  
Do recognize Pro users.  TripIt is a freemium model, with many ad-viewing customers and many subscription-based customers.  From an API development perspective, the main thing a Pro user shows to your client is lots more data for trips and frequent traveler information.  
 
For example, consider an Air Segment, where instead of just the scheduled time for departure or arrival, a Pro user will also have the latest estimated times, plus the most recent gate & terminal information.
 
Here we’ve extracted what a free user might see in their data stream, and contrast it with what a pro user might see.  (This is a highly compressed view of the actual data.  Timezone information and other duplicate information has been omitted or combined, for space reasons):
 
         "StartDateTime": "2011-03-30 07:30:00",
         "EndDateTime":   "2011-03-30 11:00:00",
 
In contrast, the Pro user’s data stream will include these additional details, showing a badly delayed flight and more terminal and gate information.  Consider all the possibilities when using these values.   If you display layovers, for example, you should be using the estimated times, as they are the best known values for that flight.  
 
         "Status": {
           "last_modified": "1301508689",
           "flight_status": "401",
           "departure_terminal": "4",
           "departure_gate": "B25",
           "ScheduledDepartureDateTime": "2011-03-30 07:30:00",
           "EstimatedDepartureDateTime": "2011-03-30 08:45:00",
           "arrival_terminal": "I",
           "arrival_gate": "A8",
           "ScheduledArrivalDateTime":  "2011-03-30 11:00:00"
           "EstimatedArrivalDateTime":  "2011-03-30 12:10:00"
           },
         }
 
We can't be experts in all the areas covered by your many different current and future apps – I'm personally looking forward to apps that will let me visualize my trips in advance, right down to the friendly bartenders – but we do know how our users behave, and how to make the most efficient use of our API in a mobile setting.
 
Of course, this advice is only specific to our API.  Apple and Android have touched on general performance issues elsewhere.  In future articles, I will touch on less-obvious aspects of our API content and how our customers typically use our services to store their traveler data.
 
If you find this useful, please do share with other developers in your network.

For more information, please go to http://www.tripit.com/developer.  You can also join us in our developer forum.