Playable Locations API Key Concepts

The following sections contain explanations of the concepts that are key to understanding and using the Playable Locations API.

About playable locations

Generally speaking, a location is a geographic point on a map, but a playable location is a location deemed suitable for placing game objects on in real-world games (that is, as spawn points for things like prizes).

Types of playable locations

When you retrieve a set of playable locations, you can receive two types of them.

Curated
Curated playable locations are geographic points that are associated with objects that exist at specific locations. They represent the locations of Points of Interest (POI) drawn from Google's database. They're actually the same places that you can search for using Google Maps, and they include prominent landmarks such as the Statue of Liberty and the Eiffel Tower; but they also include places that are simply useful to consumers—like local restaurants, hotels, and shops.
Generated
If there aren't enough curated playable locations to satisfy your criteria, then the Playable Locations API generates extra playable locations. These generated playable locations are geographic points that aren't associated with existing objects. Instead, these geographic points are programmatically created in realtime, and they're randomly placed along sidewalks, within parks, on beaches, and within playgrounds, town squares, and other publicly accessible areas.

You use both types of playable locations for placing game object types like powerups, loot, battle grounds and supply depots.

The Playable Locations API provides collections of playable locations contained within the geographic area that you specify, that satisfy optional filter criteria that you provide. Google's goal is to provide at least a minimum density of playable locations, with consideration given to the following criteria:

CriteriaExample
Player safety Game prizes shouldn't appear in the middle of freeways or inside military bases.
Appropriateness for game play Players shouldn't disturb cemeteries or places of worship.

PlayableLocation properties

searchPlayableLocations returns a collection of PlayableLocation objects, which are JSON objects with the following properties.

JSON
{
  "name": string,
  "placeId": string,
  "plus_code": string,
  "types": [
    string
  ],
  "centerPoint": {
    object(LatLng)
  },
  "snappedPoint": {
    object(LatLng)
  },
  "displayNames": [
    {
      object(DisplayName)
    }
  ],
  "addresses": [
    {
      object(Address)
    }
  ]
}
    
name
A string that uniquely identifies the playable location. It is the PlaceID prefixed with "playableLocations/". For example, playableLocations/Chlj79ZW1ohQwokRWPhGmWQ2K4.
placeId
An alphanumeric string that uniquely identifies the location. This is a Place ID for curated playable locations (for example, e66ef376f790adf8a5af7fca9e6e422c03c9143f). You can use a curated playable location's PlaceId to attach game-specific metadata to the location. You can also use Place IDs with other Google APIs.

plus_code
A Plus Code that uniquely identifies the generated playable location. Plus codes are alphanumeric strings. For example, PXRV+XJ.
types
An array of Playable Location types (strings) that specify the type of playable location. The first type in the array is considered the primary type. For example, you could have a playable location that is a restaurant in a town_square.
centerPoint
The geographic coordinates corresponding to the location's center-point. The center-point is used to determine whether a location falls within the area of interest you specify in the searchPlayableLocations method.
snappedPoint
The geographic coordinates corresponding to the location snapped to the sidewalk of the nearest road (when a nearby road exists). You can use the snapped-point to place game objects when business owners don't want game players inside their premises. Snapped-point is not provided for locations with prominence levels of one and two.
displayNames
The display name associated with this curated playable location, in multiple languages if supported—as an array of DisplayName objects.
addresses
The address associated with this curated playable location, in multiple languages if supported—as an array of Address objects.

Spacing

You can remove tight clusters of curated playable locations by specifying SpacingOptions. To set spacing options, you specify the minimum spacing (in meters) between neighboring playable locations, and specify the point type (either center-point or snapped-point).

Example without spacing options

The following example demonstrates the problem of undefined spacing.

Without density options

Example with spacing options

The following example demonstrates a minimum spacing of 150 meters.

With density options

Intended audience

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.

We provide this option with the contentRating query parameter, which you pass when you call the searchPlayableLocations method.

Biomes

A biome is a community of plants and animals that share common environmental adaptation characteristics. Biomes form in response to a shared physical climate. Examples of biomes are forests, wetlands, and urban areas.

