Skip to content

Mobile App Design Considerations

Jump to bottom Edit New page
Sean Barbeau edited this page Sep 9, 2019 · 71 revisions

Interested in creating a mobile app that uses OneBusAway for real-time transit data? You're in the right place.

Before you start your own app, check out the existing open-source OneBusAway (OBA) apps to get ideas, and make sure you're not duplicating features that already exist:

You may want to contact the developers to see if you can pitch in to add new features to the existing apps. Or, create a new OBA app for a new platform!

Using the existing OBA Mobile Apps with your OBA Server

First, check out the multi-region page to learn how to easily make the OneBusAway mobile apps available in your city.

Then, for the existing OBA mobile apps to work with your OneBusAway server, you must add the following keys to the data-sources.xml file for the onebusaway-api-webapp (or using an admin web page):

  • Android: v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20=
  • iPhone: org.onebusaway.iphone
  • Windows Phone: v1_C5+aiesgg8DxpmG1yS2F/pj2zHk=c3BoZW5yeUBnbWFpbC5jb20==
  • Windows 8: 693c0a55-9ef0-4302-8bc3-f9b2db93e124
  • Fire Phone: v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20= (same as Android)
  • Alexa (for Amazon Echo, etc.): e5c0e97a-729d-4fdb-a3ca-2fccb20ac3ab
  • Pebble Smartwatch: 48d59e79-ed33-4be0-9db3-912f8f521fec

NOTE: If you're testing the Windows Phone key with your OBA API from a browser, note that the key contains two reserved characters ("+" and "/") that need to be encoded to form a valid URL. Here's the encoded key - v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk%3Dc3BoZW5yeUBnbWFpbC5jb20%3D= - so a sample URL would be: http://api.tampa.onebusaway.org/api/api/where/agencies-with-coverage.json?key=v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk%3Dc3BoZW5yeUBnbWFpbC5jb20%3D=

The existing iPhone and Android apps both have settings where you can update the OBA server that the app is pointing at. So, for testing apps with your server prior to being added to the Regions API, you can download the existing apps from the iPhone App Store or Google Play store and change the URL to point to your server.

To be clear, the above keys should NOT be used in your own mobile app, these keys are reserved for the exiting OBA native open-source mobile apps listed at the top of this section.

See the Multi-region page once you've tested your OBA server with the OBA apps to see how you can be added as a new OneBusAway region.

Launching your own mobile apps with a OBA Server

We strongly encourage you to use the main OneBusAway apps as part of the OneBusAway Multi-region configuration in your region - this allows everyone to easily benefit from investments made in these apps and immediately get bug fixes and new features when they are deployed.

If you really need an app with your own brand and app store listing, check our the white-label/re-branding capabilities:

Please DO NOT fork the codebase if at all possible - this creates long-term maintenance headaches for everyone and costs more to maintain that leveraging the white-label solutions.

The Anatomy of OBA-related Transit APIs

Like many open-source projects, OneBusAway is changing quickly. Check out the OBA RESTful API Roadmap for a list of APIs that are currently supported in OneBusAway, as well as the plan for what APIs will be supported in the future.

Also check out the SIRI Element to UI Mappings for a description of the SIRI element fields and how they should be shown to transit riders.

Design Considerations

Overview

In general, we suggest using the JSON interfaces for OneBusAway. JSON is a more compact representation of data than XML, and therefore more efficient. This means less data sent over the wireless network and better battery life for a mobile phone.

Format of OBA REST API requests and responses

See OBA REST API documentation.

Format of SIRI responses

To conform with the SIRI standard, XML and JSON element labels are in PascalCase (i.e., not camelCase, where the first letter is lower-case).

XML:

<RecordedAtTime>2012-09-12T09:27:52.867-04:00</RecordedAtTime>

JSON:

"RecordedAtTime":"2012-08-21T12:07:21.485-04:00"

Java-based JSON and XML data binding parsers such as Jackson can typically be configured to handle PascalCase, even though they typically expect camelCase, since the Java POJOs used in data binding typically define fields in camelCase.

However this presents a problem for certain attributes. Consider the following XML:

<Summary xml:lang="EN">b/d 1:00pm until f/n. local and express buses run w/delays & detours. POTUS visit in MANH. Allow additional travel time Details at www.mta.info</Summary>

The xml:lang attribute must remain lower-case because of XML language attribute definition defined by W3C. Therefore, if you configure your JSON or XML parser to use PascalCase for elements, be aware that you will need to configure it to make an exception for attributes such as xml:lang.

TODO - add how to handle xml:lang in Jackson, also add this to SiriRestClient pages.

Platform-specific information

Below are some pointers for developing OneBusAway apps on various mobile platforms.

Android
Real-time Discovery and Real-time REST API - JSON and XML parsing

We've created onebusaway-client-library, an open-source library written in Java for easily access the OneBusAway REST APIs. It's used in the OneBusAway Alexa skill and is licensed under Apache 2.0.

Real-time mobile SIRI API - JSON and XML parsing

We've created Siri Rest Client, an open-source reference implementation Android app that shows how to access and parse SIRI data in both JSON and XML format. Feel free to use this project as a basis for your app, as the source code is licensed under Apache 2.0.

We've developed several tutorials based on what we've learned implementing the SiriRestClient, especially in the area of JSON and XML parsing on Android:

Add a custom footer
Add a custom sidebar
Clone this wiki locally