Introduction From 1.4.8 to 2.0.0 Quick Start Feature list Instantiate boorus Authentification Create your own booru Exception thrown General functions Post functions Comment functions Tag functions Related functions Wiki functions

Welcome on BooruSharp 2.0.1 documentation.

BooruSharp is a C# library allowing you to get images from Booru websites. BooruSharp currently handle the following websites:
The project is available on GitHub at https://github.com/Xwilarg/BooruSharp
And on NuGet at https://www.nuget.org/packages/BooruSharp/
If you need additional help you can come ask your questions on Discord or open an issue on GitHub

This documentation is for the version 2.0.1. For the version 1.4.8, please refer to the old one: https://github.com/Xwilarg/BooruSharp/wiki


Migrating from 1.4.8 to 2.0.0

See the transition guide.


Quick Start

To begin with you must instantiate a new Booru, they are in the namespace BooruSharp.Booru
var booru = new BooruSharp.Booru.Gelbooru();
Then you can use all the different functions from it:
var result = booru.GetRandomImageAsync("kantai_collection");
Console.WriteLine(result.fileUrl);
You can scroll bellow to see the different functions available.


Feature list

Booru Post by MD5 Tag by ID Comment API Last Comments API Wiki API Related Tag API
Atfbooru ✔️ ✔️ ✔️ ✔️ ✔️
Danbooru Donmai ✔️ ✔️ ✔️ ✔️ ✔️
E621 ✔️
E926 ✔️
Furry Booru ✔️ ✔️ ✔️
Gelbooru ✔️ ✔️ ✔️
Konachan ✔️ ✔️ ✔️ ✔️ ✔️
Lolibooru ✔️ ✔️ ✔️ ✔️ ✔️
Realbooru ✔️ ✔️ ✔️
Rule 34 ✔️
Safebooru ✔️
Sakugabooru ✔️ ✔️ ✔️ ✔️
Sankaku Complex ✔️ ✔️ ✔️ ✔️
Xbooru ✔️ ✔️ ✔️
Yandere ✔️ ✔️ ✔️ ✔️



Instantiate boorus

There are several boorus you can use, here are the ways the instantiate them:
new Atfbooru(BooruAuth auth = null);
new DanbooruDonmai(BooruAuth auth = null);
new E621(BooruAuth auth = null);
new E926(BooruAuth auth = null);
new Furrybooru(BooruAuth auth = null);
new Gelbooru(BooruAuth auth = null);
new Konachan(BooruAuth auth = null);
new Lolibooru(BooruAuth auth = null);
new Realbooru(BooruAuth auth = null);
new Rule34(BooruAuth auth = null);
new Safebooru(BooruAuth auth = null);
new Sakugabooru(BooruAuth auth = null);
new SankakuComplex(BooruAuth auth = null);
new Xbooru(BooruAuth auth = null);
new Yandere(BooruAuth auth = null);
BooruAuth is the authentification method, see below for more information.


Authentification

Authentification is not needed for now but here's how it works:
To use it you must instantiate a new BooruAuth using CreateFromApiKey or CreateFromPasswordHash.
To know which one to use, you can refer to this:
Booru Can use API Key Can use Password Hash
Atfbooru ✔️ ✔️
Danbooru Donmai ✔️ ✔️
E621 ✔️
E926 ✔️
Furry Booru ✔️
Gelbooru ✔️
Konachan ✔️
Lolibooru ✔️
Realbooru ✔️
Rule 34 ✔️
Safebooru ✔️
Sakugabooru ✔️
Sankaku Complex ✔️
Xbooru ✔️
Yandere ✔️


Create your own booru

To create your own booru, you need to inherit one of the class in BooruSharp.Booru.Template.
Each booru take in parameters the base URL of the website, the authentification to the booru (can be null) and somme BooruOptions (optional).
The templates are: Here's an example with Safebooru (https://safebooru.org/):
public sealed class Safebooru(BooruAuth auth = null) : base("safebooru.org", auth, BooruOptions.noComment)
BooruOptions are settings to precise the behaviour of your booru.
Templates probably already gives most of the options you need so you don't have to think too much about them.

Exception thrown




General functions

HaveRelatedAPI returns if the booru have a "tag related" API
bool HaveRelatedAPI();

HaveWikiAPI returns if the booru have a "wiki" API
bool HaveWikiAPI();

HaveCommentAPI returns if the booru have a "comment" API
bool HaveCommentAPI();

HaveTagByIdAPI returns if the booru have a can search tags by ID
bool HaveTagByIdAPI();

HaveSearchLastComment returns if the booru can search for all last comments
bool HaveSearchLastComment();

CheckAvailabilityAsync check if the booru is avaiable, throw a HttpRequestException if not
async Task CheckAvailabilityAsync();


Post functions

GetImageByMd5Async returns a post given it MD5 hash
async Task<Search.Post.SearchResult> GetImageByMd5Async(string md5);

GetRandomImageAsync returns a random post. Tags can be given in parameters
async Task<Search.Post.SearchResult> GetRandomImageAsync(params string[] tagsArg);


Search.Post.SearchResult is defined by the following struct

Url of the image
Uri fileUrl

Preview url of the image
Uri previewUrl

Is the image safe or not
Rating rating
enum Rating
{
    Safe,
    Questionable,
    Explicit
}

All the tags contained in the image
string[] tags

Id of the image
int id

Size in octets of the image
int? size

Height in pixels of the image
int height

Width in pixels of the image
int width

Height in pixels of the preview image
int? previewHeight

Width in pixels of the preview image
int previewWidth

Wehn the post was created
DateTime? creation

Where the image is coming from
string source

Score of the image
int score

Hash (md5) of the image
string md5


Comment functions

GetCommentsAsync return the comment of a post given it id
async Task<Search.Comment.SearchResult> GetCommentsAsync(int postId);

GetLastsCommentsAsync return the lasts comments posted on the website
async Task<Search.Comment.SearchResult> GetLastsCommentsAsync();


Search.Comment.SearchResult is defined by the following struct

Id of the comment
int commentId

Id of the image associated with the comment
int postId

Id of the author of the comment, is null if the author is anonymous
int? authorId

When the comment was posted
DateTime creation

Name of the author of the comment
string authorName

Comment's message
string body


Tag functions

GetTagAsync return a tag given it name
async Task<Search.Tag.SearchResult> GetTagAsync(string name);

GetTagAsync return a tag given it id
async Task<Search.Tag.SearchResult> GetTagAsync(int id);

GetTagsAsync return the similar tags of the one given in parameter
async Task<Search.Tag.SearchResult[]> GetTagsAsync(string name);


Search.Tag.SearchResult is defined by the following struct

Id of the tag
int id

Name of the tag
string name

Type of the tag (character, copyright, etc...)
TagType tag
enum TagType
{
    Trivia,
    Artist,
    Copyright = 3,
    Character,
    Metadata
}

Number of occurences of the tag
int count


GetRelatedAsync return the tags related to the one given in parameter
async Task<Search.Related.SearchResult[]> GetRelatedAsync(string tag);


Search.Related.SearchResult is defined by the following struct

Name of the tag
string name

Number of occurences of the tag
int? count


Wiki functions

GetWikiAsync return a wiki page
async Task<Search.Wiki.SearchResult> GetWikiAsync(string query);


Search.Wiki.SearchResult is defined by the following struct

Id of the wiki entry
int id

Name of the tag described
string title

Date when the entry was created
DateTime creation

Date of the latest update to the entry
DateTime lastUpdate

Tag description
string body