Metadata-Version: 2.1
Name: opengamedata-api-files
Version: 2.2.0b2
Summary: A small collection of classes for deserializing data from the OpenGameData File API.
Author: Ryan Wilkinson
Author-email: Luke Swanson <lwswanson2@wisc.edu>, David Gagnon <djgagnon@wisc.edu>
Project-URL: Homepage, https://github.com/opengamedata/opengamedata-api-files
Project-URL: Bug Tracker, https://github.com/opengamedata/opengamedata-api-files/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask==2.3.3
Requires-Dist: flask-cors==4.0.1
Requires-Dist: flask-restful==0.3.10
Requires-Dist: google-cloud-bigquery==3.36.0
Requires-Dist: opengamedata-common>=2.0.0b6
Requires-Dist: opengamedata-api-utils==2.0.*

# opengamedata-api-files

This is the OpenGameData dataset/file repository API.

Its primary use is for getting information about what data is available from the fileserver used by [opengamedata.fielddaylab.wisc.edu](opengamedata.fielddaylab.wisc.edu), but could be used for any repository of datasets using the OpenGameData pipeline.

## API endpoints

The latest release of the API supports the endpoints listed below.

Broadly speaking, the file API has a 3-level hierarchy for retrieving information about games and their datasets.

1. Games: The top-level entity is a game. Each game has an ID and is associated with one or more datasets.
2. Datasets: The term "dataset" refers to all data for a specific month of play from a specific game.
  For any given dataset, the actual data in that "set" may include game events, post-hoc "detector" events, session-level features, player-level features, or population-level features.
3. Files: A "file" contains actual data of one type from a dataset.

### Game-Level Endpoints

* `/games`

  Retrieve a list of all games for which at least one dataset exists.

  Example:

  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games
  ```

  ```json
  {
    "type": "GET",
    "val": {
      "game_ids": ["AQUALAB", "BACTERIA", "BALLOON", ...]
    },
    "msg": "SUCCESS: Retrieved list of games with available datasets"
    }
  ```

* `/games/<game_id>`

  Retrieve a summary of the game and its datasets

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB
  ```

  ```json
  response = {
    "type": "GET",
    "val": {
      "game_id": "AQUALAB",
      "dataset_count": 57,
      "session_average": 1234,
      "initial_dataset": "2021-04-11 00:00:00"
    },
    "msg": "SUCCESS: Retrieved monthly game usage"
  }
  ```

* `/games/details`

  Retrieve summaries of all games for which at least one dataset exists.

  Example:

  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/details
  ```

  ```json
  response = {
    "type": "GET",
    "val": {
      "AQUALAB": {
        "game_id": "AQUALAB",
        "dataset_count": 57,
        "session_average": 1234,
        "initial_dataset": "2021-04-11 00:00:00"
      },
      "AQUALAB": {
        "game_id": "BACTERIA",
        "dataset_count": 42,
        "session_average": 543,
        "initial_dataset": "2021-01-10 00:00:00"
      },
    },
    "msg": "SUCCESS: Retrieved list of games with available datasets"
  }
  ```


### Dataset-Level Endpoints

* `/games/<game_id>/datasets`

  Retrieve a list of datasets and associated session counts for a specific game.

  Approximately equivalent to the `/MonthlyGameUsage` legacy endpoint.
  However, the legacy endpoint includes additional entries for non-existent datasets that lie within the range of all extant datasets, with the session counts set to 0.

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB/datasets
  ```

  ```json
  response = {
    "type": "GET",
    "val": {
      "game_id": "AQUALAB",
      "datasets": [
        ...
        {"year": 2025, "month": 9, "total_sessions": 4908, "sessions_file": ..., "players_file": ..., "population_file": ...},
        {"year": 2025, "month": 10, "total_sessions": 4763, ...},
        {"year": 2025, "month": 11, "total_sessions": 5339, ...}
      ]
    },
    "msg": "SUCCESS: Retrieved monthly game usage"
  }
  ```

* `/games/<game_id>/datasets/<year>`

  Retrieve a list of datasets and associated session counts for a specific game within a specific month.
  Roughly equivalent to the `/games/<game_id>/datasets/` endpoint, but scoped to a single year.

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB/datasets/2023
  ```

  ```json
  response = {
    "type": "GET",
    "val": {
      "game_id": "AQUALAB",
      "datasets": [
        {"year": 2023, "month": 1, "total_sessions": 2013, "sessions_file": ..., "players_file": ..., "population_file": ...},
        {"year": 2023, "month": 2, "total_sessions": 17, ...},
        {"year": 2023, "month": 3, "total_sessions": 8605, ...}
        ...
      ]
    },
    "msg": "SUCCESS: Retrieved monthly game usage"
  }
  ```

* `/games/<game_id>/datasets/<year>/<month>`

  Get detailed info on the files and other resources that are available for a specific dataset. This is roughly equivalent to the `/getGameFileInfoByMonth` legacy endpoint.

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB/datasets/2023/01
  ```

* `/games/<game_id>/datasets/<year>/<month>/manifest` (experimental)

  Get a full "dataset manifest" for the given dataset. This includes details about events and features included in the dataset.

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB/datasets/2023/01/manifest
  ```

### File-Level Endpoints

* `/games/<game_id>/datasets/<month>/<year>/<file_type>`

  Retrieve the contents of a specific dataset file. Valid `file_type`s are `population`, `player`, and `session`.

  This is only recommended for applications that need direct access to dataset file contents.
  Local downloads should be obtained through the URLs provided in the other dataset endpoints.

  Future releases may add support for requesting event file contents.

  Example:
  ```bash
  curl https://ogd-staging.fielddaylab.wisc.edu/apis/files/main/games/AQUALAB/datasets/2023/01/player
  ```

## Developer Instructions

### Running the app locally via the development Flask server

Steps to run:

1. Ensure you have Python and pip installed in your development environment.
2. (optional) From the project root folder, run `python -m venv .venv` to create the `.venv` directory that will contain the virtual environment.
3. (optional) Activate the environment with `source .venv/bin/activate` on Mac/Linux, or `.venv/Scripts/activate` on Windows.
4. From the app's root directory run `pip install -r requirements.txt` to ensure you have Flask and other dependencies installed for the app.
    * If you are performing local development, you should instead run `pip install -e ./`
5. Copy `config/config.py.template` to `src/config.py` to create a config. Update `config.py` configuration values as needed.
6. Enter the source folder with `cd src` and then run `python -m flask run`, or optionally include the `--debug` flag.
7. A web server should begin running at http://localhost:5000
