Skip to content
This repository has been archived by the owner on May 27, 2024. It is now read-only.

Home

Jump to bottom
Sean Barbeau edited this page Apr 7, 2017 · 79 revisions

SIRI REST Client

SiriRestClient is an open-source reference implementation Android library for interacting with the RESTful SIRI (Service Interface for Real Time Information) interface for real-time transit data, such as that currently being used by the MTA Bus Time API.

SIRI is a public transportation standard developed by the European standards organization CEN. More information about SIRI can be found at the main SIRI website.

The purpose of this project is to stimulate innovation in mobile apps for the SIRI real-time transit API by providing an easy-to-use Android library that makes interacting with the API simple for app developers, thus lowering the learning curve for developing new real-time transit apps.

See the SiriRestClientUI project for an example of how to use this library in an Android app.

All SiriRestClient source code is licensed under Apache 2.0.

Getting Started

Using this library in an Android app

To add this library to your project using Maven, add the following to your pom.xml file:

<dependencies>
  <!-- SIRI POJOs -->
  <dependency>
      <groupId>edu.usf.cutr.siri</groupId>    
      <artifactId>onebusaway-siri-api-v13-pojos</artifactId>    
      <version>1.0.0</version>
  </dependency>
    
  <!-- SiriRestClient library -->
  <dependency>
      <groupId>edu.usf.cutr.siri</groupId>
      <artifactId>sirirestclient</artifactId>
      <version>1.0.0-SNAPSHOT</version>            
  </dependency>
</dependencies>

<!-- CUTR SNAPSHOTs/RELEASES -->
<repositories>
    <repository>
        <id>cutr-snapshots</id>
        <url>https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/snapshots</url>
    </repository>        
    <repository>
        <id>cutr-releases</id>
        <url>https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/releases</url>
    </repository>  
</repositories>

If you're using Gradle and Android Studio, here's what your build.gradle should look like:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:0.11.+'
    }
}
apply plugin: 'android'

repositories {
    mavenCentral()
    maven {
        // CUTR SNAPSHOTs
        url "https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/snapshots"
    }
    maven {
        // CUTR Releases
        url "https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/releases"
    }
}

