The starting point of any treasure hunt challenge is to list the available treasure hunts so the player can pick the one they want to compete in. This is enabled using the /th/api/list call.

The API call is as follows:

The call has these parameters:

The output includes the status and the array of available treasureHunts.

To join a treasure hunt, the player must use the start call and specify their name, app id and requested treasure hunt id.

The API call is as follows:

The call has these parameters:

The output includes the status the total numOfQuestions and the session id which is required for subsequent calls, such as to get the current question.

Once you join a treasure hunt you can start looking up questions. To view a question, you can use the /th/api/question call. This gives you information about the actual question (i.e. its text) as well as the expected answer type.

The API call is as follows:

The call has one parameter:

The output includes the status and some properties of the question. For instance the completed property specifies if the user has already completed this treasure hunt (i.e. has answered all questions already). The questionText contains the text-based question, whcih can also be specified in simple HTML. The questionType specifies the expected type of the answer. The possible answer types are:

• BOOLEAN can be either Boolean value true/false
• INTEGER can be any valid integer like -1, 0, 1, 2, etc.
• NUMERIC can be any valid numeric value like -1.2, 0.2, 1.234, etc.
• MCQ can be any of four possible multiple-choice answers, i.e. A, B, C, D
• TEXT can be any general text, normally a single word

The canBeSkipped is a Boolean that specifies whether this particular question can be skipped or must be answered. The requires-location indicates whether this is a location sensitive question where the player must be at a specific location for their answer to be checked. The numOfQuestions specifies the total number of questions in the treasure hunt, and the currentQuestionIndex defines the zero-based index of the current question (the first one is 0, and the last one is numOfQuestions-1). Finally, the correctScore, wrongScore and skipScore specify the score adjustment for when the answer is correct, wrong, or the question was skipped, respectively.

To answer the current question you can use the /th/api/answer call. This allows you to specify the answer for the given session.

The API call is as follows:

The call has two parameters:

The output includes the status and some properties such as whether the provided answer was correct, whether the session is no completed (meaning there are no more unanswered questions), an optional text-based message and the scoreAdjustment as an integer that indicates how the score has changed (i.e. points gained or subtracted from the player's score).

Some of the questions require that the player is at a specific location to be able to answer. The /th/api/location call allows you to specify the location in terms of latitude and longitude for the given session.

The /th/api/location call is used periodically to update the server of the player's current location, and also before answering a location-sensitive question as indicated by the requires-location property of the /question call. Normally, you can not call /th/api/location too often. Instead allow at least 30 seconds between calls.

The API call is as follows:

The call has three parameters:

The output includes the status and a text-based message explaining whether the call was recorded or not.

Some of the questions can be skipped, usually with a penalty to the score. The /th/api/skip call allows you to skip a question if the player chooses to do so.

The API call is as follows:

The call has one parameter:

The output includes the status, a Boolean indication of whether the treasure hunt is completed after skipping, a text-based message and the scoreAdjustment which is normally a negative integer, e.g. -5.

The /th/api/score call is used to access the current score of this session.

The API call is as follows:

The call has one parameter:

The output includes the status, a Boolean indication of whether the treasure hunt is completed, i.e. there are no more unanswered questions, and whether the treasure hunt is finished, i.e. it has ended time-wise. The player property gives the selected player name, the score property gives the score as an integer, e.g. 23. Last, the hasPrize property shows whether there is a prize associated with the current treasure hunt (this is needed for some special applications).

Naturally multiple players can be competing in a treasure hunt. To access the current leaderboard us the /th/api/leaderboard call and specify either the current player session or the selected treasure-hunt-id. Optionally, also use the sorted flag to indicate that you want the list of scores to be sorted from higher to smaller score. You can also specify the optional limit parameter to limit the number of entries that appear in the leaderboard.

The API call is as follows:

The call has four possible parameters. You can only use one of session and treasure-hunt-id. If you specify both, the latter is ignored. The other parameters are as follows:

The output includes the status, the numOfPlayers, a Boolean value indicating whether the list is sorted, the applied limit and the leaderboard. When not specified or when invalid, the limit is automatically set to the max integer value, i.e. 2147483647. Finally, the nae of the corresponding Treasure Hunt is provided for convenience as the named value treasureHuntName.

The leaderboard consists of a JSON array containing numOfPlayers entries, where each entry has a player name, a score and a completionTime. The latter is a timestamp of when the player answered the last question, expressed in Unix epoch in milliseconds. If the player has not finished yet, it is set to zero.

Players with higher score are ranked higher irrespective of completionTime. When players have the same score then the player with the earliest completionTime is ranked higher (as the player answered the last question first). Players with a completionTime of zero (i.e. unfinished) are ranked lower to other players with the same score.