Method: searchPlayableLocations

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

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

HTTP request

POST https://playablelocations.googleapis.com/v3:searchPlayableLocations

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation
{
  "areaFilter": {
    object(AreaFilter)
  },
  "criteria": [
    {
      object(Criterion)
    }
  ]
}
Fields
areaFilter

object(AreaFilter)

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

criteria[]

object(Criterion)

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

Response body

If successful, the response body contains data with the following structure:

Response for the playableLocations.search method.

JSON representation
{
  "locationsPerGameObjectType": {
    string: {
      object(PlayableLocationList)
    },
    ...
  },
  "ttl": string
}
Fields
locationsPerGameObjectType

map (key: number, value: object(PlayableLocationList))

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

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ttl

string (Duration format)

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 playableLocations.search 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).

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

AreaFilter

Specifies the area to search for playable locations.

JSON representation
{
  "s2CellId": string,
  "pointExclusions": [
    {
      object(PointExclusion)
    }
  ]
}
Fields
s2CellId

string (fixed64 format)

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:

pointExclusions[]

object(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".

PointExclusion

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

JSON representation
{
  "point": string,
  "minSpacingMeters": number
}
Fields
point

string (fixed64 format)

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.

minSpacingMeters

number

The minimum spacing around the excluded S2 cell.

No playable locations will be placed within this radius.

Criterion

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

JSON representation
{
  "gameObjectType": number,
  "filter": {
    object(Filter)
  },
  "ranking": {
    object(Ranking)
  },
  "fieldsToReturn": string
}
Fields
gameObjectType

number

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 gameObjectType 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<gameObjectType, Response>.

filter

object(Filter)

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

ranking

object(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.

fieldsToReturn

string (FieldMask format)

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 centerPoint 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.

A comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

Filter

Specifies the filters to use when searching for playable locations.

JSON representation
{
  "maxLocationCount": number,
  "spacing": {
    object(SpacingOptions)
  },
  "includedTypes": [
    string
  ],
  "excludedTypes": [
    string
  ],
  "contentRating": enum(ContentRating),
  "accessTypes": [
    enum(AccessType)
  ],
  "biomeTypes": [
    enum (BiomeType)
  ]
}
Fields
maxLocationCount

number

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

object(SpacingOptions)

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

includedTypes[]

string

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

excludedTypes[]

string

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

This field has a higher precedence than includedTypes.

contentRating

enum(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.

accessTypes[]

enum(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.

biomeTypes[]

enum (BiomeType)

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

SpacingOptions

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

JSON representation
{
  "minSpacingMeters": number,
  "pointType": enum(PointType)
}
Fields
minSpacingMeters

number

Required. The minimum spacing between any two playable locations, measured in meters. 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.
pointType

enum(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).

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.

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.

PRIVATE

A private location with the risk of unwanted access. For example: residences, private roads, and corporate offices.

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

Ranking

Defines weighting factors used for ranking the returned playable locations.

JSON representation
{
  "typesProminenceModifier": {
    string: number,
    ...
  },
  "busyness": {
    object(Busyness)
  },
  "capacity": {
    object(Capacity)
  },
  "dwellability": {
    object(Dwellability)
  },
  "artisticallyInteresting": {
    object(ArtisticallyInteresting)
  }
}
Fields
typesProminenceModifier

map (key: string, value: number)

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.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

busyness

object(Busyness)

Specifies how busy the playable locations are.

capacity

object(Capacity)

Specifies how large venue capacities are.

dwellability

object(Dwellability)

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

artisticallyInteresting

object(ArtisticallyInteresting)

Specifies how artistically interesting venues are.

Busyness

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

JSON representation
{
  "busyness": enum(BusynessModifier)
}
Fields
busyness

enum(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.

JSON representation
{
  "capacity": enum(CapacityModifier)
}
Fields
capacity

enum(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.

Dwellability

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

JSON representation
{
  "dwellability": enum(DwellabilityModifier)
}
Fields
dwellability

enum(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.

ArtisticallyInteresting

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

JSON representation
{
  "artisticallyInteresting": enum(ArtisticallyInterestingModifier)
}
Fields
artisticallyInteresting

enum(ArtisticallyInterestingModifier)

When you don't specify an artisticallyInteresting 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.