SDK for Android Developer's Guide

Transit Information

Your application can use API calls from SDK for Android to display transit information for users.

Note: The transit map schemes (NORMAL_DAY_TRANSIT, NORMAL_NIGHT_TRANSIT, and HYBRID_DAY_TRANSIT) are specifically designed for displaying transit information. You can opt to use one of these schemes when your app displays transit information.

MapTransitLayer

MapTransitLayer is a layer that displays the available transit data for a map area. To customize the transit layer, call Map.getMapTransitLayer() to access the methods available through the MapTransitLayer class. For example, to show all transit information available:

// Assumes map is instantiated
map.getMapTransitLayer().setMode(MapTransitLayer.Mode.EVERYTHING);

Note: MapTransitLayer settings may be affected when you change map schemes. For example, changing the map scheme to NORMAL_DAY_TRANSIT enables the "everything" mode. It is recommended that map scheme changes occur before changes in the MapTransitLayer.

To show only transit stops and accesses call:

// Assumes map is instantiated
map.getMapTransitLayer().setMode(MapTransitLayer.Mode.STOPS_AND_ACCESSES);

To hide all transit information call:

// Assumes map is instantiated
map.getMapTransitLayer().setMode(MapTransitLayer.Mode.NOTHING);

Transit Information Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/.

Highlighting Transit Objects

The following four types of transit data objects are available:

Transit Stop data - represented by TransitStopObject
Transit Line data - represented by TransitLineObject
Transit Access data - represented by TransitAccessObject
Transit Line Segment data - represented by TransitLineSegmentObject

Transit objects can be selected through tap gestures. For example, to highlight one or more TransitLineObject, you need to know the unique identifier of the line objects. Depending on the use case there are several ways of getting a single one or a list of Identifier objects:

Call TransitLineObject.getLineId() when a user has selected a TransitLineObject by tapping on it. It returns an Identifier of the selected transit line.
Call TransitStopObject.getTransitStopInfo().getLines() when a user has selected a TransitStopObject via tapping. getLines() returns a list of Identifier of the lines connected to the selected transit stop.

For details of handling tappable MapProxyObjects, see Handling MapProxyObject objects.

With a single one or a list of Identifier objects you call the following API to highlight the lines:

// Assumes map is instantiated and identifierList is
// filled with a list of Identifiers
map.getMapTransitLayer().highlightTransitLines(identifierList);

TransitStopObject

A TransitStopObject is a type of MapProxyObject that contains information about a transit stop. The following figures show the different types of transit stops:

To acquire information about a tapped TransitStopObject (see Handling MapProxyObject objects ) use onMapObjectsSelected(List<ViewObject>) as follows:


