HERE iOS SDK Developer's Guide

Transit Information

Your application can use API calls from the HERE iOS SDK to display transit information for users.

Note: The transit map schemes (NMAMapSchemeNormalDayTransit, NMAMapSchemeNormalNightTransit, and NMAMapSchemeHybridDayTransit) are specifically designed for displaying transit information. You can optionally use one of these map schemes when your app displays transit information.

NMAMapTransitDisplayMode

Map transit data is displayed as a layer over a map area. To customize this transit layer, set the transitDisplayMode property available in the NMAMapView class. For example, to show all transit information available:

// Assumes map is instantiated
mapView.transitDisplayMode = NMAMapTransitDisplayModeEverything;
Figure 1. MapTransitLayer set to show everything

To show only transit stops and accesses, call:

// Assumes map is instantiated
mapView.transitDisplayMode = NMAMapTransitDisplayModeStopAndAccess;
Figure 2. MapTransitLayer set to show only transit stops and accesses

To hide all transit information call:

// Assumes map is instantiated
mapView.transitDisplayMode = NMAMapTransitDisplayModeNothing;
Note: transitDisplayMode settings may be affected when you change map schemes. For example, changing the map scheme to NMAMapSchemeNormalDayTransit enables the "everything" mode. It is advisable that map scheme changes occur before changes in the transitDisplayMode.

Highlighting Transit Objects

The following four types of transit data objects are available:
  • Transit Stop data - represented by NMATransitStop
  • Transit Line data - represented by NMATransitLine
  • Transit Access data - represented by NMATransitAccess
  • Transit System Info data - represented by NMATransitSystem

These types of data are represented by NMATransitObject presentation objects, which are child instances of NMAProxyObject. They can be selected through tap gestures and passed to the NMATransitManager to request for the appropriate data object.

The following is an example of using an NMATransitObject to retrieve a data object. If the tapped object was a tranist line, then your application receives the transitManager:didGetLineInfo:forId: callback with a populated NMATransitLine. Note that the retrieved transit data object has the same uniqueId as transitObject.


//assuming that this class adopts the NMATransitManagerDelegate protocol
[NMATransitManager sharedTransitManager].delegate = self;
//the transitObject is an NMATransitObject
[[NMATransitManager sharedTransitManager] requestInfoForObject:transitObject];

Depending on the use case, there are several ways of getting a single or a list of Identifier objects from a transit line.

  • Use the uniqueId property when the user has selected a NMATransitLine
  • Use the NMATransitStop.lineIds property when the user has selected an NMATransitStop. It returns a list of Identifier of the lines connected to this selected transit stop.

For details of handling tappable NMAProxyObject, see Objects and Interaction.

With a single or a list of unique identifiers, you can call the following API to highlight the lines:

// Assumes mapView is instantiated and uniqueId is a valid identifier
[mapView.mapTransitLayer highlightTransitLinesFromUniqueIds:@[uniqueId]];
Figure 3. MapTransitLayer highlighting transit lines connected to the selected transit stop

NMATransitStop

An NMATransitStop object contains information about a transit stop. The following figures show the different types of transit stops:

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

To acquire the TransitStopObject, implement the transitManager:didGetStopInfo:forId: method in the NMATransitManagerDelegate protocol and perform a request from NMATransitManager.

The TransitStopObject class provides the following properties for getting information about the transit stop:

  • location - gets the location coordinates of the transit stop
  • officialName - gets the official name of the transit stop
  • informalName - gets the informal name of the transit stop
  • uniqueId - gets the identifier of the transit stop
  • systemIds - gets the transit system this transit stop belongs to, it can be more than one
  • lineIds - gets a list of Identifier objects for transit lines connected to this transit stop

You can also use the hasTransitType:type method to see whether this stop supports a transit type. For example, a transit stop may support both public bus and a metro railway.

NMATransitLine

An NMATransitLine object contains information about a transit line. The following figure show some examples of different types of transit lines:

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

To acquire the NMATransitLine, implement the transitManager:didGetLineInfo:forId: method in the NMATransitManagerDelegate protocol and perform a request from NMATransitManager.

NMATransitLine provides a unique identifier as a class property. This identifier can be submitted to the NMAMapTransitLayer to highlight this line on the map.(see NMAMapTransitDisplayMode)

The NMATransitLine class contains transit line information in the following properties:

  • officialName gets the official name of the transit line
  • informalName gets the informal name of the transit line
  • shortName gets the short name of the transit line
  • transitType gets the transit types (NMATransitType) that this transit line belongs to
  • color gets the color associated with the line, if available
  • systemId - gets the transit system this transit line belongs to
  • uniqueId - gets the identifier of the transit line

NMATransitAccess

An NMATransitAccess object 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, that is only visible in higher zoom levels. The icons presenting the transit stops and accesses 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 Multiple Accesses

To acquire the NMATransitAccess, implement the transitManager:didGetAccessInfo:forId: method in the NMATransitManagerDelegate protocol and perform a request from NMATransitManager.

The NMATransitAccess provides the following properties for getting information about the transit access:

  • location gets the location coordinates of this transit access.
  • name gets the name of this transit access
  • stopId gets a unique identifier of the transit stop that this transit access leads to.
  • uniqueId - gets the identifier of the transit line

NMATransitSystem

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

  • officialName - gets the official name of the transit system
  • website - gets the website URL of the transit system
  • companyOfficialName - gets the official transit system company name
  • companyWebsite - gets the website URL of the transit system company
  • companyRoutePlannerWebsite - gets the route planner URL of the transit system company
  • companyScheduleWebsite - gets the schedule url of the transit system company
  • companyTelephoneNumber - gets the phone number for the transit system company

To acquire the NMATransitSystem, implement the transitManager:didGetSystemInfo:forId: method in the NMATransitManagerDelegate protocol and perform a request from NMATransitManager.

NMATransitManager

The NMATransitManager class is responsible for querying transit information of various types from a unique identifier, with an NMATransitManagerDelegate for monitoring query results and triggering appropriate callback methods upon completion. Applications can call the [NMATransitManager sharedTransitManager] class method to retrieve a NMATransitManager for querying transit information.

NMATransitManagerDelegate can be used to monitor query results from the NMATransitManager. It is required to be implemented within the application and submitted as part of the asynchronous query request.

The NMATransitManagerDelegate protocol contains the following callbacks:

  • transitManager:didGetLineInfo:forId: provides a NMATransitLine object.
  • transitManager:didGetStopInfo:forId: provides a NMATransitStop object.
  • transitManager:didGetAccessInfo:forId: provides a NMATransitAccess object.
  • transitManager:didGetSystemInfo:forId: provides a NMATransitSystem object.
  • transitManager:didCompleteWithError: signifies the asynchronous query request has completed. Please note that NMATransitManager rejects all subsequent requests unless it has completed the current request. An NMATransitManagerErrorBusy results if the NMATransitManager is busy. 

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

Transit-related enumerations

  • The NMATransitObjectType enum - represents values describing different transit object types: NMATransitObjectTypeAccess, NMATransitObjectTypeLine or NMATransitObjectTypeStop
  • The NMATransitType enum - represents values describing possible types of transit, such as NMATransitTypePublicBus, NMATransitTypeLightRail or NMATransitTypeWater