HERE Android SDK Developer's Guide

Transit Information

Your application can use API calls from the HERE Android SDK 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.
Figure 1. MapTransitLayer set to show everything

To show only transit stops and accesses call:

// Assumes map is instantiated
map.getMapTransitLayer().setMode(MapTransitLayer.Mode.STOPS_AND_ACCESSES);
Figure 2. MapTransitLayer set to show only transit stops and accesses

To hide all transit information call:

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

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 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 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);
Figure 3. MapTransitLayer highlighting transit lines connected to the selected transit stop

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:

Figure 4. TransitStopObject: A metro station
Figure 5. TransitStopObject: A ferry station

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

The 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:

Figure 6. Three types of transit lines: Metro, Train and Water

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:

Figure 7. Transit Stop and Access: Metro Station with Single Access
Figure 8. Transit Stop and Access: Metro Station with Mutiple Accesses

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

The 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

The 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
  • getSystemWebsitUrl() - 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 tranit system's bicycle parking hours
  • getSystemLogo() - gets the system logo (if present)
  • getCompanyLogo() - gets the companyLogo (if presents)

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 the 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

The TransitDatabase class is responsible for querying transit information of various types using a unique Identifier , with a OnGetTransitInfoListener for monitoring query results and triggering appropriate callback methods upon completion. Applications can call the TransitDatabase constructor to activate a 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

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.