private MapGesture.OnGestureListener listener = new MapGesture.OnGestureListener() {
...
@Override
public boolean onMapObjectsSelected(List<ViewObject> objects) {
  for (ViewObject obj : objects) {
    if (obj.getBaseType() == ViewObject.Type.PROXY_OBJECT) {
      MapProxyObject proxyObj = (MapProxyObject) obj;
      if (proxyObj.getType() == MapProxyObject.Type.TRANSIT_STOP) {
        TransitStopObject transitStopObj
            = (TransitStopObject) proxyObj;
        Log.d(TAG, "Found a TransitStopObject");
        Log.d(TAG, "position is "
          + transitStopObj.getCoordinate().toString());
        TransitStopInfo transitStopInfo
            = transitStopObj.getTransitStopInfo();
        ...
    }
  }
  return true;
}

The TransitStopObject provides two methods for getting information about the transit stop:

getCoordinate() gets the location coordinates of the transit stop
getTransitStopInfo() gets further information about the transit stop

TransitStopInfo

TransitStopInfo class contains transit stop information that is accessed by calling one or more of the following methods:

getOfficialName() - gets the official name of the transit stop
getInformalName() - gets the informal name of the transit stop
getId() - gets the Identifier of the transit stop
getTransitTypes() - gets the transit types this transit stop belongs to; there can be more than one.
getLines() - gets a list of Identifier objects for transit lines connected to this transit stop

Each Identifier is submitted to the TransitDatabase to get further information. For more details see TransitDatabase. Also they can be submitted to the MapTransitLayer to get highlighted on the map. (See MapTransitLayer)

An example of getting information about the first transit line connected to the transit stop is provided below. A TransitDatabase.OnGetTransitInfoListener needs to be implemented to receive the TransitLineInfo. (See TransitLineInfo)

An asynchronous request is submitted to the TransitDatabase along with the OnGetTransitInfoListener.

TransitDatabase.OnGetTransitInfoListener listener
= new TransitDatabase.OnGetTransitInfoListener() {
......
  @Override
  public void onTransitLineInfo(TransitLineInfo info) {
    ......
  }

// transitStopInfo is a TransitStopInfo object
......
mTransitDatabase.getLineInfo(transitStopInfo.getLines().get(0), listener);

TransitLineObject

A TransitLineObject is a type of MapProxyObject that contains information about a transit line. The following figure shows examples of different types of transit lines:

To acquire information about a tapped TransitLineObject (see Handling MapProxyObject objects ) use onMapObjectsSelected(List<ViewObject>) as illustrated in the following code:


private MapGesture.OnGestureListener listener = new MapGesture.OnGestureListener() {
...
@Override
public boolean onMapObjectsSelected(List<ViewObject> objects) {
  for (ViewObject obj : objects) {
    if (obj.getBaseType() == ViewObject.Type.PROXY_OBJECT) {
      MapProxyObject proxyObj = (MapProxyObject) obj;
      if (proxyObj.getType() == MapProxyObject.Type.TRANSIT_LINE) {
        TransitLineObject transitLineObj
            = (TransitLineObject) proxyObj;
        Log.d(TAG, "Found a TransitLineObject");
        Log.d(TAG, "Id is "
          + transitLineObj.getLineId().toString());
        mTransitDatabase.getLineInfo(m_lineIdList.get(0),
                mOnGetTransitInfoListener);
      }
    }
  }
  return true;
}

The TransitLineObject provides a single method for getting the Identifier of the transit line. This Identifier can be submitted to the MapTransitLayer to get highlighted on the map. (For more information refer to MaptransitLayer)

As shown in the example above, the Identifier can also be submitted to the TransitDatabase (see TransitDatabase) along with the OnGetTransitInfoListener to get more information about the transit line. mOnGetTransitInfoListener is implemented to receive the TransitLineInfo object from the TransitDatabase.

TransitDatabase.OnGetTransitInfoListener mOnGetTransitInfoListener
= new TransitDatabase.OnGetTransitInfoListener() {
  ...
  @Override
  public void onTransitLineInfo(TransitLineInfo info) {
  ...
  }
}

TransitLineInfo

The TransitLineInfo class contains transit line information that is accessed by calling one or more of the following methods:

getOfficialName() - gets the official name of the transit line
getInformalName() - gets the informal name of the transit line
getShortName() - gets the short name of the transit line
getTransitType() - gets the transit types this transit line belongs to

TransitAccessObject

A TransitAccessObject is a type of MapProxyObject that contains information about a transit access. A transit access is an entrance/exit to a transit stop. There can be multiple transit accesses to a transit stop.

Transit access is presented as a smaller transit stop with a downward triangle attached to the bottom and is visible only in higher zoom levels. The icons presenting the transit stops and access vary between different countries and companies. The following figures show two examples:

To acquire information about a tapped TransitAccessObject (see Handling MapProxyObject objects) use onMapObjectsSelected(List<ViewObject>) as in the following code:


private MapGesture.OnGestureListener listener = new MapGesture.OnGestureListener() {
...
@Override
public boolean onMapObjectsSelected(List<ViewObject> objects) {
  for (ViewObject obj : objects) {
    if (obj.getBaseType() == ViewObject.Type.PROXY_OBJECT) {
      MapProxyObject proxyObj = (MapProxyObject) obj;
      if (proxyObj.getType() == MapProxyObject.Type.TRANSIT_ACCESS) {
        TransitAccessObject transitAccessObj
                = (TransitAccessObject) proxyObj;
        Log.d(TAG, "position is " +
            transitAccessObj.getCoordinate().toString());
        TransitAccessInfo transitAccessInfo
              = transitAccessObj.getTransitAccessInfo();
        ...

        break;
        }
    }
  }
  return true;
}

The TransitAccessObject provides two methods for getting information about the transit access:

getCoordinate() - gets the location coordinates of the transit access
getTransitAccessInfo() - gets further information about the transit access

TransitAccessInfo

TransitAccessInfo class contains transit access information that can be accessed by calling one or more of the following methods:

getTransitTypes() - gets the transit types this transit access belongs to; there can be more than one
getStopId() - gets a unique Identifier of the transit stop that this transit access leads to

In the next example the unique identifier of the transit stop is submitted to the TransitDatabase to get further information. For more details see TransitDatabase.

// transitAccessInfo is a TransitAccessInfo object
Log.d(TAG, "transit type is " +
  transitAccessInfo.getTransitTypes().toString());
Log.d(TAG, "Stop Id is " +
  transitAccessInfo.getStopId().toString());
mTransitDatabase.getStopInfo(transitAccessInfo
    .getStopId(), mOnGetTransitInfoListener);

An example of getting information about the destination transit stop of a transit access is provided below. An OnGetTransitInfoListener needs to be implemented to receive the TransitStopInfo object. An asynchronous request is submitted to the TransitDatabase along the OnGetTransitInfoListener. For more information see TransitStopInfo.

TransitDatabase.OnGetTransitInfoListener mOnGetTransitInfoListener
= new TransitDatabase.OnGetTransitInfoListener(){
  ......
  @Override
  public void onTransitStopInfo(TransitStopInfo info) {
    ......
  }
}

// transitAccessInfo is a TransitAccessInfo object
......
mTransitDatabase.getStopInfo(transitAccessInfo.getStopId(),
      mOnGetTransitInfoListener);

TransitSystemInfo

TransitSystemInfo class contains information about a public transit system that can be accessed by calling one or more of the following methods:

getSystemOfficialName() - gets the official name of the transit system
getSystemWebsiteUrl() - gets the website URL of the transit system
getCompanyOfficialName() - gets the official transit system company name
getCompanyWebsiteUrl() - gets the website URL of the transit system company
getCompanyRoutePlannerUrl() - gets the route planner URL of the transit system company
getCompanyScheduleUrl() - gets the schedule url of the transit system company
getCompanyPhone() - gets the phone number for the transit system company
getBicycleHours() - gets the transit system's bicycle parking hours
getSystemLogo() - gets the system logo (if any)
getCompanyLogo() - gets the companyLogo (if any)

An example of retrieving transit system information is provided below. In this example an OnGetTransitInfoListener is implemented to receive the TransitSystemInfo object. For more information see TransitDatabase section.

TransitDatabase.OnGetTransitInfoListener mOnGetTransitInfoListener =
  new TransitDatabase.OnGetTransitInfoListener() {
  ...
  @Override
  public void onTransitSystemInfo(TransitSystemInfo systemInfo) {
    String officialName = systemInfo.getSystemOfficialName();
  }
  ...
}


// transitLineInfo is a TransitLineInfo object
mTransitDatabase.getSystemInfo(transitLineInfo.getSystemId(),
  mOnGetTransitInfoListener);

TransitDatabase

TransitDatabase class is responsible for querying transit information of various types using a unique Identifier with an OnGetTransitInfoListener for monitoring query results and triggering appropriate callback methods upon completion. Applications can call the TransitDatabase constructor to activate the TransitDatabase for querying transit information.

The OnGetTransitInfoListener interface can be used to monitor query results of the TransitDatabase. It must be implemented within the application and submitted as part of the asynchronous query request.


TransitDatabase.OnGetTransitInfoListener mOnGetTransitInfoListener
  = new TransitDatabase.OnGetTransitInfoListener() {

  @Override
  public void onTransitLineInfo(TransitLineInfo info) {
    //...
  }

  @Override
  public void onTransitStopInfo(TransitStopInfo info) {
    //...
  }

  @Override
  public void onTransitAccessInfo(TransitAccessInfo info) {
    //...
  }

  @Override
  public void onTransitSystemInfo(TransitSystemInfo info) {
    //...
  }

  @Override
  public void onEnd(TransitDatabase.Error error) {
    //...
  }
};

The OnGetTransitInfoListener class provides five callbacks:

onTransitLineInfo provides a TransitLineInfo object. (See TransitLineInfo)
onTransitStopInfo provides a TransitStopInfo object. (See TransitStopInfo)
onTransitAccessInfo provides a TransitAccessInfo object. (See TransitAccessInfo)
onTransitSystemInfo provides a TransitSystemInfo object. (See TransitSystemInfo)
onEnd is a callback that signifies the asynchronous query request has completed.
Note: TransitDatabase rejects all subsequent requests unless it has completed the current request. If the TransitDatabase is busy, INVALID_OPERATION is returned.

An asynchronous request is submitted to the TransitDatabase along with the OnGetTransitInfoListener. Note that the TransitDatabase instance is created by calling the TransitDatabase constructor.

The following lists the main use cases of the TransitDatabase:

getLineInfo() - pass in TransitLineObject.getLineId() when a user has selected a TransitLineObject by tapping on it. This method returns an Identifier of a selected transit line.
```
// transitLineObject is a TransitLineObject object
......
mTransitDatabase.getLineInfo(transitLineObject
          .getLineId(), mOnGetTransitInfoListener);
```

getLineInfo() - pass in TransitStopObject.getTransitStopInfo().getLines() when a user has selected a TransitStopObject by tapping on it. This method returns a list of Identifiers for the lines connected to the selected transit stop.

// transitStopInfo is a TransitStopInfo object
......
// Requesting transit line info of the first identifier on the list
mTransitDatabase.getLineInfo(transitStopInfo
          .getLines().get(0), mOnGetTransitInfoListener);

getStopInfo() - pass in TransitAccessInfo.getStopId() when a user has selected a TransitAccessObject by tapping on it. This method returns an Identifier of the stop that the transit access leads to.
```
// transitAccessInfo is a TransitAccessInfo object
......
mTransitDatabase.getStopInfo(transitAccessInfo
         .getStopId(), mOnGetTransitInfoListener);
```

Transit-related enumerations

The TransitType enum - represents values describing different transit types such as BUS_PUBLIC, RAIL_METRO or TRAIN_REGIONAL
The TransitDatabase.Error enum - represents values describing possible transit database errors such as NONE or INVALID_PARAMETERS