Public Transit Stops

_|

This API provides access to public transport data including agencies, routes, stops, and trips. Fetch and explore real-time public transportation information from selected positions on the map.

Tip

The public transport data structure follows the General Transit Feed Specification (GTFS) and offers access to a subset of GTFS fields and entities.

Key features:

• Query public transport overlays by screen position
• Retrieve information about transport agencies, stops, routes, and trips
• Access real-time data including delays and cancellations
• View metadata about accessibility, bike allowances, and platform details
• Filter trips by route type, route short name, or agency

How it works:

• Set a position on the map using setCursorScreenPosition
• Query for public transport overlays with cursorSelectionOverlayItems
• Retrieve stop information using getPreviewExtendedData() on each overlay item of ECommonOverlayId::OID_PublicTransport type.
• Use the populated SearchableParameterList object to explore agencies, stops, and trips

---

Query Public Transit Stops

class MyMapViewListenerImpl : public IMapViewListener
{
public:

    void setMapView(StrongPointer<MapView> mv)
    {
        mapView = mv;
    }

    void onLongDown(const Xy &pos) override
    {
        // Set cursor position on the screen.
        mapView->setCursorScreenPosition(pos);

        // Wait for the map view to fully load the tiles

        // Get the overlay items at that position.
        auto items = mapView->cursorSelectionOverlayItems();

        // For each overlay item at that position.
        for (auto item : items) 
        {
            auto overlayId = item.getOverlayUid();

            // We're interested only in public tranposrt overlay items.
            if(overlayId == ECommonOverlayId::OID_PublicTransport)
            {
                // Declare the searchable parameter list that will get populated with the public transit data.
                SearchableParameterList ptStopInfo;

                item.getPreviewExtendedData(ptStopInfo, yourProgressListenerImpl);

                // Wait for the operation to complete (replace with your own synchronization mechanism).
                WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl ), 15000 );

                // Start using the information, it must contain data now.
                if (!ptStopInfo.empty()) 
                {
                    // Information about agencies.
                    auto agencies = ptStopInfo.find<gem::SearchableParameterList>(opid::kPT_agencies);

                    // Information about stops and generic routes
                    // (routes that don't have `heading` set)
                    auto stops = ptStopInfo.find<gem::SearchableParameterList>(opid::kPT_stops);

                    // Information about trips (together with 
                    // route, agency, stop times, real-time info, etc.)
                    auto trips = ptStopInfo.find<gem::SearchableParameterList>(opid::kPT_trips);

                    // Go through stops.
                    for (auto stop : stops.first) 
                    {
                        // Get the stop details.
                        auto stopDetails = stop.getValue<gem::SearchableParameterList>();

                        GEM_INFO_LOG("Stop id: %llu", stopDetails.find<gem::LargeInteger>(opid::kPT_stop_id).first);
                        GEM_INFO_LOG("Stop name: %s", stopDetails.find<gem::String>(opid::kPT_stop_name).first);

                        GEM_INFO_LOG("Routes:");

                        auto stopRoutes = stopDetails.find<gem::SearchableParameterList>(opid::kPT_stop_routes);

                        // Go through the routes that visit this stop
                        for (auto route : stopRoutes.first)
                        {
                            auto routeDetails = route.getValue<gem::SearchableParameterList>();

                            GEM_INFO_LOG("  Route id: %llu", routeDetails.find<gem::LargeInteger>(opid::kPT_route_id).first);
                            GEM_INFO_LOG("  Route short name: %s", routeDetails.find<gem::String>(opid::kPT_route_short_name).first);
                            GEM_INFO_LOG("  Route long name: %s", routeDetails.find<gem::String>(opid::kPT_route_long_name).first);
                        }
                    }
                }
            }
        }

    }
private:
    StrongPointer<MapView> mapView;
};

Tip

Obtain SearchableParameterList instances with public transit data by performing an overlay search using ECommonOverlayId::OID_PublicTransport. Retrieve the corresponding OverlayItems and use their getPreviewExtendedData method to access stop information.

See the Search on overlays guide for details.

danger

All returned times are local times represented as epoch time values in UTC (timezone offset 0). Use the TimezoneService to convert them to other time zones.

danger

Two types of public transit stops exist on the map:

