Public Transit stops

This API provides detailed access to public transport data including agencies, routes, stops, and trips. It is designed to integrate with interactive map-based applications using the Magic Lane SDK and allows developers to dynamically fetch and explore real-time public transportation information from selected positions on the map.

tip

The structure of the public transport data is modeled after the General Transit Feed Specification (GTFS) and offers access to a subset of the fields and entities defined in GTFS.

Query public transport overlays by screen position.
Retrieve structured information about transport agencies, stops, routes, and trips. You can filter the trips by:
route short name (tripsByRouteShortName)
route type (tripsByRouteType)
agency (tripsByAgency)

These can be accomplished by using the following methods of the PTStopInfo class:

tripsByRouteShortName(routeShortName: string): PTTrip[]
tripsByRouteType(routeType: PTRouteType): PTTrip[]
tripsByAgency(agency: PTAgency): PTTrip[]

Where:

PTTrip is the trip type (see below)
PTRouteType is the route type enum
PTAgency is the agency type

An example illustrating this is the following:

import { PTRouteType, PTTrip } from '@magiclane/maps-sdk';
const trips: PTTrip[] = ptStopInfo.tripsByRouteType(PTRouteType.bus);

Set a position on the map using setCursorScreenPosition.
Query for public transport overlays with cursorSelectionOverlayItemsByType or for generic overlays with cursorSelectionOverlayItems.
Retrieve stop information using getPTStopInfo() on each overlay item.
Use the returned PTStopInfo object to explore agencies, stops, and trips.
This API is part of a modular system intended to support rich and interactive transit applications.

An example of using this feature is the following:

import { GemMap, CommonOverlayId } from '@magiclane/maps-sdk';

let map: GemMap;

function onMapCreated(gemMap: GemMap) {
    map = gemMap;
    map.registerLongPressCallback(async (pos) => {
        await map.setCursorScreenPosition(pos);
        const items = map.cursorSelectionOverlayItemsByType(CommonOverlayId.PublicTransport);
        for (const item of items) {
            const ptStopInfo = await item.getPTStopInfo();
            if (ptStopInfo) {
                // Agencies
                const agencies = ptStopInfo.agencies;
                // Stops and generic routes
                const stops = ptStopInfo.stops;
                // Trips (with route, agency, stop times, real-time info, etc.)
                const trips = ptStopInfo.trips;

                // How to use stops
                for (const stop of stops) {
                    console.log(`Stop id: ${stop.stopId}`);
                    console.log(`Stop name: ${stop.stopName}`);
                    console.log('Routes:');
                    for (const route of stop.routes) {
                        console.log(`  Route id: ${route.routeId}`);
                        console.log(`  Route short name: ${route.routeShortName}`);
                        console.log(`  Route long name: ${route.routeLongName}`);
                    }
                }
            }
        }
    });
}

tip

You can also obtain instances of PTStopInfo by performing an overlay search using CommonOverlayId.publicTransport. Once you retrieve the corresponding OverlayItems, use their getPTStopInfo method to access the stop information.

See the Search guide for more details on searching.

warning

All returned times are local times. They are represented as DateTime values in UTC (timezone offset 0).

Use the TimezoneService to convert them to other time zones.

warning

There are two types of public transit stops on the map:

Stops which are of type OverlayItem and can be selected via the cursorSelectionOverlayItemsByType method. These stops provide extensive details structured as PTStopInfo objects. They are displayed with a blue icon when using the default style.
Stops which are of type Landmark and can be selected via the cursorSelectionLandmarks method. These stops do not provide extensive details. They are displayed with a gray icon when using the default style.

Agencies

The PTAgency class represents a public transport agency.

Property	Type	Description
`id`	`number`	Agency ID
`name`	`string`	Full name of the transit agency.
`url`	`string \| undefined`	Optional URL of the transit agency.

Public Transport Routes

The PTRouteInfo class represents a public transport route.