android {
    compileSdkVersion 19
    buildToolsVersion "19.1.0"

    defaultConfig {
        minSdkVersion 9
        targetSdkVersion 13
    }

    // http://stackoverflow.com/questions/20673625/gradle-0-7-0-duplicate-files-during-packaging-of-apk
    packagingOptions {
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/services/com.fasterxml.jackson.core.JsonFactory'
        exclude 'META-INF/services/com.fasterxml.jackson.core.ObjectCodec'
    }
...

dependencies {
    compile 'com.android.support:support-v4:19.1.+'
    compile 'com.actionbarsherlock:actionbarsherlock:4.4.0@aar'
    // POJOs used for full data-binding via Jackson
    compile 'edu.usf.cutr.siri:onebusaway-siri-api-v13-pojos:1.0.0'
	// SIRI REST Client library
	compile 'edu.usf.cutr.siri:sirirestclient:1.0.0-SNAPSHOT'
}

Sample code

The SIRI REST API has two primary interfaces that are currently supported in this library:

  • vehicle monitoring - provides information for specific transit vehicles
  • stop monitoring - provides information for estimated arrival information at specific stops

Here's some sample code for configuring the client:

//Client object from this library that will make the request to the server
SiriRestClient client; 

// Setup server config
SiriRestClientConfig config = new SiriRestClientConfig(SiriRestClientConfig.RESPONSE_TYPE_JSON);  //Request JSON response
config.setHttpConnectionType(SiriRestClientConfig.HTTP_CONNECTION_TYPE_ANDROID);  //Request using Android HTTP connection object
config.setJacksonObjectType(SiriRestClientConfig.JACKSON_OBJECT_TYPE_READER);  //Request using the Jackson ObjectReader, which is more efficient than ObjectMapper

// Instantiate client with URLs for server and config
client = new SiriRestClient(
	        "http://bustime.mta.info/api/siri/vehicle-monitoring",
                "http://bustime.mta.info/api/siri/stop-monitoring", config);

Once you've configure the client, you can request information for either a vehicle or specific stop.

Here's an example of requesting stop info:

//Get the parameters that will be used to make the request - fill in these with your own info
String key = getDeveloperKey(); //Get the developer API key to use, perhaps from a config file
String operatorRef = getOperatorRef();  //Get the operator we're requesting info for
String monitoringRef = getStopId();  //Get the stop ID we're requesting info for, perhaps from UI field
String lineRef = getRouteId();  //Get the route ID filter, perhaps from UI field
int directionRefInt = getDirectionInt(); //Route direction filter (0 or 1)
String stopMonitoringDetailLevel = "normal";  //Get arrivals up to the specified stop ID (not after)
int maximumNumberOfCallsOnwardsInt = 3; //Get next 3 arrivals at this stop

//Make request to the server, and get response data in a SIRI object
Siri siri = client.makeStopMonRequest(key,
                                      operatorRef,
                                      monitoringRef,
                                      lineRef,
                                      directionRefInt,
                                      stopMonitoringDetailLevel,
                                      maximumNumberOfCallsOnwardsInt);

And here's an example of requesting vehicle info:

//Get the parameters that will be used to make the request - fill in these with your own info
String key = getDeveloperKey(); //Get the developer API key to use, perhaps from a config file
String operatorRef = getOperatorRef();  //Get the operator we're requesting info for
String vehicleRef= getVehicleId();  //Get the vehicle ID filter, perhaps from UI field
String lineRef= getRouteId();  //Get the route ID filter, perhaps from UI field
int directionRefInt = getDirectionInt(); //Route direction filter (0 or 1)
String vehicleMonitoringDetailLevel= "calls";  //Get arrival info for the vehicle, in addition to position information
int maximumNumberOfCallsOnwardsInt = 3; //Get next 3 arrivals for this vehicle

Siri siri = client.makeVehicleMonRequest(key,
                                         operatorRef,
                                         vehicleRef,
                                         lineRef,
                                         directionRefInt,
                                         vehicleMonitoringDetailLevel,
                                         maximumNumberOfCallsOnwardsInt);

Demo App

See the SiriRestClientUI project for an example of how to use this library in an Android app.

Compiling the code yourself

Setting up your environment

This project was created in Eclipse using the Android SDK and Android Plugin for Eclipse. Libraries and dependencies are managed using [Maven] (http://eclipse.org/m2e/). Note that you'll need to install the m2e Android Maven plugin in Eclipse.

Getting the code

To get started with this project, use a Git client to clone this repository to your local computer. Then, in Eclipse do "File->Import->Maven->Existing Maven Projects", and point to the directory where you cloned the repo.

Dependencies

Jackson JSON and XML Processor project

SiriRestClient has dependencies on Jackson for parsing JSON and XML. We also need some XML libraries that have been modified so they work on Android. Both of these dependencies are managed via Maven, so no action is required on your part.

Please see the Parsing JSON and XML on Android wiki page for a full description of the use of Jackson with Android.

SIRI POJOs

This project also uses the SIRI POJOs project for Jackson data binding. This project is included in the Maven dependencies, so no action is required.

Build the project

Clean and build the project. If you have any problems, try cleaning the project, restarting Eclipse, then building the SiriRestClient project.

CUTR Release Process

We've set up a Maven repository to hold the artifacts from this project in a Github project - cutr-mvn-repo.

At CUTR, we should run the following at the command-line to create a new artifact:

mvn -DaltDeploymentRepository=cutr-snapshots::default::file:"/Git Projects/cutr-mvn-repo/snapshots" clean deploy

Then commit using Git and push new artifacts to Github.

Note that the "snapshots" in the command-line should be replaced with "releases" for release versions.

Regenerating the client SIRI API code

We anticipate that the SIRI specification will change over time and the SIRI Plain Old Java Objects (POJOs) code will need to be regenerated. The SIRI v1.3 POJOs are maintained in their own OBA SIRI v1.3 POJOs project. If a new version of SIRI is released (e.g., v2.0), a new SIRI POJOs project will need to be created for this version of SIRI.

There are two strategies for creating new SIRI POJOs needed for data binding with a new version of SIRI:

  1. Use tools such as [json gen] (http://jsongen.byingtondesign.com/) to generate POJOs based on SIRI JSON data

  2. Strip the XML annotations and other characteristics that are incompatible with Android from the SIRI JAXB classes to create true POJOs that work on Android. See the current SIRI POJO project wiki for details on how to perform this manual process.

Tutorials

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:

Clone this wiki locally