# Google Play Game Services API . scores

## Instance Methods

Get high scores and optionally, ranks in leaderboards for the currently authenticated player. For a specific time span, leaderboardId can be set to ALL to retrieve data for all leaderboards in a given time span.

Retrieves the next page of results.

Lists the scores in a leaderboard, starting from the top.

Lists the scores in a leaderboard around (and including) a player's score.

Retrieves the next page of results.

Retrieves the next page of results.

Submits a score to the specified leaderboard.

Submits multiple scores to leaderboards.

### Method Details

`get(playerId, leaderboardId, timeSpan, includeRankType=None, language=None, maxResults=None, pageToken=None)`

    Get high scores and optionally, ranks in leaderboards for the currently authenticated player. For a specific time span, leaderboardId can be set to ALL to retrieve data for all leaderboards in a given time span.

    Args:
      playerId: string, A player ID. A value of me may be used in place of the authenticated player's ID. (required)
      leaderboardId: string, The ID of the leaderboard. (required)
      timeSpan: string, The time span for the scores and ranks you're requesting. (required)
        Allowed values
          ALL - Get the high scores for all time spans. If this is used, maxResults values will be ignored.
          ALL_TIME - Get the all time high score.
          DAILY - List the top scores for the current day.
          WEEKLY - List the top scores for the current week.
      includeRankType: string, The types of ranks to return. If the parameter is omitted, no ranks will be returned.
        Allowed values
          ALL - Retrieve public and social ranks.
          PUBLIC - Retrieve public ranks, if the player is sharing their gameplay activity publicly.
          SOCIAL - Retrieve the social rank.
      language: string, The preferred language to use for strings returned by this method.
      maxResults: integer, The maximum number of leaderboard scores to return in the response. For any response, the actual number of leaderboard scores returned may be less than the specified maxResults.
      pageToken: string, The token returned by the previous request.

    Returns:
      An object of the form:

        { # This is a JSON template for a list of player leaderboard scores.
        "nextPageToken": "A String", # The pagination token for the next page of results.
        "items": [ # The leaderboard scores.
          { # This is a JSON template for a player leaderboard score object.
            "writeTimestamp": "A String", # The timestamp at which this score was recorded, in milliseconds since the epoch in UTC.
            "kind": "games#playerLeaderboardScore", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerLeaderboardScore.
            "publicRank": { # This is a JSON template for a score rank in a leaderboard. # The public rank of the score in this leaderboard. This object will not be present if the user is not sharing their scores publicly.
              "numScores": "A String", # The number of scores in the leaderboard.
              "kind": "games#leaderboardScoreRank", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardScoreRank.
              "formattedRank": "A String", # The rank in the leaderboard as a string.
              "rank": "A String", # The rank in the leaderboard.
              "formattedNumScores": "A String", # The number of scores in the leaderboard as a string.
            },
            "timeSpan": "A String", # The time span of this score.
                # Possible values are:
                # - "ALL_TIME" - The score is an all-time score.
                # - "WEEKLY" - The score is a weekly score.
                # - "DAILY" - The score is a daily score.
            "scoreString": "A String", # The formatted value of this score.
            "leaderboard_id": "A String", # The ID of the leaderboard this score is in.
            "scoreValue": "A String", # The numerical value of this score.
            "socialRank": { # This is a JSON template for a score rank in a leaderboard. # The social rank of the score in this leaderboard.
              "numScores": "A String", # The number of scores in the leaderboard.
              "kind": "games#leaderboardScoreRank", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardScoreRank.
              "formattedRank": "A String", # The rank in the leaderboard as a string.
              "rank": "A String", # The rank in the leaderboard.
              "formattedNumScores": "A String", # The number of scores in the leaderboard as a string.
            },
          },
        ],
        "kind": "games#playerLeaderboardScoreListResponse", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerLeaderboardScoreListResponse.
      }

`get_next(previous_request, previous_response)`

    Retrieves the next page of results.

    Args:
      previous_request: The request for the previous page. (required)
      previous_response: The response from the request for the previous page. (required)

    Returns:
      A request object that you can call 'execute()' on to request the next
      page. Returns None if there are no more items in the collection.

