The following tutorial describes how to define multi-location services (e.g. services that span across multiple points of interests). This tutorial is most relevant for partners in the ticketing space.
Example use cases:
- A one-day tour in San Francisco that starts from the Financial District and visits a few local attractions. Hotel pick-up is available at a few popular nearby hotels
- A hop-on, hop-off bus tour in Paris where the user can choose to visit as many locations as supported by the tour.
- A combination ticket that can be used to visit the “Statue of Liberty”, “Top of the Rock” and the “Empire Building”
Key Definitions
- Merchant: The provider of the service (e.g. tour agency, operator, etc.)
- Service: The service provided by the merchant (e.g. tour, activity, etc.).
- Service Locations: The locations related to the service (e.g. the points of interest visited as part of the service, hotel pick-up, etc.).
- Start/Meeting Location(s): The location where the service begins. You
can also specify pick-up or meeting locations.
- The start/meeting location(s) are displayed to users via custom intake forms (for selection), and to inform the users of the start/meeting location(s) on the UI.
- Visited Location(s): The locations that are critical or closely related to the service
- The visited location(s) are used to determine where the service will show up on various Google surfaces. There is no guarantee the POI of the visited location will show the service.
- End Location: The location where the service ends.
- Start/Meeting Location(s): The location where the service begins. You
can also specify pick-up or meeting locations.
All locations are used to improve the UI on the detailed activity pages (e.g. map pins, indication of location opening hours, etc.)
Adding Service Locations
Service Feed
In the service feed, specify service locations (if applicable). To do this,
set the new Location
field. This is a repeated field, so you can set multiple locations.
// Geographic information about a location. message Location { // The Place ID for a place in the Google Places database and on Google Maps. // See https://developers.google.com/places/place-id for more about Place IDs. // If this is provided, Google will match the location to this place. (optional) string place_id = 1; // The location's name, telephone, url and geo are used to support matching // the location with places already present on Google Maps. It is recommended // to provide the location name if possible. (optional) // // The name of the location. (optional) string name = 2; // The public telephone number of the location including its country and area // codes, e.g. +14567891234. (optional) string telephone = 3; // The url of the location's public website. (optional) string url = 4; // The Geo info of the location, including latitude, longitude, and address. // (optional) GeoCoordinates geo = 5; // Optional text to provide more precise description of the location, or // instructions assisting locating the place. E.g. "Front entrance of the // library", "meet at the intersect of Road A and Street B". (optional) Text description = 6; // The type of the location, must be supplied if this location is provided for // a Service. LocationType location_type = 7; // Unique reference of the location within the service. This id can be used to // refer to this location in other service fields. E.g in the custom intake // form, a set of location ids can be used to specify pick up location // options. If set, this id should be unique within the same service. // (optional) string location_id = 8; } enum LocationType { // Location type unspecified. LOCATION_TYPE_UNSPECIFIED = 0; // The location where this service visits. VISITED_LOCATION = 1; // The location where this service starts, also serves as MEETING_LOCATION/START_LOCATION. START_LOCATION = 2; // The location where this service ends. END_LOCATION = 3; }
Optionally, set specific instructions of the location using
description
(e.g. Meet at the front desk of Hotel A)If using custom intake forms (e.g. user can select from a list of hotel pick-up locations), set
location_id
.
Adding Hotel Pick-up
Service Feed
If your service supports hotel pick-up from multiple locations, you can implement this feature in the service feed.
- Set a service location with
location_id
set - Set
intake_form
and add thelocation_id
to it
Example Hotel pick-up Service Feed
{ "location": [ { "name": "Hilton Hawaiian Village Waikiki Beach Resort", "geo": { "latitude": 21.283949, "longitude": -157.836151, "unstructured_address": "2005 Kalia Road Honolulu, Hawaii 96815 United States" }, "location_type": "START_LOCATION", "location_id": "hotel-1" }, { "name": "Fairmont Orchid - Hawaii", "geo": { "latitude": 19.950553, "longitude": -155.859931, "unstructured_address": "1 North Kaniku Drive Kohala Coast, Waimea Hawaii 96743 United States" }, "location_type": "START_LOCATION", "location_id": "hotel-2" }, { "name": "Manago Hotel Restaurant", "geo": { "latitude": 19.489207, "longitude": -155.910936, "unstructured_address": "82-6155 Mamalahoa Highway Captain Cook, Hawaii 96704 United States" }, "location_type": "START_LOCATION", "location_id": "hotel-3" } ], "intake_form": { "field": [ { "type": "LOCATION_SEARCH", "label": "Please select the pick up hotel below:", "value": [ "hotel-1", "hotel-2", "hotel-3" ], "is_required": true, "id": "hotel-pick-up-form-1" } ] } }
If the location_id
in the intake_form
is not found in the list of service
locations, the field will not show up in the form.
CreateOrderResponse
When the user buys the tickets, the CreateOrderResponse should return the responses the user filled out in the custom intake form.
// User's answers to merchant questions. message IntakeFormAnswers { repeated IntakeFormFieldAnswer answer = 1; } message IntakeFormFieldAnswer { // This id should be the same as the id of the corresponding question. string id = 1; // The response given by the user. // One string for MULTIPLE_CHOICE, DROPDOWN, SHORT_ANSWER, and PARAGRAPH // One string ("true" or "false") for BOOLEAN // One or more strings for CHECKBOXES. // For LOCATION_SEARCH, the response could be: // 1. Matches one of the "location_id" in the "location" field in the // service feed. // 2. User input answer containing location information that are not // provided in the feed. repeated string response = 2; }
Example Hotel pick-up CreateOrderResponse
{ "order": { "order_id": "order-1", "merchant_id": "100001", "item": [ { "service_id": "1000", "start_sec": "1546647234", "duration_sec": 3600, "tickets": [ { "ticket_id": "ticket-1", "count": 1 } ], "price": { "price_micros": 100000000, "currency_code": "USD" }, "status": "CONFIRMED", "intake_form_answers": { "answer": [ { "id": "hotel-pick-up-form-1", "response": "hotel-1" } ] } } ], "user_information": { "email": "johnsmith@gmail.com", "family_name": "John", "given_name": "Smith", "telephone": "+1 800-123-4567", "user_id": "2017492857928759285" } }, "payment_processing_parameters": { ... }, "idempotency_token": "1239874" }
The response
field should be used to indicate the location_id
the user
selected or a custom location for pick-up if the pick-up address is not found
in the provided locations.