Files API

This section describes how to use the File API from your web browser.

The OGD File API

This API is used to browse information about the datasets provided by OpenGameData, typically via the OGD website. However, it is possible to navigate the API as a human user.

You may, for example, have previously submitted a game for inclusion on the OpenGameData website. This game might have an initial dataset, but may not yet have its own page included in the OpenGameData website. In this case, you can find the link to download your dataset via the API.

Base Location

The base URL for the File API is the following: https://ogd-services.fielddaylab.wisc.edu/apis/files/latest/app.wsgi

All API requests you make will be relative to this base URL.

Accessing APIs With Your Browser

While the output isn’t the prettiest, you can easily use your browser to request data from most of our API endpoints. In particular, you can use any endpoint that supports the “GET” request method. This includes all endpoints for the File API, which is the API that a human user is most likely to make use of.

To access an API endpoint with your browser, simply perform the following steps:

  1. Identify your base URL. For example: ogd-services.fielddaylab.wisc.edu/apis/files/latest/app.wsgi

  2. Identify which endpoint you want to access. For example, suppose you want to get the list of datasets for the game AQUALAB. The endpoint is: /games/AQUALAB/datasets

  3. Add the endpoint to the base to get a full URL. In our example, this would be: ogd-services.fielddaylab.wisc.edu/apis/files/latest/app.wsgi/games/AQUALAB/datasets

  4. Open the URL in your browser. This step is the same as opening any other URL in your browser. You could type it in to the browser’s address bar directly, or paste it from somewhere else. The result should be a very simple display of some JSON-structured data, corresponding to your request:

    The results of an example API request displayed in the Chromium web browser (with pretty-printing enabled)

Endpoints

The File API provides the following endpoints, which you can use to access specific details about available datasets, as well as the games behind those datasets. Broadly speaking, there is a 3-level hierarchy for retrieving this information.

  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.

There are also a few “legacy” endpoints used by older versions of the website. These are considered deprecated, and will be removed in a future version of the API.

Game-Level Endpoints

  • /games

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

    Example:

    curl https://ogd-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/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-services.fielddaylab.wisc.edu/apis/files/latest/games/AQUALAB/datasets/2023/01/player

Legacy Endpoints

Endpoints used by the OpenGameData website, which use an outdated convention. We intend to deprecate these in the near future.

  • /MonthlyGameUsage : Retrieve a list of datasets and associated session counts for a specific game.

    Query string params: game_id

  • /getGameFileInfoByMonth : Get detailed info on the files and other resources that are available for a specific dataset.

    Query string params: game_id, year, month