Package google.maps.playablelocations.v3

Index

PlayableLocations

The Playable Locations API for v3.

LogImpressions

rpc LogImpressions(LogImpressionsRequest) returns (LogImpressionsResponse)

Logs new events when playable locations are displayed, and when they are interacted with.

Impressions are not partially saved; either all impressions are saved and this request succeeds, or no impressions are saved, and this request fails.

LogPlayerReports

rpc LogPlayerReports(LogPlayerReportsRequest) returns (LogPlayerReportsResponse)

Logs bad playable location reports submitted by players.

Reports are not partially saved; either all reports are saved and this request succeeds, or no reports are saved, and this request fails.

SamplePlayableLocations

rpc SamplePlayableLocations(SamplePlayableLocationsRequest) returns (SamplePlayableLocationsResponse)

Returns a set of playable locations that lie within a specified area, that satisfy optional filter criteria.

Note: Identical SamplePlayableLocations requests can return different results as the state of the world changes over time.

Impression

Encapsulates impression event details.

Fields
location_name

string

Required. The name of the playable location.

impression_type

ImpressionType

Required. The type of impression event.

game_object_type

int32

An arbitrary, developer-defined type identifier for each type of game object used in your game.

Since players interact with differ types of game objects in different ways, this field allows you to segregate impression data by type for analysis.

You should assign a unique game_object_type ID to represent a distinct type of game object in your game.

For example, 1=monster location, 2=powerup location.

ImpressionType

The type of impression event.

Enums
IMPRESSION_TYPE_UNSPECIFIED Unspecified type. Do not use.
PRESENTED The playable location was presented to a player.
INTERACTED A player interacted with the playable location.

LogImpressionsRequest

A request for logging impressions.

Fields
impressions[]

Impression

Required. Impression event details. The maximum number of impression reports that you can log at once is 50.

request_id

string

Required. A string that uniquely identifies the log impressions request. This allows you to detect duplicate requests. We recommend that you use UUIDs for this value. The value must not exceed 50 characters.

You should reuse the request_id only when retrying a request in case of failure. In this case, the request must be identical to the one that failed.

client_info

ClientInfo

Required. Information about the client device. For example, device model and operating system.

LogImpressionsResponse

A response for the LogImpressions method. This method returns no data upon success.

LogPlayerReportsRequest

A request for logging your player's bad location reports.

Fields
player_reports[]

PlayerReport

Required. Player reports. The maximum number of player reports that you can log at once is 50.

request_id

string

Required. A string that uniquely identifies the log player reports request. This allows you to detect duplicate requests. We recommend that you use UUIDs for this value. The value must not exceed 50 characters.

You should reuse the request_id only when retrying a request in the case of a failure. In that case, the request must be identical to the one that failed.

client_info

ClientInfo

Required. Information about the client device (for example, device model and operating system).

LogPlayerReportsResponse

A response for the LogPlayerReports method.

This method returns no data upon success.

PlayerReport

A report submitted by a player about a playable location that is considered inappropriate for use in the game.

Fields
location_name

string

Required. The name of the playable location.

reasons[]

BadLocationReason

Required. One or more reasons why this playable location is considered bad.

reason_details

string

Required. A free-form description detailing why the playable location is considered bad.

language_code

string

Language code (in BCP-47 format) indicating the language of the freeform description provided in reason_details. Examples are "en", "en-US" or "ja-Latn". For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.

BadLocationReason

The reason why the playable location is considered bad.

Enums
BAD_LOCATION_REASON_UNSPECIFIED Unspecified reason. Do not use.
OTHER The reason isn't one of the reasons in this enumeration.
NOT_PEDESTRIAN_ACCESSIBLE The playable location isn't accessible to pedestrians. For example, if it's in the middle of a highway.
NOT_OPEN_TO_PUBLIC The playable location isn't open to the public. For example, a private office building.
PERMANENTLY_CLOSED The playable location is permanently closed. For example, when a business has been shut down.
TEMPORARILY_INACCESSIBLE The playable location is temporarily inaccessible. For example, when a business has closed for renovations.

SamplePlayableLocationsRequest

Life of a query:

  • When a game starts in a new location, your game server issues a SamplePlayableLocations request. The request specifies the S2 cell, and contains one or more "criteria" for filtering:

  • Criterion 0: i locations for long-lived bases, or level 0 monsters, or...

  • Criterion 1: j locations for short-lived bases, or level 1 monsters, ...
  • Criterion 2: k locations for random objects.
  • etc (up to 5 criterion may be specified).

PlayableLocationList will then contain mutually exclusive lists of PlayableLocation objects that satisfy each of the criteria. Think of it as a collection of real-world locations that you can then associate with your game state.

Note: These points are impermanent in nature. E.g, parks can close, and places can be removed.

The response specifies how long you can expect the playable locations to last. Once they expire, you should query the samplePlayableLocations API again to get a fresh view of the real world.

Fields
area_filter

AreaFilter

Required. Specifies the area to search within for playable locations.

criteria[]

Criterion

Required. Specifies one or more (up to 5) criteria for filtering the returned playable locations.

SamplePlayableLocationsResponse

Response for the SamplePlayableLocations method.

Fields
locations_per_game_object_type

map<int32, PlayableLocationList>

Each PlayableLocation object corresponds to a game_object_type specified in the request.

ttl

Duration

Required. Specifies the "time-to-live" for the set of playable locations. You can use this value to determine how long to cache the set of playable locations. After this length of time, your back-end game server should issue a new SamplePlayableLocations request to get a fresh set of playable locations (because for example, they might have been removed, a park might have closed for the day, a business might have closed permanently).