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.

SearchPlayableLocations

rpc SearchPlayableLocations(SearchPlayableLocationsRequest) returns (SearchPlayableLocationsResponse)

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

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

AccessType

A set of values that specifies the type of access a venue provides.

Enums
ACCESS_TYPE_UNSPECIFIED Unspecified access type. Do not use.
FREE Accessible to the general public without restrictions. For example, parks, playgrounds, and town squares.
PAID

Restricted to paying customers and members. For example, golf courses, amusement parks, and zoos.

Google recommends that you make game objects placed within paid locations visible to players when they come within 100 meters of them.

Address

Encapsulates the address of a playable location.

Fields
language_code

string

The language code, in BCP-47 format. It indicates the language that the address is written in.

For example, "en", "en-US", and "ja-Latn".

For more information, see Unicode Locale Identifier.

flags[]

LanguageFlag

A collection of flags that specifies additional details about the language of the address, such as whether it's in a language local to the region.

formatted[]

FormattedAddress

The formatted addresses defined for this language code.

AreaFilter

Specifies the area to search for playable locations.

Fields
s2_cell_id

fixed64

Required. The S2 cell ID of the area you want. This must be between cell level 11 and 16 (inclusive).

S2 cells are 64-bit integers that identify areas on the Earth. They are hierarchical, and can therefore be used for spatial indexing.

The S2 geometry library is available in a number of languages:

point_exclusions[]

PointExclusion

Specifies playable locations to exclude when searching for playable locations. For example, these could be for locations that are already used in the game by user-generated "bases" or "supply boxes".

ArtisticallyInteresting

Specifies a ranking modifier that is based on how artistically interesting people find a place.

Fields
artistically_interesting

ArtisticallyInterestingModifier

When you don't specify an artistically_interesting value, then this modifier won't be used to rank playable locations.

ArtisticallyInterestingModifier

A set of values that specify how artistically interesting people find a place.

Enums
MODIFIER_UNSPECIFIED Not specified. Do not use.
INTERESTING

People tend to find this place artistically interesting.

Places that are artistically interesting are ranked higher. For example, museums and theaters.

BiomeTypeProto

Encapsulates a biome.

BiomeType

A set of values that specify the type of biome associated a playable location.

Enums
UNKNOWN The biome type is unknown.
FOREST Forest. Dominated by trees.
SHRUBLAND Shrubland. Dominated by woody perennials
SAVANNA Savanna. Sparse tree coverage.
GRASSLAND Grassland. Dominated by herbaceous annuals.
WETLAND Wetland. Areas covered by water and with vegetated cover.
CROPLAND Cropland. Cultivated cropland.
URBAN Urban. Urban and built up areas.
SNOW_ICE Snow or ice. Covered by snow and ice at least 10 months of the year.
BARREN Barren. Non-vegetated barren (sand, rock, soil) areas
WATER Water. Bodies of water.

Busyness

Specifies a ranking modifier that is based on how often venues are frequented.

Fields
busyness

BusynessModifier

Specifies an activity level ranking modifier as one of the BusynessModifier enumeration values.

When you don't specify a busyness value, then this modifier won't be used to rank playable locations.

BusynessModifier

A set of values that specify your preferred degree of busyness. That is, whether a lot or just a few people regularly frequent a location.

Enums
MODIFIER_UNSPECIFIED Not specified.
MORE_BUSY_BETTER Ranks busier places higher.
LESS_BUSY_BETTER Ranks less busy places higher.

Capacity

Specifies a ranking modifier that is based on venue capacity.

Fields
capacity

CapacityModifier

Specifies a capacity ranking modifier as one of the CapacityModifier enumeration values.

When you don't specify a capacity value, then this modifier won't be used to rank playable locations.

CapacityModifier

A set of values that specifies your preferred capacity. That is, whether the venue can accommodate a large crowd.

Enums
MODIFIER_UNSPECIFIED Not specified.
LARGE Larger venues are ranked higher.

ContentRating

A set of values that specifies the age range of the audience that playable locations are appropriate for.

By default, the Playable Locations API serves playable locations that are appropriate for use by players of all ages. But if your game targets adult players only, then you have the option of including playable locations associated with age-restricted venues like bars, casinos, and nightclubs.

Enums
CONTENT_RATING_UNSPECIFIED Unspecified. Not used.
EVERYONE The set of playable locations that are appropriate for use by children and young adults underthe age of 21. I.e., playable locations that contain no adult-oriented content.
ADULTS_ONLY The set of playable locations that are appropriate for use by adults over the age of 21. This set includes EVERYONE.

Criterion

Encapsulates a filter criterion for searching for a set of playable locations.

Fields
game_object_type