`list(leaderboardId, collection, timeSpan, language=None, maxResults=None, pageToken=None)`

    Lists the scores in a leaderboard, starting from the top.

    Args:
      leaderboardId: string, The ID of the leaderboard. (required)
      collection: string, The collection of scores you're requesting. (required)
        Allowed values
          PUBLIC - List all scores in the public leaderboard.
          SOCIAL - List only social scores.
      timeSpan: string, The time span for the scores and ranks you're requesting. (required)
        Allowed values
          ALL_TIME - List the all-time top scores.
          DAILY - List the top scores for the current day.
          WEEKLY - List the top scores for the current week.
      language: string, The preferred language to use for strings returned by this method.
      maxResults: integer, The maximum number of leaderboard scores to return in the response. For any response, the actual number of leaderboard scores returned may be less than the specified maxResults.
      pageToken: string, The token returned by the previous request.

    Returns:
      An object of the form:

        { # This is a JSON template for a ListScores response.
        "nextPageToken": "A String", # The pagination token for the next page of results.
        "kind": "games#leaderboardScores", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardScores.
        "numScores": "A String", # The total number of scores in the leaderboard.
        "items": [ # The scores in the leaderboard.
          { # This is a JSON template for the Leaderboard Entry resource.
            "kind": "games#leaderboardEntry", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardEntry.
            "scoreValue": "A String", # The numerical value of this score.
            "timeSpan": "A String", # The time span of this high score.
                # Possible values are:
                # - "ALL_TIME" - The score is an all-time high score.
                # - "WEEKLY" - The score is a weekly high score.
                # - "DAILY" - The score is a daily high score.
            "formattedScore": "A String", # The localized string for the numerical value of this score.
            "player": { # This is a JSON template for a Player resource. # The player who holds this score.
              "playerId": "A String", # The ID of the player.
              "kind": "games#player", # Uniquely identifies the type of this resource. Value is always the fixed string games#player.
              "avatarImageUrl": "A String", # The base URL for the image that represents the player.
              "displayName": "A String", # The name to display for the player.
            },
            "formattedScoreRank": "A String", # The localized string for the rank of this score for this leaderboard.
            "scoreRank": "A String", # The rank of this score for this leaderboard.
            "writeTimestampMillis": "A String", # The timestamp at which this score was recorded, in milliseconds since the epoch in UTC.
          },
        ],
        "playerScore": { # This is a JSON template for the Leaderboard Entry resource. # The score of the requesting player on the leaderboard. The player's score may appear both here and in the list of scores above. If you are viewing a public leaderboard and the player is not sharing their gameplay information publicly, the scoreRank and formattedScoreRank values will not be present.
          "kind": "games#leaderboardEntry", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardEntry.
          "scoreValue": "A String", # The numerical value of this score.
          "timeSpan": "A String", # The time span of this high score.
              # Possible values are:
              # - "ALL_TIME" - The score is an all-time high score.
              # - "WEEKLY" - The score is a weekly high score.
              # - "DAILY" - The score is a daily high score.
          "formattedScore": "A String", # The localized string for the numerical value of this score.
          "player": { # This is a JSON template for a Player resource. # The player who holds this score.
            "playerId": "A String", # The ID of the player.
            "kind": "games#player", # Uniquely identifies the type of this resource. Value is always the fixed string games#player.
            "avatarImageUrl": "A String", # The base URL for the image that represents the player.
            "displayName": "A String", # The name to display for the player.
          },
          "formattedScoreRank": "A String", # The localized string for the rank of this score for this leaderboard.
          "scoreRank": "A String", # The rank of this score for this leaderboard.
          "writeTimestampMillis": "A String", # The timestamp at which this score was recorded, in milliseconds since the epoch in UTC.
        },
        "prevPageToken": "A String", # The pagination token for the previous page of results.
      }