Property	Type	Description
`routeId`	`number`	Route ID
`routeShortName`	`string \| undefined`	Short name of a route. Often a short, abstract identifier (e.g., "32", "100X") that riders use to identify a route. May be undefined.
`routeLongName`	`string \| undefined`	Full name of a route. This name is generally more descriptive than the short name and often includes the route's destination or stop.
`routeType`	`PTRouteType`	Type of route.
`routeColor`	`Color \| undefined`	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.
`routeTextColor`	`Color \| undefined`	Legible color to use for text drawn against a background of `routeColor`.
`heading`	`string \| undefined`	Optional heading information.

warning

Do not confuse the PTRoute and PTRouteInfo classes.

PTRouteInfo provides information about the public transit routes available at a specific stop.
PTRoute, on the other hand, represents a computed public transit route between multiple waypoints and includes detailed instructions.

For more information on computing public transit routes using PTRoute, refer to the Compute Public Transit Routes section.

The type of public transport route is represented by the PTRouteType enum.

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

Stops

The PTStop class represents a public transport stop.

Property	Type	Description
`stopId`	`number`	Identifies a location: stop/platform, station, entrance/exit, node or boarding area
`stopName`	`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.
`isStation`	`boolean \| undefined`	Whether this location is a station or not. A station is considered a physical structure or area that contains one or more platforms.
`routes`	`PTRouteInfo[]`	Associated routes for the stop. Contains all routes serving this stop, whether active at the given time or not.

Stop Times

The PTStopTime class provides details about stop time in a PTTrip.

Property	Type	Description
`stopName`	`string`	The name of the serviced stop.
`coordinates`	`Coordinates`	WGS latitude and longitude for the stop.
`hasRealtime`	`boolean`	Whether data is provided in real-time or not.
`delay`	`number`	Delay in seconds. Not available if `hasRealtime` is false.
`departureTime`	`Date \| undefined`	Optional departure time in the local timezone.
`isBefore`	`boolean`	Whether the stop time is before the current time.
`isWheelchairFriendly`	`boolean`	Whether the stop is wheelchair accessible.

Trips

The PTTrip class represents a public transport trip.

Property	Type	Description
`route`	`PTRouteInfo`	Associated route
`agency`	`PTAgency`	Associated agency
`tripIndex`	`number`	Trip index
`tripDate`	`Date \| undefined`	The date of the trip
`departureTime`	`Date \| undefined`	Departure time of the trip from the first stop
`hasRealtime`	`boolean`	Whether real-time data is available
`isCancelled`	`boolean \| undefined`	Whether the trip is cancelled
`delayMinutes`	`number \| undefined`	Delay in minutes. Not available if `hasRealtime` is false.
`stopTimes`	`PTStopTime[]`	Details of stop times in the trip
`stopIndex`	`number`	Stop index
`stopPlatformCode`	`string \| undefined`	Platform code
`isWheelchairAccessible`	`boolean`	Whether the stop is wheelchair accessible.
`isBikeAllowed`	`boolean`	Whether bikes are allowed on the stop.

warning

Do not confuse the PTRoute and PTTrip classes.

The PTRouteInfo class represents the public-facing service that riders recognize, like “Bus 42” while a PTTrip is a single scheduled journey along that route at a specific time, with its own stop times and sequence.

In other words, the route is the line or service identity, and the trips are the individual vehicle runs that make up that service throughout the day.

Stop Info

The PTStopInfo class aggregates stop-related data including agencies, stops, and trips related to a specific public transit overlay item.

Property	Type	Description
`agencies`	`PTAgency[]`	Agencies serving the selected item
`trips`	`PTTrip[]`	Trips in which the selected item is involved
`stops`	`PTStop[]`	Stops associated with the trips

Public Transit

Agencies​

Public Transport Routes​

Stops​

Stop Times​

Trips​

Stop Info​

Relevant examples demonstrating public transit related features​

Agencies

Public Transport Routes

Stops

Stop Times

Trips

Stop Info

Relevant examples demonstrating public transit related features