int32

Required. An arbitrary, developer-defined identifier of the type of game object that the playable location is used for. This field allows you to specify criteria per game object type when searching for playable locations.

Since players interact differently with different types of game objects, this field allows you to segregate impression data for targeted data analysis.

You should assign a unique game_object_type ID across all request_criteria to represent a distinct type of game object. For example, 1=monster location, 2=powerup location.

The response contains a map<game_object_type, Response>.

filter

Filter

Specifies filtering options, and specifies what will be included in the result set.

ranking

Ranking

Specifies ranking options. Note that this will not be implemented for v3. We're including it at this point just to get early feedback. For more information about versioning and the timeline, see Next Steps.

fields_to_return

FieldMask

Specifies which PlayableLocation fields are returned. Currently available fields are:

  • addresses
  • biome_type
  • center_point
  • display_names
  • name
  • place_id
  • snapped_point
  • types

By default, only name (which is used for logging impressions) and center_point are returned. All other fields are omitted unless you specify them here.

Note: The more fields you include, the more expensive in terms of data and associated latency your query will be.

DisplayName

Encapsulates the name of a playable location.

Fields
language_code

string

The language code, in BCP-47 format. It indicates the language of the free-form name provided in text.

For example, "en", "en-US", and "ja-Latn".

For more information, see Unicode Locale Identifier.

flags[]

LanguageFlag

A collection of flags that indicate additional details about the language of the playable location name, such as whether it's in a language local to the region.

text

string

The display name.

Dwellability

Specifies a ranking modifier that is based on how likely people tend to stay at a venue.

Fields
dwellability

DwellabilityModifier

Specifies a dwellability ranking modifier as one of the DwellabilityModifier enumeration values.

When you don't specify a dwellability value, then this modifier won't be used to rank playable locations.

DwellabilityModifier

A set of values that specify your preferred degree of dwellability. That is, the length of time that people tend to stay when they visit a venue.

Enums
MODIFIER_UNSPECIFIED Not specified. Do not use.
LONG

People tend to stay for a relatively long period at the venue.

Places that have higher dwellability are ranked higer. For example, a park has has a higher dwellability than a gas station.

Filter

Specifies the filters to use when searching for playable locations.

Fields
max_location_count

int32

Specifies the maximum number of playable locations to return. This value must not be greater than 1,000. The default value is 100.

Only the top-ranking playable locations are returned.

spacing

SpacingOptions

A set of options that control the spacing between playable locations.

included_types[]

string

Restricts the set of playable locations to just the types that you want.

excluded_types[]

string

Excludes the types of playable locations that you don't want.

This field has a higher precedence than included_types.

content_rating

ContentRating

Provides the option of including playable locations associated with age-restricted venues like bars, casinos, and nightclubs.

The default value is EVERYONE, which means the playable locations are suitable for all ages.

access_types[]

AccessType

A value that specifies the type of access associated with the venue, specified as one of the AccessType enumeration values.

This field allows you to filter playable locations within areas that are FREE (such as public parks) or PAID (such as amusement parks). The default value is FREE.

biome_types[]

BiomeType

Restricts the set of playable locations to just the biome types that you want.

FormattedAddress

Encapsulates the address of a playable location, in a particular format.

Fields
format

FormatType

The format of the address, specified as one of the FormatType enumeration values.

lines[]

string

The address text, on multiple lines.

FormatType

A set of values that specifies the format of the address.

Enums
FORMAT_TYPE_UNSPECIFIED Format type not specified. Do not use.
LOCALITY The locality of the address. For example, Mountain View.
FULL_ADDRESS The full address, displayed on a single line. For example, 1600 Amphitheatre Pkwy, Mountain View, California 94043, USA.

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.

LanguageFlag

Annotates language-specific data with additional information.

Enums
LANGUAGE_FLAG_UNSPECIFIED Unspecified language flag. Do not use.
IN_LOCAL_LANGUAGE The data is in a language local to the country it pertains to.

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.

PlayableLocation

A geographical point suitable for placing game objects in location-based games.

Fields
name

string

Required. The name of this playable location, also used on PlayerReports and Impressions.

types[]

string

A collection of Playable Location Types for this playable location. The first type in the collection is the primary type.

Type information might not be available for all playable locations.

center_point

LatLng

Required. The latitude and longitude associated with the center of the playable location.

By default, the set of playable locations returned from SearchPlayableLocations use center-point coordinates.

snapped_point

LatLng

The playable location's coordinates, snapped to the sidewalk of the nearest road, if a nearby road exists.

display_names[]

DisplayName

The playable location's display name, in each language that the name is supported in.

Local languages for the playable location are listed first, and then any additional languages are listed afterwards, in no particular order.