`listWindow(leaderboardId, collection, timeSpan, language=None, returnTopIfAbsent=None, resultsAbove=None, maxResults=None, pageToken=None)`

    Lists the scores in a leaderboard around (and including) a player's score.

    Args:
      leaderboardId: string, The ID of the leaderboard. (required)
      collection: string, The collection of scores you're requesting. (required)
        Allowed values
          PUBLIC - List all scores in the public leaderboard.
          SOCIAL - List only social scores.
      timeSpan: string, The time span for the scores and ranks you're requesting. (required)
        Allowed values
          ALL_TIME - List the all-time top scores.
          DAILY - List the top scores for the current day.
          WEEKLY - List the top scores for the current week.
      language: string, The preferred language to use for strings returned by this method.
      returnTopIfAbsent: boolean, True if the top scores should be returned when the player is not in the leaderboard. Defaults to true.
      resultsAbove: integer, The preferred number of scores to return above the player's score. More scores may be returned if the player is at the bottom of the leaderboard; fewer may be returned if the player is at the top. Must be less than or equal to maxResults.
      maxResults: integer, The maximum number of leaderboard scores to return in the response. For any response, the actual number of leaderboard scores returned may be less than the specified maxResults.
      pageToken: string, The token returned by the previous request.

    Returns:
      An object of the form:

        { # This is a JSON template for a ListScores response.
        "nextPageToken": "A String", # The pagination token for the next page of results.
        "kind": "games#leaderboardScores", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardScores.
        "numScores": "A String", # The total number of scores in the leaderboard.
        "items": [ # The scores in the leaderboard.
          { # This is a JSON template for the Leaderboard Entry resource.
            "kind": "games#leaderboardEntry", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardEntry.
            "scoreValue": "A String", # The numerical value of this score.
            "timeSpan": "A String", # The time span of this high score.
                # Possible values are:
                # - "ALL_TIME" - The score is an all-time high score.
                # - "WEEKLY" - The score is a weekly high score.
                # - "DAILY" - The score is a daily high score.
            "formattedScore": "A String", # The localized string for the numerical value of this score.
            "player": { # This is a JSON template for a Player resource. # The player who holds this score.
              "playerId": "A String", # The ID of the player.
              "kind": "games#player", # Uniquely identifies the type of this resource. Value is always the fixed string games#player.
              "avatarImageUrl": "A String", # The base URL for the image that represents the player.
              "displayName": "A String", # The name to display for the player.
            },
            "formattedScoreRank": "A String", # The localized string for the rank of this score for this leaderboard.
            "scoreRank": "A String", # The rank of this score for this leaderboard.
            "writeTimestampMillis": "A String", # The timestamp at which this score was recorded, in milliseconds since the epoch in UTC.
          },
        ],
        "playerScore": { # This is a JSON template for the Leaderboard Entry resource. # The score of the requesting player on the leaderboard. The player's score may appear both here and in the list of scores above. If you are viewing a public leaderboard and the player is not sharing their gameplay information publicly, the scoreRank and formattedScoreRank values will not be present.
          "kind": "games#leaderboardEntry", # Uniquely identifies the type of this resource. Value is always the fixed string games#leaderboardEntry.
          "scoreValue": "A String", # The numerical value of this score.
          "timeSpan": "A String", # The time span of this high score.
              # Possible values are:
              # - "ALL_TIME" - The score is an all-time high score.
              # - "WEEKLY" - The score is a weekly high score.
              # - "DAILY" - The score is a daily high score.
          "formattedScore": "A String", # The localized string for the numerical value of this score.
          "player": { # This is a JSON template for a Player resource. # The player who holds this score.
            "playerId": "A String", # The ID of the player.
            "kind": "games#player", # Uniquely identifies the type of this resource. Value is always the fixed string games#player.
            "avatarImageUrl": "A String", # The base URL for the image that represents the player.
            "displayName": "A String", # The name to display for the player.
          },
          "formattedScoreRank": "A String", # The localized string for the rank of this score for this leaderboard.
          "scoreRank": "A String", # The rank of this score for this leaderboard.
          "writeTimestampMillis": "A String", # The timestamp at which this score was recorded, in milliseconds since the epoch in UTC.
        },
        "prevPageToken": "A String", # The pagination token for the previous page of results.
      }

`listWindow_next(previous_request, previous_response)`

    Retrieves the next page of results.

    Args:
      previous_request: The request for the previous page. (required)
      previous_response: The response from the request for the previous page. (required)

    Returns:
      A request object that you can call 'execute()' on to request the next
      page. Returns None if there are no more items in the collection.

