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 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:

PlayableLocation properties

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

{
  "name": string,
  "placeId": string,
  "plus_code": string,
  "types": [
    string
  ],
  "centerPoint": {
    object(LatLng)
  },
  "snappedPoint": {
    object(LatLng)
  }
}
      

name

A string that uniquely identifies the playable location.

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 both entertainment and outdoor_recreation.

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

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). The samplePlayableLocations method supports spacing options in the range of 30m to 1000m, with the default being 200m.

Example with default spacing options (200m)

Example with a minimum spacing of 400 meters.

Ranking

When you issue a sample request for a set of playable locations by calling samplePlayableLocations, the returned playable locations are automatically ranked according to their prominence, which is determined by the place's popularity in Google's POI database.

Intended audience

The Playable Locations API serves playable locations that are appropriate for use by players of all ages.

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 4³⁰ 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 14 inclusive. These S2 Cells have the following average areas:

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

Further reading

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

• S2 cells and space-filling curves: Keys to building better digital map tools for cities.

• Sidewalk Labs Planetary View app.

• Google’s S2, geometry on the sphere, cells and Hilbert curve.