This section explains how to get playable locations, and it also contains examples that demonstrate how to call the APIs.
Getting playable locations
You retrieve sets of playable locations on-demand, as your players progress through your game. You don't retrieve and then cache a large dataset for use over a long period.
You get a set of playable locations by calling the
samplePlayableLocations
method. In your call, you specify the area to search within, and your also
specify filter criteria. The samplePlayableLocations
method returns a set of
PlayableLocation
objects, which contains both curated playable locations and generated playable
locations.
The HTTP request
The following code demonstrates how to call the samplePlayableLocations
method
by making an HTTP POST request, passing parameters in the request body.
POST https://playablelocations.googleapis.com/v3:samplePlayableLocations?key=YOUR_API_KEY
The request body
When you call the samplePlayableLocations
method, you pass the call parameters
using a JSON object within the HTTP request body.
{
"areaFilter": {
"s2CellId": string,
},
"criteria": [
{
"gameObjectType": number,
"filter": {
"maxLocationCount": number,
"spacing": {
"minSpacingMeters": number,
"pointType": enum(PointType)
},
"includedTypes": [
string
],
},
"fieldsToReturn": string
}
]
}
The request object model
The relationships between the JSON sub-objects is depicted in the following illustration.
Example 1: request body
The following code example demonstrates
filters
and
fields_to_return
.
{
"area_filter":{
"s2_cell_id":7715420662885515264
},
"criteria":[
{
"gameObjectType":1,
"filter":{
"maxLocationCount":4,
"includedTypes":[
"food_and_drink"
]
},
"fields_to_return": {"paths": ["name"]}
},
{
"gameObjectType":2,
"filter":{
"maxLocationCount":4
},
"fields_to_return": {"paths": ["types", "snapped_point"]}}
]
}
Example 2: request body
The following code example demonstrates
maxLocationCount
for various object types.
{
"area_filter":{
"s2_cell_id":7715420662885515264
},
"criteria":[
{
"gameObjectType":1,
"filter":{
"maxLocationCount":4,
"spacing":{
"minSpacingMeters":500
}
}
},
{
"gameObjectType":2,
"filter":{
"maxLocationCount":4,
"spacing":{
"minSpacingMeters":400
}
}
},
{
"gameObjectType":3,
"filter":{
"maxLocationCount":50,
"spacing":{
"minSpacingMeters":200
}
}
}
]
}