Metadata-Version: 2.1
Name: geoguessr
Version: 0.0.1
Summary: 3rd party API for accessing Geoguessr challenge scores
Home-page: https://github.com/jaceiverson/geoguessr
Author: Jace Iverson
License: MIT
Project-URL: Bug Tracker, https://github.com/jaceiverson/geoguessr/issues
Platform: unix
Platform: linux
Platform: osx
Platform: cygwin
Platform: win32
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: testing
License-File: LICENSE

# Geoguesser Challenge Result API
3rd party API for accessing Geoguessr challenge scores. Uses the API found within Geoguessr to extract scores and store them in pandas DataFrames for ease of use

## Example
```py
from gg import Geoguesser
from util import clean

# initialize our instance of the class
geo = Geoguessr()

# make the html request to API
challenge_id = "abc123"
raw_data = geo.get_challenge_scores(chal)
scores = clean(raw_data)
```
### Sample output
| playerName   |   totalScore |   R1 |   R2 |   R3 |   R4 |   R5 |
|:-------------|-------------:|-----:|-----:|-----:|-----:|-----:|
| John     |        17120 | 4566 | 2940 | 4782 | 3589 | 1243 |
| Jane   |        11740 |   86 | 2632 | 2808 | 3896 | 2318 |
| Sue          |        10148 | 1396 | 3278 | 3422 |  112 | 1940 |
| Bob |         9954 |   51 | 2718 | 4997 |  443 | 1745 |
| Mary       |         8796 |   95 |   23 | 3186 | 3747 | 1745 |

## Requirements / Inputs
In order to use this API you will need to have participated in the challenge and have your ncfa cookie value stored as the environment variable: 
```
GEOGUESSR_COOKIE
``` 
By default this library uses <a href=https://pypi.org/project/python-dotenv/>python-dotenv</a> and its corresponding `.env` file to store environment variables.

This value can be found in the dev tools section of your browser. Look for the _ncfa value and copy it. You will store your variable like the following, replacing with your custom cookie value:
```
GEOGUESSR_COOKIE=_ncfa={MY COOKIE VALUE}
```
This is slightly confusing with the double equal sign, but that is how it should be formated so the request can properly go through. To reduce errors this value should be URL encoded (but don't worry that is the default on Chrome dev tools if you copied it over from there).

## Class Methods
```py
.get_challenge_scores(
    self, 
    challenge_id: str = None
    ) -> list:
```
Returns the raw response for the given challenge_id. Challenge_id can be found in the URl of the challenge. This is the code that is found after either `/results/` or `/challenge/` in the URL. Because this returns a raw response, there are utility functions to help clean and parse the data into other forms

## Utility Functions (from util import *)
```py
.clean(
    raw_data: list, 
    column_list: list = ["totalScore"],
    include_round_scores: bool = True
    ) -> pd.DataFrame
```
The main parsing function to clean challenge scores and put them into a DataFrame.

```raw_data```: is your response from `.get_challenge_scores()`

```column_list```: is which columns you'd like to include, by default this is only the totalScore, but a list of all columns you can chose from is included below.

```include_round_scores```: will determine if you would like to see each round score included in your output, by default this is True and will show each rounds' score.

### Potential Columns
|   # | Column                                       | Dtype   |
|----:|:---------------------------------------------|:--------|
|   0 | gameToken                                    | object  |
|   1 | userId                                       | object  |
|   2 | totalScore                                   | int64   |
|   3 | isLeader                                     | bool    |
|   4 | pinUrl                                       | object  |
|   5 | game.token                                   | object  |
|   6 | game.type                                    | object  |
|   7 | game.mode                                    | object  |
|   8 | game.state                                   | object  |
|   9 | game.roundCount                              | int64   |
|  10 | game.timeLimit                               | int64   |
|  11 | game.forbidMoving                            | bool    |
|  12 | game.forbidZooming                           | bool    |
|  13 | game.forbidRotating                          | bool    |
|  14 | game.streakType                              | object  |
|  15 | game.map                                     | object  |
|  16 | game.mapName                                 | object  |
|  17 | game.panoramaProvider                        | int64   |
|  18 | game.bounds.min.lat                          | float64 |
|  19 | game.bounds.min.lng                          | float64 |
|  20 | game.bounds.max.lat                          | float64 |
|  21 | game.bounds.max.lng                          | float64 |
|  22 | game.round                                   | int64   |
|  23 | game.rounds                                  | object  |
|  24 | game.player.totalScore.amount                | object  |
|  25 | game.player.totalScore.unit                  | object  |
|  26 | game.player.totalScore.percentage            | float64 |
|  27 | game.player.totalDistance.meters.amount      | object  |
|  28 | game.player.totalDistance.meters.unit        | object  |
|  29 | game.player.totalDistance.miles.amount       | object  |
|  30 | game.player.totalDistance.miles.unit         | object  |
|  31 | game.player.totalDistanceInMeters            | float64 |
|  32 | game.player.totalTime                        | int64   |
|  33 | game.player.totalStreak                      | int64   |
|  34 | game.player.guesses                          | object  |
|  35 | game.player.isLeader                         | bool    |
|  36 | game.player.currentPosition                  | int64   |
|  37 | game.player.pin.url                          | object  |
|  38 | game.player.pin.anchor                       | object  |
|  39 | game.player.pin.isDefault                    | bool    |
|  40 | game.player.newBadges                        | object  |
|  41 | game.player.newObjectives                    | object  |
|  42 | game.player.explorer                         | object  |
|  43 | game.player.id                               | object  |
|  44 | game.player.nick                             | object  |
|  45 | game.player.isVerified                       | bool    |
|  46 | game.progressChange.xpProgressions           | object  |
|  47 | game.progressChange.awardedXp.totalAwardedXp | int64   |
|  48 | game.progressChange.awardedXp.xpAwards       | object  |
|  49 | game.progressChange.prevRank                 | object  |
|  50 | game.progressChange.newRank                  | object  |
|  51 | game.progressChange.medal                    | int64   |
|  52 | game.progressChange.seasonProgress           | object  |
|  53 | game.progressChange.competitiveProgress      | object  |
