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 data.opengamedata.io, 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:

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

  {
    "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:

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

  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:

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

  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:

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

  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:

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

  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:

  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:

  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_types 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:

  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