Playable Locations API . v3

Instance Methods

logImpressions(body=None, x__xgafv=None)

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

logPlayerReports(body=None, x__xgafv=None)

Logs bad playable location reports submitted by players.

samplePlayableLocations(body=None, x__xgafv=None)

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