NOTICE: Google Maps Platform gaming services is deprecated as of October 18, 2021. Current users will have continued access until December 31, 2022. During this time, we will continue to provide support and fixes to major bugs and outages. See the Gaming Services Transition Guide for resources to help you plan the next steps for your projects.

Method: samplePlayableLocations

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

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

HTTP request

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

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 5) criteria for filtering the returned playable locations.

Response body

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

Response for the v3.samplePlayableLocations method.

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

map (key: integer, 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 v3.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).

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
}
Fields
s2CellId

string (fixed64 format)

Required. The S2 cell ID of the area you want. This must be between cell level 11 and 14 (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:

Criterion

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

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

integer

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.

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

string (FieldMask format)

Specifies which PlayableLocation fields are returned.

name (which is used for logging impressions), centerPoint and placeId (or plusCode) are always returned.

The following fields are omitted unless you specify them here:

  • snappedPoint
  • types

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": integer,
  "spacing": {
    object (SpacingOptions)
  },
  "includedTypes": [
    string
  ]
}
Fields
maxLocationCount

integer

Specifies the maximum number of playable locations to return. This value must not be greater than 1000. 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. By default the minimum distance between locations is 200m.
includedTypes[]

string

Restricts the set of playable locations to just the 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 minimum value is 30. The maximum value is 1000.

Inputs will be rounded up to the next 10 meter interval.

The default value is 200m.

Set this field to remove tight clusters of playable locations.

Note:

The spacing is a greedy algorithm. It optimizes for selecting the highest ranking locations first, not to maximize the number of locations selected. Consider the following scenario:

  • Rank: A: 2, B: 1, C: 3.
  • Distance: A--200m--B--200m--C

If spacing=250, it will pick the highest ranked 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: 400m, Y: undefined, Z: 200m.
  1. Add locations for X, within 400m of each other.
  2. Add locations for Y, without any spacing.
  3. Finally, add locations for Z within 200m of each other as well X and Y.

The distance diagram between those locations end up as:

  • From->To.
  • X->X: 400m
  • Y->X, Y->Y: unspecified.
  • Z->X, Z->Y, Z->Z: 200m.
pointType

enum (PointType)

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.

Set this to the point type used in your game.

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