# Playable Locations API . v3

## Instance Methods

Logs new events when playable locations are displayed, and when they are

Logs bad playable location reports submitted by players.

Returns a set of playable locations that lie within a specified area,

### Method Details

`logImpressions(body=None, x__xgafv=None)`

    Logs new events when playable locations are displayed, and when they are
    interacted with.

    Impressions are not partially saved; either all impressions are saved and
    this request succeeds, or no impressions are saved, and this request fails.

    Args:
      body: object, The request body.
        The object takes the form of:

    { # A request for logging impressions.
        "requestId": "A String", # Required. A string that uniquely identifies the log impressions request. This allows
            # you to detect duplicate requests. We recommend that you use UUIDs for this
            # value. The value must not exceed 50 characters.
            #
            # You should reuse the `request_id` only when retrying a request in case of
            # failure. In this case, the request must be identical to the one that
            # failed.
        "clientInfo": { # Client information. # Required. Information about the client device. For example, device model and
            # operating system.
          "languageCode": "A String", # Language code (in BCP-47 format) indicating the UI language of the client.
              # Examples are "en", "en-US" or "ja-Latn". For more information, see
              # http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
          "operatingSystemBuild": "A String", # Build number/version of the operating system. e.g., the contents of
              # android.os.Build.ID in Android, or the contents of sysctl "kern.osversion"
              # in iOS.
          "platform": "A String", # Platform where the application is running.
          "apiClient": "A String", # API client name and version. For example, the SDK calling the API. The
              # exact format is up to the client.
          "applicationId": "A String", # Application ID, such as the package name on Android and the bundle
              # identifier on iOS platforms.
          "applicationVersion": "A String", # Application version number, such as "1.2.3". The exact format is
              # application-dependent.
          "deviceModel": "A String", # Device model as reported by the device. The exact format is
              # platform-dependent.
          "operatingSystem": "A String", # Operating system name and version as reported by the OS. For example,
              # "Mac OS X 10.10.4". The exact format is platform-dependent.
        },
        "impressions": [ # Required. Impression event details. The maximum number of impression reports that you
            # can log at once is 50.
          { # Encapsulates impression event details.
            "impressionType": "A String", # Required. The type of impression event.
            "locationName": "A String", # Required. The name of the playable location.
            "gameObjectType": 42, # An arbitrary, developer-defined type identifier for each type of game
                # object used in your game.
                #
                # Since players interact with differ types of game objects in different ways,
                # this field allows you to segregate impression data by type for analysis.
                #
                # You should assign a unique `game_object_type` ID to represent a distinct
                # type of game object in your game.
                #
                # For example, 1=monster location, 2=powerup location.
          },
        ],
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # A response for the LogImpressions method.
          # This method returns no data upon success.
      }

`logPlayerReports(body=None, x__xgafv=None)`

    Logs bad playable location reports submitted by players.

    Reports are not partially saved; either all reports are saved and this
    request succeeds, or no reports are saved, and this request fails.

    Args:
      body: object, The request body.
        The object takes the form of:

    { # A request for logging your player's bad location reports.
        "playerReports": [ # Required. Player reports. The maximum number of player reports that you can log at
            # once is 50.
          { # A report submitted by a player about a playable location that is considered
              # inappropriate for use in the game.
            "reasons": [ # Required. One or more reasons why this playable location is considered bad.
              "A String",
            ],
            "locationName": "A String", # Required. The name of the playable location.
            "languageCode": "A String", # Language code (in BCP-47 format) indicating the language of the freeform
                # description provided in `reason_details`. Examples are "en", "en-US" or
                # "ja-Latn". For more information, see
                # http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
            "reasonDetails": "A String", # Required. A free-form description detailing why the playable location is
                # considered bad.
          },
        ],
        "requestId": "A String", # Required. A string that uniquely identifies the log player reports request. This
            # allows you to detect duplicate requests. We recommend that you use UUIDs
            # for this value. The value must not exceed 50 characters.
            #
            # You should reuse the `request_id` only when retrying a request in the case
            # of a failure. In that case, the request must be identical to the one that
            # failed.
        "clientInfo": { # Client information. # Required. Information about the client device (for example, device model and
            # operating system).
          "languageCode": "A String", # Language code (in BCP-47 format) indicating the UI language of the client.
              # Examples are "en", "en-US" or "ja-Latn". For more information, see
              # http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
          "operatingSystemBuild": "A String", # Build number/version of the operating system. e.g., the contents of
              # android.os.Build.ID in Android, or the contents of sysctl "kern.osversion"
              # in iOS.
          "platform": "A String", # Platform where the application is running.
          "apiClient": "A String", # API client name and version. For example, the SDK calling the API. The
              # exact format is up to the client.
          "applicationId": "A String", # Application ID, such as the package name on Android and the bundle
              # identifier on iOS platforms.
          "applicationVersion": "A String", # Application version number, such as "1.2.3". The exact format is
              # application-dependent.
          "deviceModel": "A String", # Device model as reported by the device. The exact format is
              # platform-dependent.
          "operatingSystem": "A String", # Operating system name and version as reported by the OS. For example,
              # "Mac OS X 10.10.4". The exact format is platform-dependent.
        },
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # A response for the LogPlayerReports
          # method.
          #
          # This method returns no data upon success.
      }