• OverlayItem stops selected via cursorSelectionOverlayItems - provide extensive extendedData details and display with a blue icon (default style) - available only in Online mode.
• Landmark stops selected via cursorSelectionLandmarks - provide limited details and display with a gray icon (default style) - available in Offline mode.

The public transit overlay items might hide the equivalent landmarks in the same area.

---

Agencies

A SearchableParameterList containing an Agency has the following values:

Key	Type	Description
agency_id	int	Agency ID
agency_name	String	Full name of the transit agency.
agency_url	String	Optional URL of the transit agency.

---

Public Transport Routes

A SearchableParameterList containing a public transit Route has the following values:

Key	Type	Description
route_id	LargeInteger	Route ID
route_short_name	String	Short name of a route. Often a short, abstract identifier (e.g., "32", "100X") that riders use to identify a route. May be null.
rout_long_name	String	Full name of a route. This name is generally more descriptive than the short name and often includes the route's destination or stop.
route_type	int	Type of route. Check opid::pt::ERouteType values.
route_color	String	Route color designation that matches public-facing material. May be used to color the route on the map or to be shown on UI elements. In hex format.
route_text_Color	String	Legible color to use for text drawn against a background of routeColor. In hex format.
route_heading	String	Optional heading information.

Route Types

The opid::pt::EPTRouteType enum represents the type of public transport route:

Enum Case	Description
RT_Bus	Bus, Trolleybus. Used for short and long-distance bus routes.
RT_Underground	Subway, Metro. Any underground rail system within a metropolitan area.
RT_Railway	Rail. Used for intercity or long-distance travel.
RT_Tram	Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area.
RT_WaterTransport	Water transport. Used for ferries and other water-based transit.
RT_Misc	Miscellaneous. Includes other types of public transport not covered by the other categories.

---

Stops

A SearchableParameterList containing a public transit Stop has the following values:

Key	Type	Description
stop_id	LargeInteger	Identifies a location: stop/platform, station, entrance/exit, node or boarding area
stop_name	String	Name of the location. Matches the agency's rider-facing name for the location as printed on a timetable, published online, or represented on signage.
is_station	bool	Whether this location is a station or not. A station is considered a physical structure or area that contains one or more platforms.
routes	SearchableParameterList	Associated routes for the stop. Contains all routes serving this stop, whether active at the given time or not.

---

Stop Times

A SearchableParameterList containing a public transit Stop Time has the following values:

Key	Type	Description
stop_name	String	The name of the serviced stop.
departure_time	int	Optional departure time in the local timezone.
has_realtime	bool	Whether data is provided in real-time or not.
delay	int	Delay in seconds. Not available if has_realtime is false.
is_before	bool	Whether the stop time is before the current time.
stop_details	int	Bitwise details about bike or wheelchair accessibility.
lat	double	WGS latitude for the stop.
lon	double	WGS longitude for the stop.

---

Trips

A SearchableParameterList containing a public transit Trip has the following values:

Key	Type	Description
agency_id	int	Associated agency id.
trip_index	int	Trip index.
trip_date	int	The date of the trip as epoch.
departure_time	int	Departure time of the trip from the first stop as epoch.
has_realtime	bool	Whether real-time data is available.
is_cancelled	bool	Whether the trip is cancelled by realtime.
delay_minutes	int	Delay in minutes. Not available if has_realtime is false.
stop_times	SearchableParameterList	Details of stop times in the trip.
stop_index	int	The current stop index inside the whole list of stops that this trip passes through. This value changes based on which stop you tap on the map.
stop_platform_code	String	Platform code. For example inside train stations.
is_wheelchair_accessible	bool	Whether the stop is wheelchair accessible.
is_bike_allowed	bool	Whether bikes are allowed on the stop.

danger

A public transit Route represents the public-facing service riders recognize (e.g., "Bus 42"). A public transit Trip is a single scheduled journey along that route at a specific time with its own stop times and sequence. The route is the line identity; trips are individual vehicle runs throughout the day.

---

Public Transit Extended Data

A SearchableParameterList containing a public transit extended data has the following values:

Key	Type	Description
agencies	SearchableParameterList	Agencies serving the selected item.
trips	SearchableParameterList	Trips in which the selected item is involved.
stops	SearchableParameterList	Stops associated with the trips.

---

Relevant examples demonstrating public transit related features

• Public Transit Stop