An async C# wrapper for the Open Trivia DB API.
Via dotnet
:
dotnet add package OpenTDB-Wrapper --version 1.9.1
Via PackageReference
in your .csproj
file:
<PackageReference Include="OpenTDB-Wrapper" Version="1.9.1" />
As a good rule of thumb, add these using
statements.
using OpenTDB; // For fetching questions from the API
using OpenTDB.Enumerators; // For specifying optional paramters
using OpenTDB.Exceptions; // For handling OpenTDB exceptions
using OpenTDB.Models; // For interacting with the Question class
Create an instance of OpenTDB
.
OpenTDB.OpenTDB openTDB = new();
If you want to pass in your own HttpClient
you can do it like so:
HttpClient httpClient = new();
OpenTDB.OpenTDB openTDB = new(httpClient);
Warning
It is highly recommended that you call InitializeTokenAsync()
immediately after creation of the OpenTDB
object if you call it at all.
The Open Trivia Database API provides session tokens for ensuring no duplicate questions are retrieved. You can start usage of a token like so:
await openTDB.InitializeTokenAsync();
// Initializes the session Token.
After one of the following happens you will need to call ResetTokenAsync()
, this will get a new session token:
- After 6 hours your session token is automatically deleted by Open Trivia Database.
- If you ever exhaust all questions in the database.
You will know for certain that you should call this method if you get one of the following exceptions, these indicate your session token is dead:
Code 3: Token Not Found | Session Token does not exist.
Code 4: Token Empty | Session Token has returned all possible questions for the specified query. Resetting the Token is necessary.
await openTDB.ResetTokenAsync();
// Sets the Token to a newly created one.
Warning
GetQuestionsAsync()
should be wrapped in a try-catch
block as it throws OpenTDBException
and ArguementException
.
Warning
GetQuestionsAsync()
, should not be called less-than 5 seconds apart due to Open Trivia DB' rate limits.
Use GetQuestionsAsync()
to get a list of questions. This method has default values of Category.Any
, Difficulty.Any
, and QuestionType.Any
.
await openTDB.GetQuestionsAsync(10);
// returns a List<Question> with a Count of 10.
Here is a more complicated example. If you wanted to get 10 Nature questions, that were of easy difficulty, and in the form of multiple-choice questions, it would look like so:
await openTDB.GetQuestionsAsync(10, Category.Nature, Difficulty.Easy, QuestionType.MultipleChoice);
// returns a List<Question> with a Count of 10.
Important
All values in the Question
class will be encoded in whatever you specified when calling GetQuestionsWithEncodingAsync()
. You must handle parsing of this data.
Here is a more complicated example. If you wanted to get 10 Nature questions, that were of easy difficulty, in the form of a multiple-choice questions, and had legacy URL encoding it would look like so:
await openTDB.GetQuestionsWithEncodingAsync(10, Category.Nature, Difficulty.Easy, QuestionType.MultipleChoice, Encoding.LegacyURL);
// returns a List<Question> with a Count of 10.
The Category
enumerator contains all valid opetions for the "category" value of the API.
Value | Description | URL Request Category Value |
---|---|---|
Any |
Any category | - |
GeneralKnowledge |
General Knowledge | 9 |
Books |
Books | 10 |
Film |
Film | 11 |
Music |
Music | 12 |
MusicalsTheatres |
Musicals & Theatres | 13 |
Television |
Television | 14 |
VideoGames |
Video Games | 15 |
BoardGames |
Board Games | 16 |
Nature |
Nature | 17 |
Computers |
Computers | 18 |
Mathematics |
Mathematics | 19 |
Mythology |
Mythology | 20 |
Sports |
Sports | 21 |
Geography |
Geography | 22 |
History |
History | 23 |
Politics |
Politics | 24 |
Art |
Art | 25 |
Celebrities |
Celebrities | 26 |
Animals |
Animals | 27 |
Vehicles |
Vehicles | 28 |
Comics |
Comics | 29 |
Gadgets |
Gadgets | 30 |
AnimeManga |
Anime & Manga | 31 |
CartoonsAnimations |
Cartoons & Animations | 32 |
The Difficulty
enumerator contains all valid options for the "difficulty" value of the API.
Value | Description | Difficulty Value |
---|---|---|
Any |
Any difficulty | - |
Easy |
Easy | "easy" |
Medium |
Medium | "medium" |
Hard |
Hard | "hard" |
The QuestionType
enumerator contains all valid options for the "type" value of the API.
Value | Description | Type Value |
---|---|---|
Any |
Any type of question | - |
MultipleChoice |
Multiple-choice question | "multiple" |
TrueFalse |
True or false question | "boolean" |
The Encoding
enumerator contains all valid options for the "encoding" value of the API.
Value | Description | Encoding Value |
---|---|---|
HTML |
HTML | - |
LegacyURL |
Legacy URL | "urlLegacy" |
URL |
URL | "url3986" |
Base64 |
Base64 | "base64" |
The Question
class looks like this:
public class Question
{
public string Type { get; set; }
public string Difficulty { get; set; }
public string Category { get; set; }
public string QuestionTitle { get; set; }
public string CorrectAnswer { get; set; }
public string[] IncorrectAnswers { get; set; }
}
If you need to determine how many questions are in a specific category you can do so with GetCategoryQuestionTotalsAsync()
This can be done with a specific Category
:
await GetCategoryQuestionTotalsAsync(Category.Nature);
// returns a CategoryCount object.
Or with an integer representing the Category
ID:
await GetCategoryQuestionTotalsAsync(17);
// returns a CategoryCount object.
The CategoryCount
class looks like this:
public class CategoryCount
{
public int CategoryId { get; set; }
public int TotalQuestions { get; set; }
public int TotalEasyQuestions { get; set; }
public int TotalMediumQuestions { get; set; }
public int TotalHardQuestions { get; set; }
}
If you need to find out things like how many questions there are in the entire database you should use GetGlobalQuestionTotalsAsync()
.
await GetGlobalQuestionTotalsAsync();
// returns a GlobalCount object.
The GlobalCount
class looks like this:
public class GlobalCount
{
public int TotalQuestions { get; set; }
public int TotalPendingQuestions { get; set; }
public int TotalVerifiedQuestions { get; set; }
public int TotalRejectedQuestions { get; set; }
public List<GlobalCategoryCount> Categories { get; set; }
}
If you need to find just the categories provided by the API you should use GetApiCategoriesAsync()
(although, you could always just look at the Category
enum).
await GetApiCategoriesAsync()
// returns a List<ApiCategory> object.
The ApiCategory
class looks like this:
public class ApiCategory
{
public int Id { get; set; }
public string Name { get; set; }
}
This wrapper has 100% API coverage!
- Open Trivia DB API uses Creative Commons Attribution-ShareAlike 4.0 International License.
- OpenTDB-Wrapper uses GPL-3.0 License and is not affiliated with the Open Trivia Database.