`list_next(previous_request, previous_response)`

    Retrieves the next page of results.

    Args:
      previous_request: The request for the previous page. (required)
      previous_response: The response from the request for the previous page. (required)

    Returns:
      A request object that you can call 'execute()' on to request the next
      page. Returns None if there are no more items in the collection.

`submit(leaderboardId, score, language=None)`

    Submits a score to the specified leaderboard.

    Args:
      leaderboardId: string, The ID of the leaderboard. (required)
      score: string, The score you're submitting. The submitted score is ignored if it is worse than a previously submitted score, where worse depends on the leaderboard sort order. The meaning of the score value depends on the leaderboard format type. For fixed-point, the score represents the raw value. For time, the score represents elapsed time in milliseconds. For currency, the score represents a value in micro units. (required)
      language: string, The preferred language to use for strings returned by this method.

    Returns:
      An object of the form:

        { # This is a JSON template for a list of leaderboard entry resources.
        "kind": "games#playerScoreResponse", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScoreResponse.
        "leaderboardId": "A String", # The leaderboard ID that this score was submitted to.
        "formattedScore": "A String", # The formatted value of the submitted score.
        "beatenScoreTimeSpans": [ # The time spans where the submitted score is better than the existing score for that time span.
            # Possible values are:
            # - "ALL_TIME" - The score is an all-time score.
            # - "WEEKLY" - The score is a weekly score.
            # - "DAILY" - The score is a daily score.
          "A String",
        ],
        "unbeatenScores": [ # The scores in time spans that have not been beaten. As an example, the submitted score may be better than the player's DAILY score, but not better than the player's scores for the WEEKLY or ALL_TIME time spans.
          { # This is a JSON template for a player score.
            "kind": "games#playerScore", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScore.
            "score": "A String", # The numerical value for this player score.
            "formattedScore": "A String", # The formatted score for this player score.
            "timeSpan": "A String", # The time span for this player score.
                # Possible values are:
                # - "ALL_TIME" - The score is an all-time score.
                # - "WEEKLY" - The score is a weekly score.
                # - "DAILY" - The score is a daily score.
          },
        ],
      }

`submitMultiple(body, language=None)`

    Submits multiple scores to leaderboards.

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

    { # This is a JSON template for a list of score submission requests
        "kind": "games#playerScoreSubmissionList", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScoreSubmissionList.
        "scores": [ # The score submissions.
          { # This is a JSON template for a request to submit a score to leaderboards.
            "kind": "games#scoreSubmission", # Uniquely identifies the type of this resource. Value is always the fixed string games#scoreSubmission.
            "leaderboardId": "A String", # The leaderboard this score is being submitted to.
            "score": "A String", # The new score being submitted.
          },
        ],
      }

      language: string, The preferred language to use for strings returned by this method.

    Returns:
      An object of the form:

        { # This is a JSON template for a list of score submission statuses.
        "submittedScores": [ # The score submissions statuses.
          { # This is a JSON template for a list of leaderboard entry resources.
            "kind": "games#playerScoreResponse", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScoreResponse.
            "leaderboardId": "A String", # The leaderboard ID that this score was submitted to.
            "formattedScore": "A String", # The formatted value of the submitted score.
            "beatenScoreTimeSpans": [ # The time spans where the submitted score is better than the existing score for that time span.
                # Possible values are:
                # - "ALL_TIME" - The score is an all-time score.
                # - "WEEKLY" - The score is a weekly score.
                # - "DAILY" - The score is a daily score.
              "A String",
            ],
            "unbeatenScores": [ # The scores in time spans that have not been beaten. As an example, the submitted score may be better than the player's DAILY score, but not better than the player's scores for the WEEKLY or ALL_TIME time spans.
              { # This is a JSON template for a player score.
                "kind": "games#playerScore", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScore.
                "score": "A String", # The numerical value for this player score.
                "formattedScore": "A String", # The formatted score for this player score.
                "timeSpan": "A String", # The time span for this player score.
                    # Possible values are:
                    # - "ALL_TIME" - The score is an all-time score.
                    # - "WEEKLY" - The score is a weekly score.
                    # - "DAILY" - The score is a daily score.
              },
            ],
          },
        ],
        "kind": "games#playerScoreListResponse", # Uniquely identifies the type of this resource. Value is always the fixed string games#playerScoreListResponse.
      }