# Loquiz API Documentation

## Overview

The Loquiz API version 3 provides a RESTful interface for retrieving game results. The API is hosted at:

**Base URL**: `https://api.loquiz.com/v3`

---

## Endpoints

### 1. Get Game Info

**Endpoint**: `GET /games/{gameId}`

Retrieve detailed information about a specific game, including tasks.

**Parameters**:

* `gameId` (path, required): The unique identifier of the game.

**Responses**:

* `200 OK`: Returns game details.
* `401 Unauthorized`: Game data is not public or invalid API key.
* `404 Not Found`: Game not found.
* `500 Internal Server Error`: Server-side error.

---

### 2. Get Teams in a Game

**Endpoint**: `GET /results/{gameId}/teams`

Retrieve a list of teams registered for a specific game.

**Parameters**:

* `gameId` (path, required): The unique identifier of the game.
* `scope` (query, optional): Filter by comma-separated list of scopes.
* `ticketId` (query, optional): Filter by comma-separated list of ticket IDs.
* `skip` (query, optional): Number of items to skip.
* `limit` (query, optional): Number of items to return (max 100).
* `sort` (query, optional): Field to sort by. Default is `-totalScore`. Prepend with `-` for descending order.

  * Options: `totalScore`, `correctAnswers`, `incorrectAnswers`, `startTime`, `finishTime`, etc.
* `group` (query, optional): Group teams by scope. Response will include `id`, `teamIds`, and `names`.
* `includeAnswers` (query, optional): Include team answers if set to `true` or `1`.
* `includeFirstImage` (query, optional): Include the first uploaded image for each team if set to `true` or `1`.

**Responses**:

* `200 OK`: Returns a list of teams as `{ "total": "number", "items": [Team] }`.
* `401 Unauthorized`: Game results are not public or invalid API key.
* `404 Not Found`: Game not found.
* `500 Internal Server Error`: Server-side error.

---

### 3. Get Media Uploaded by Teams

**Endpoint**: `GET /results/{gameId}/media`

Retrieve media files (e.g., images, videos) uploaded by teams during a game.

**Parameters**:

* `gameId` (path, required): The unique identifier of the game.
* `scope` (query, optional): Filter by comma-separated list of scopes.
* `ticketId` (query, optional): Filter by comma-separated list of ticket IDs.

**Responses**:

* `200 OK`: Returns a list of media files as `{ "total": "number", "items": [Media] }`.
* `401 Unauthorized`: Game results are not public or invalid API key.
* `404 Not Found`: Game not found.
* `500 Internal Server Error`: Server-side error.

---

## Components

### Schemas

#### Error

```json
{
  "error": "string",
  "message": "string"
}
```

#### Game

Detailed properties for games, including settings, colors, tasks, and permissions.

```json
{
  "id": "string",
  "title": "string",
  "logoUrl": "string",
  "primaryColor": "string",
  "secondaryColor": "string",
  "units": "metric | imperial",
  "language": {
    "id": "string",
    "version": "integer"
  },
  "pinInfo": "order | score | intro | none",
  "taskBackgroundImageUrl": "string",
  "intro": "string",
  "outro": "string",
  "hintLimit": "integer",
  "penalizeIncorrectAnswers": "boolean",
  "allowChatting": "boolean",
  "showShortIntroUnderPin": "boolean",
  "showAllTeamScores": "boolean",
  "showAllTeamLocations": "boolean",
  "disableTeamTracks": "boolean",
  "allowTaskFiltering": "boolean",
  "hideFollowMe": "boolean",
  "hideMyLocation": "boolean",
  "showMyTrack": "boolean",
  "allowNavigation": "boolean",
  "allowAppFeedback": "boolean",
  "hideScore": "boolean",
  "hideScoreUntilPlayTime": "number",
  "hideScoreFromPlayTime": "number",
  "showCodeScanner": "boolean",
  "hideGameTime": "boolean",
  "showPostAnswerComment": "boolean",
  "multiplePlayersPerTeam": "boolean",
  "afterFinishMeetingPoint": {
    "location": {
      "lat": "float",
      "lng": "float",
      "radius": "float"
    },
    "pin": {
      "none": "boolean",
      "1x": "string",
      "2x": "string",
      "3x": "string",
      "iconAnchor": [
        "float",
        "float"
      ],
      "areaColor": "string"
    },
    "message": "string"
  },
  "mapTiles": [
    {
      "type": "string",
      "style": "string"
    }
  ],
  "mapOverlays": [
    {
      "imageUrl": "string",
      "alpha": "number",
      "bounds": {
        "top": "number",
        "right": "number",
        "bottom": "number",
        "left": "number"
      },
      "rotation": "number"
    }
  ],
  "tasks": [
    {
      "id": "string",
      "text": "string",
      "answerType": "single | multiple | text | number | number:range | photo | video | none | activity",
      "survey": "boolean",
      "codeBox": "boolean",
      "answers": [
        {
          "text": "string",
          "correct": "boolean"
        }
      ],
      "difficulty": "number",
      "timeLimit": "integer",
      "comments": {
        "shortIntro": "string",
        "hint": "string",
        "correct": "string",
        "incorrect": "string"
      },
      "media": [
        {
          "type": "image | youtube | vimeo | webpage | audio",
          "url": "string"
        }
      ],
      "password": "string",
      "backgroundAudio": {
        "url": "string",
        "loop": "boolean"
      },
      "showAnswerCorrectness": "boolean",
      "showCorrectAnswer": "boolean"
    }
  ]
}
```

#### Team

Details about a team, including scores, members, and answers.

```json
{
  "id": "string",
  "scope": "string",
  "ticketId": "string",
  "name": "string",
  "members": ["string"],
  "isFinished": "boolean",
  "startTime": "number",
  "finishTime": "number",
  "answersScore": "number",
  "bonusScore": "number",
  "totalScore": "number",
  "correctAnswers": "number",
  "incorrectAnswers": "number",
  "hints": "number",
  "odometer": "number",
  "answers": [
    {
      "id": "string",
      "taskId": "string",
      "answer": "string",
      "correct": "boolean",
      "time": "number",
      "timeToAnswer": "number",
      "outOfTime": "boolean",
      "hintUsed": "boolean",
      "score": "number"
    }
  ],
  "firstImage": {
    "thumbnail": "string",
    "optimized": "string",
    "original": "string"
  }
}
```

#### Medium

Details about uploaded media, including paths to thumbnails and original files.

```json
{
  "id": "string",
  "teamId": "string",
  "scope": "string",
  "ticketId": "string",
  "taskId": "string",
  "thumbnail": "string",
  "optimized": "string",
  "original": "string",
  "time": "number"
}
```

---

## Usage Notes

- Timestamps are in seconds since the epoch (Unix time).
- All responses are in JSON format.
- Ensure to handle pagination for endpoints that return lists (e.g., teams, media).
- Use appropriate error handling for responses, especially for `401 Unauthorized` and `404 Not Found`.