`samplePlayableLocations(body=None, x__xgafv=None)`

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

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

    Args:
      body: object, The request body.
        The object takes the form of:

    { #
          # Life of a query:
          #
          # - When a game starts in a new location, your game server issues a
          # SamplePlayableLocations
          # request. The request specifies the S2 cell, and contains one or more
          # "criteria" for filtering:
          #
          # - Criterion 0: i locations for long-lived bases, or level 0 monsters, or...
          # - Criterion 1: j locations for short-lived bases, or level 1 monsters, ...
          # - Criterion 2: k locations for random objects.
          # - etc (up to 5 criterion may be specified).
          #
          # `PlayableLocationList` will then contain mutually
          # exclusive lists of `PlayableLocation` objects that satisfy each of
          # the criteria. Think of it as a collection of real-world locations that you
          # can then associate with your game state.
          #
          # Note: These points are impermanent in nature. E.g, parks can close, and
          # places can be removed.
          #
          # The response specifies how long you can expect the playable locations to
          # last. Once they expire, you should query the `samplePlayableLocations` API
          # again to get a fresh view of the real world.
        "areaFilter": { # Specifies the area to search for playable locations. # Required. Specifies the area to search within for playable locations.
          "s2CellId": "A String", # 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:
              #
              #   * [C++](https://github.com/google/s2geometry)
              #   * [Java](https://github.com/google/s2-geometry-library-java)
              #   * [Go](https://github.com/golang/geo)
              #   * [Python](https://github.com/google/s2geometry/tree/master/src/python)
        },
        "criteria": [ # Required. Specifies one or more (up to 5) criteria for filtering the
            # returned playable locations.
          { # Encapsulates a filter criterion for searching for a set of playable
              # locations.
            "filter": { # Specifies the filters to use when searching for playable locations. # Specifies filtering options, and specifies what will be included in the
                # result set.
              "maxLocationCount": 42, # 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.
              "includedTypes": [ # Restricts the set of playable locations to just the
                  # [types](/maps/documentation/gaming/tt/types) that you want.
                "A String",
              ],
              "spacing": { # A set of options that specifies the separation between playable locations. # A set of options that control the spacing between playable locations. By
                  # default the minimum distance between locations is 200m.
                "minSpacingMeters": 3.14, # 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": "A String", # 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.
              },
            },
            "fieldsToReturn": "A String", # Specifies which `PlayableLocation` fields are returned.
                #
                # `name` (which is used for logging impressions), `center_point` and
                # `place_id` (or `plus_code`) are always returned.
                #
                # The following fields are omitted unless you specify them here:
                #
                #   * snapped_point
                #   * types
                #
                # Note: The more fields you include, the more expensive in terms of data and
                # associated latency your query will be.
            "gameObjectType": 42, # 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 `game_object_type` 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<game_object_type, Response>.
          },
        ],
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { #
          # Response for the
          # SamplePlayableLocations
          # method.
        "ttl": "A String", # 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
            # 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).
        "locationsPerGameObjectType": { # Each PlayableLocation object corresponds to a game_object_type specified
            # in the request.
          "a_key": { # A list of PlayableLocation objects that satisfies a single Criterion.
            "locations": [ # A list of playable locations for this game object type.
              { # A geographical point suitable for placing game objects in location-based
                  # games.
                "plusCode": "A String", # A [plus code] (http://openlocationcode.com)
                "centerPoint": { # An object representing a latitude/longitude pair. This is expressed as a pair # Required. The latitude and longitude associated with the center of the playable
                    # location.
                    #
                    # By default, the set of playable locations returned from
                    # SamplePlayableLocations use
                    # center-point coordinates.
                    # of doubles representing degrees latitude and degrees longitude. Unless
                    # specified otherwise, this must conform to the
                    # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84
                    # standard</a>. Values must be within normalized ranges.
                  "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0].
                  "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0].
                },
                "name": "A String", # Required. The name of this playable location.
                "placeId": "A String", # A [place ID] (https://developers.google.com/places/place-id)
                "snappedPoint": { # An object representing a latitude/longitude pair. This is expressed as a pair # The playable location's coordinates, snapped to the sidewalk of the
                    # nearest road, if a nearby road exists.
                    # of doubles representing degrees latitude and degrees longitude. Unless
                    # specified otherwise, this must conform to the
                    # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84
                    # standard</a>. Values must be within normalized ranges.
                  "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0].
                  "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0].
                },
                "types": [ # A collection of [Playable Location
                    # Types](/maps/documentation/gaming/tt/types) for this playable location. The
                    # first type in the collection is the primary type.
                    #
                    # Type information might not be available for all playable locations.
                  "A String",
                ],
              },
            ],
          },
        },
      }