addresses[]

Address

The playable location's address, in each language that the address is supported in.

Local languages for the playable location are listed first, and then any additional languages are listed afterwards, in no particular order.

biome_type[]

BiomeType

The playable location's biome types.

Union field location_id. Required. Each location has one of the following identifiers: location_id can be only one of the following:
place_id

string

A place ID

plus_code

string

A plus code

PlayableLocationList

A list of PlayableLocation objects that satisfies a single Criterion.

Fields
locations[]

PlayableLocation

A list of playable locations for this game object type.

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.

PointExclusion

Specifies how to exclude particular playable locations from the set of returned playable locations.

Fields
point

fixed64

The ID of a leaf S2 cell to exclude from the search result. This allows you to avoid overlapping your own content with playable locations.

min_spacing_meters

double

The minimum spacing around the excluded S2 cell.

No playable locations will be placed within this radius.

Ranking

Defines weighting factors used for ranking the returned playable locations.

Fields
types_prominence_modifier

map<string, int32>

Allows you to adjust the weighting of prominence levels for particular types of playable locations.

For example, {park: 2, cinema: 3, banks: -1}. Here, the prominence of parks is boosted by 2, that of cinemas is boosted by 3, and that of banks is reduced by 1. The value can range from -10 to +10, inclusive.

Playable locations that satisfy multiple matching types have their prominence boosted by the largest value specified.

The prominence level is influenced by a place's ranking in Google's index, and by global popularity, and by other factors.

Prominence tiers range from 1 to 10, where:

  • 1 is the lowest prominence tier.
  • 2 and above are the top 50% of playable locations.
  • 3 and above are the top 25% of playable locations.
  • 4 and above are the top 10% of playable locations.
  • 5 and above are the top 5% of playable locations.
  • 6 and above are the top 1% of playable locations.
  • 7 and above are the top 0.5% of playable locations.
  • 8 and above are the top 0.1% of playable locations.
  • 9 and above are the top 0.05% of playable locations.
  • 10 consists of the top 0.01% of playable locations.
busyness

Busyness

Specifies how busy the playable locations are.

capacity

Capacity

Specifies how large venue capacities are.

dwellability

Dwellability

Specifies how long the average length of stay is for venues.

artistically_interesting

ArtisticallyInteresting

Specifies how artistically interesting venues are.

SearchPlayableLocationsRequest

Life of a query:

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

  • 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 100 criterion may be specified).

{@link SearchPlayableLocationResponseItem} 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 blacklisted.

The response specifies how long you can expect the playable locations to last. Once they expire, you should query the search 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 100) criteria for filtering and ranking the returned playable locations.

SearchPlayableLocationsResponse

Response for the SearchPlayableLocations 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 SearchPlayableLocations request to get a fresh set of playable locations (because for example, they might have been blacklisted, a park might have closed for the day, a business might have closed permanently).

SpacingOptions

A set of options that specifies the separation between playable locations.

Fields
min_spacing_meters

double

Required. The minimum spacing between any two playable locations, measured in meters. The minimum value is 10. The maximum value is 1000.

Set this field to remove tight clusters of playable locations.

Note:

The spacing is a prominence-based greedy algorithm: it optimizes for selecting the most prominent locations first, not to maximize the number of locations selected. Suppose the following scenario:

  • Prominence: A: 9, B: 10, C: 8.
  • Distance: A--20m--B--20m--C

If spacing=25, it will pick the most prominent location [B], not [A, C].

Note:

Spacing works within the game object type itself, as well as the previous ones. Suppose three game object types, each with the following spacing:

  • X: 100m, Y: undefined, Z: 50m.
  1. Add locations for X, within 100m of each other.
  2. Add locations for Y, without any spacing.
  3. Finally, add locations for Z within 50m of each other as well X and Y.

The distance diagram between those locations end up as:

  • From->To.
  • X->X: 100m
  • Y->X, Y->Y: unspecified.
  • Z->X, Z->Y, Z->Z: 50m.
point_type

PointType

Required. Specifies whether the minimum spacing constraint applies to the center-point or to the snapped point of playable locations. The default value is CENTER_POINT.

If a snapped point is not available for a playable location, its center-point is used instead.

PointType

Specifies whether the playable location's geographic coordinates (latitude and longitude) correspond to its center-point, or to its location snapped to the sidewalk of the nearest road.

Enums
POINT_TYPE_UNSPECIFIED Unspecified point type. Do not use this value.
CENTER_POINT The geographic coordinates correspond to the center of the location.
SNAPPED_POINT The geographic coordinates correspond to the location snapped to the sidewalk of the nearest road (when a nearby road exists).