Each PlayableLocation has an associated biomeType field. When a playable location is situated within a biome, then this field is populated with one or more BiomeType values.

To receive biome information for playable locations, you must specify that you want it in Criteria.fields_to_return. For example:

"fields_to_return": {"paths": ["biome_type"]}

The associated response contains the biome information, as is demonstrated in the following code snippet:

...
  "locations": [
    {
      "name": "curatedPlayableLocations/ChIJGc4QODauEmsRPyDYYycA4Yg",
      "placeId": "ChIJGc4QODauEmsRPyDYYycA4Yg",
      "centerPoint": {
        "latitude": -33.86811999999999,
        "longitude": 151.19691129999998
      },
      "biomeType": [
        "GRASSLAND",
        "URBAN",
        "WATER"
      ]
    },
...

Playable Locations Explorer

The Playable Locations Explorer is a web app that allows you to construct and test search requests for the Playable Locations API. You can use it to experiment with filters to find the best collections of playable locations for your game.

S2 cells

You use S2 Cells to specify the area that you want to search within for retrieving playable locations. This section contains a brief overview of what they are.

Imagine a sphere bounded by a square box (a cube), and visualize projecting each of the box's six sides back onto the sphere. Now imagine that the sphere is the globe, with its surface divided into six equally-sized squares. These are actually squares with bent sides, and we refer to them as S2 Cells.

These six large cells are called base cells, or level 0 cells. Now you understand the basics of what S2 Cells are. Now consider dividing each of these base cells into four equal sections. What you get is 6 x 4 = 24 sub-cells (or level 1 cells). Note that each of the six base cells become parents to the sub-cells that they contain.

If you repeat this process, and further divide each sub-cell into four smaller cells, then you'll have defined the set of level 2 cells. Repeat this process twenty eight more times, and you'll end up covering the Earth with 6 X 430 cells, with each one measuring about ten centimeters per side. These are the level 30 cells—the finest level.

Every S2 Cell (which includes S2 Cells of all levels) has a unique identifier— the s2CellId . These are 64-bit integers, and in the Playable Locations API, you'll use them to specify the area that you want playable locations within. S2 Cells have a parent/child relationship, and they are arranged hierarchically. This aspect makes it easy to support spatial indexing, which enables very fast retrieval of playable locations from a database.

S2 cell average areas

The Playable Locations API supports S2 Cell levels between 11 and 16 inclusive. These S2 Cells have the following average areas:

S2 Cell LevelAverage Area (km²)
11 20
12 5
13 1
14 0.3
15 0.08
16 0.02

The S2 Geometry Library

The S2Geometry Library is a geographic information system that represents data on a three-dimensional sphere. The library includes the following features:

  • Support for spatial indexing.

    • This allows you to approximate arbitrary areas as collections of discrete S2 Cells.

    • Fast in-memory spatial indexing of collections of points, polylines, and polygons.

  • Robust constructive operations (such as intersection, union, and simplification) and boolean predicates (such as testing for containment).

  • Efficient query operations for finding nearby objects, measuring distances, and computing centroids.

  • A collection of mathematical predicates for testing relationships among geometric primitives.

  • Snap rounding.

S2 cell statistics

S2 Cell Statistics are useful for computing things like the length of time that it takes to download a data set at a particular QPS.

S2 geometry code repositories

Clone any of these repositories to get started working with S2 Cells.

Determining S2 cell coverage

When retrieving a set of playable locations, you might need to compute the set of S2 Cells that cover particular geographical areas. For help, you can use the Region Coverer web app from Sidewalk Labs, or the Coordinate Plotter web app from s2map.com.

How to determine S2 cell coverage programmatically

All S2 geometry libraries include a class called S2RegionCoverer that you can use to compute the list of S2 Cells that cover an arbitrary region. You can use the S2CellId class to get child S2 Cell IDs at the smallest granularity level supported by the Playable Locations API (level 16).

Further reading

Here are a few resources that provide more information on S2 Cells.

Send feedback about...

Google Maps Platform gaming solution
Google Maps Platform gaming solution