Using the Playable Locations API

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.

Request parameters vector graphic

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
            }
         }
      }
   ]
}