Stop-only Integration

  • This document outlines the specifications for a "Stop-only" integration, where partners who don't provide full GTFS feeds can still integrate with Google Maps.

  • Partners must provide a stop feed file, containing required information like stop_id, stop_name, stop_lat, and stop_lon to identify each stop or station.

  • A market set feed is optional and can be used to define specific origin/destination pairs that will be enabled, with any pairs not included being disabled.

  • Ticketing deep links are constructed using a base URL provided by the partner, appended with parameters like from_ticketing_stop_time_id, to_ticketing_stop_time_id, service_date, boarding_time, and arrival_time to specify the trip details.

  • The Partner API parameters for GetTripOptionsRequest use a reduced set of SegmentKeys based on the deep link specification, specifying each segment of the route with multiple SegmentKeys.

Overview

If you are not the provider of the GTFS feeds for Google Maps, your integration is Stop-only. For this integration we need to understand how you identify the different train or bus stops.

General feed specifications

When starting the integration, we create a unique identifier for each integration, for example: ch_google_test (country code, partner name, integration) or eu_google (region code, partner name).

Partners provide a file containing text files in CSV format that are applied per integration. Each CSV file must contain a header row with column names that match the "Field Name" specified in the corresponding feed specification table.

To allow partner to upload new versions of the stops and markets files, our team will share SFTP dropbox details, one for each type of file during the onboarding process.

Stop feed specification (required)

The stop file should contain the following columns:

Field Name Type (see GTFS) Description
stop_id ID (required) The unique identifier that identifies a stop or station. Larger stations should only contain a single entry. This is used when making calls to your Partner Server API and in the ticketing deep links.
stop_name Text (required) A human readable name for debugging stop mapping, cache filling & price accuracy data.
stop_lat Latitude (required) Latitude of the stop.
stop_lon Longitude (required) Longitude of the stop.

We will use an automated ingestion process where partners can continuously provide updated zip files when information contained therein changes. For example, a partner may expand the inventory provided by extending the list of stops. However, similar to GTFS, stop_ids should be stable.

Market set feed specification (optional)

With the mapped stops, we generate the market set for this integration (a list containing popular origin / destination pairs). From there, you have the option to reduce this set of markets by proving a market set feed.

The market set acts as an allowlist for our cache fill service. By default, if no market set is provided, all markets are enabled. If you provide a market set, only the markets included in the list will be queried. If users query markets outside of this allow-list, our systems will still send a live query for the particular market and date requested, but we won't try to proactively cache it.

The market set file should contain the following columns:

Field Name Type (see GTFS) Description
origin_stop_id ID (required) The origin stop_id of the market.
destination_stop_id ID (required) The destination stop_id of the market.

Partner Configuration

When using the stop-only integration, we require extra information for the static partner configuration as outlined in the Partner Configuration section.

The format and parameters of the booking link (also called Ticketing link) are defined in Ticketing Links

Partner API parameters

The SegmentKeys parameters for the Partner API (GetBulkTripOptionsRequest) are based on the deep link specification. We use SegmentKeys including only from_ticketing_stop_time_id, to_ticketing_stop_time_id, service_date, boarding_time and arrival_time, leaving ticketing_trip_id empty. We will fully specify the route including all transfers by specifying multiple SegmentKeys, one per segment.