Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

booru

AtoraSuunva1.6kMIT2.7.0TypeScript support: included

Search (and do other things) on a bunch of different boorus!

booru, e621, hypnohub, danbooru, konachan, yandere, gelbooru, rule34, safebooru, tbib, xbooru, paheal, derpibooru

readme

booru

A node package to search boorus

CircleCI npm GitHub Typescript typings

Minimum supported Node.js version: >=18.17

Features

  • Search 15 different boorus (check sites.json)
  • Normalizes all received data into Post objects that are consistent no matter which booru you use
  • Access to the raw data received from the booru as well (transformed from XML to JSON, if applicable)
  • Alias support for boorus (sb for safebooru.org)
  • Promises
  • Types (using Typescript)
  • Choose the amount of images to get
  • Random support for all sites, using order:random on sites that support it and using custom code on those that don't
  • Coming soon(-ish): Support for more than just searching

Installation

npm add booru
# or
yarn add booru

Usage

const Booru = require('booru')

Booru.search('safebooru', ['glaceon'], { limit: 3, random: true }).then(
  posts => {
    for (let post of posts) console.log(post.fileUrl, post.postView)
  },
)

// or (using alias support and creating boorus)
const sb = Booru.forSite('sb')

sb.search(['cat', 'dog'], { limit: 2 })

See example.js for more examples

Docs

Available here: https://booru.js.org

Web support

booru was built for Node.js, and is only officially supported for Node.js. Issues relating to web are fine, although support might be limited.

It's possible to use booru on the web using webpack (or similar), although your experience may vary. Some websites don't have the proper CORS headers, meaning that API requests to those sites from a browser will fail! This is not an issue I can fix in the package, and requires either that booru to add proper support themselves or for you to find a workaround for CORS.

FAQ

What are the properties of a Post?

The basic structure of a Post object looks like:

Post {
  data: {/*...*/},                       // The raw data from the booru
  fileUrl: 'https://aaaa.com/img.jpg',    // The direct link to the image, ready to post
  id: '124125',                           // The image ID, as a string
  tags: ['cat', 'cute'],                  // The tags, split into an Array
  score: 5,                               // The score as a Number
  source: 'https://ex.com/aaa.png',       // Source of the image, if supplied
  rating: 's',                            // Rating of the image
  createdAt: Date,                        // The `Date` this image was created at
  postView: 'https://booru.ex/show/12345' // A URL to the post
}

s: 'Safe' q: 'Questionable' e: 'Explicit' u: 'Unrated'

Derpibooru has Safe, Suggestive, Questionable, Explicit, although Suggestive will be shown as q in <Post>.rating

Can I contribute?

Sure! Just fork this repo, push your changes, and then make a PR.

I'll accept PR based on what they do and code style (Not super strict about it, but it's best if it roughly follows the rest of the code)

Why?

Why not?

License?

It's MIT

Contributors

BobbyWibowo

Change from request-promise-native to snek-fetch

rubikscraft

Add 2 new boorus (furry.booru.org/realbooru.com)
Various Derpibooru fixes

Favna

Add TypeScript declarations
Improve TypeScript port
Various other small fixes

negezor

Add missing type information

iguessthislldo

Copy tags argument so it's not modified

changelog

booru Changelog

2.7.0

  • Update undici
  • Fix previewUrl for paheal (https://github.com/AtoraSuunva/booru/pull/110) by Rider21
  • Include booru version in default user agent
  • Allow explicitly passing undefined to credentials in Booru constructor & to SearchParameters under strict Typescript
  • doSearchRequest doesn't mutate tags parameter
  • Many, many internal changes that shouldn't impact end-user library use but makes dev work much easier for me:
    • Use biome instead of eslint + prettier + tons of setup for typescript
    • Use node:test + tsx instead of jest + babel + swc

2.6.9

  • Update dependencies
  • Update Node engine version to v18.17 because that's the actual minimum supported version, older versions crash

2.6.8

  • Replace api-cdn.rule34.xxx with xbooru.com for xbooru.com searches, since the API returns the wrong URLs (#107)

2.6.7

  • Update API URL for paheal.net (old one now returns an HTML page instead of posts)
  • Update dependencies

2.6.6

  • Update dependencies

2.6.5

2.6.4

  • Update dependencies, notably fixing a fast-xml-parser security issue

2.6.3

  • Export more types:
    • BooruCredentials, Derpibooru, XmlBooru, Post, SearchParameters, SearchResults, Site
  • Correctly mark Hypnohub as not supporting order:random (or any random sorting)
  • Update dependencies

2.6.2

  • Fixed tags being encoded twice (#94)
  • Fixed e621/e926 returning score: NaN on posts with 0 total score

2.6.1

  • Fixed tags being incorrectly joined with an encoded +/, (#93)

2.6.0

  • Added credential support
    • Support is fairly basic and only support query param auth
    • The credential object provided will be serialized into query params
    • Previously credentials did nothing, now they do something
  • Updated some types to return more useful type unions (like AnySite being a union of all site domains)
  • Booru#getSearchUrl now properly accepts no parameters
const booru = require('booru')
const gelbooru = booru.forSite('gb', { api_key: 'key', user_id: 'id' })
gelbooru.getSearchUrl()
// https://gelbooru.com/index.php?page=dapi&s=post&q=index&json=1&tags=&limit=100&pid=1&api_key=key&user_id=id

// or
booru.search('gb', [], {
  credentials: { api_key: 'key', user_id: 'id' },
})
// Uses the same search URL as above

2.5.9

2.5.8

  • Fix error when searching rule34.xxx with tags that return no results
    • For some reason, the API literally returns an empty response with HTTP 200 instead of an empty array (or at least a different status code)

2.5.7

  • Fix error when splitting by tags when konachan returned an empty string (thanks youliao)
  • Update dependencies
    • Use Undici instead of node-fetch

2.5.6

  • Update endpoints for Hypohub
  • Update tag-joining logic for Derpibooru (use , to join tags instead of +)
  • Fix regression that happened when the previous regression was fixed because programming
    • Both danbooru-based boorus and non-danbooru boorus should be fine now

2.5.5

  • Fix regression where previous fix for Danbooru broke some other boorus

2.5.4

  • Handle cases where some Danbooru-based boorus (like realbooru) return "directory": null in their API response and cause invalid URLs to be generated by booru
  • Slightly prettier example.js

2.5.3

  • Use encodeURIComponent instead of encodeURI for tags to properly encode them
  • Update some project files for more consistent development

2.5.2

  • Fixed parsing of gelbooru's API response

2.5.1

  • Broken version, deprecated and removed

2.5.0

  • Update API endpoint for r34.xxx, see https://github.com/AtoraSuunva/booru/pull/75
  • Add Booru#getSearchUrl, meant for aiding in debugging
    • You can use this to get the URL that booru would use to search, to inspect the response yourself
  • Minor changes to allow VS code's Run & Debug to work, kinda
    • Still needs some setup, and some refactoring to get working nicely

2.4.2

2.4.1

  • Moved from tslint (deprecated) -> eslint
  • Moved tslint style rules -> prettier for formatting
  • Updated dependencies
  • Moved from my old username to new username

2.4.0

  • Removed furry.booru.org since they have CloudFlare browser verification enabled.
    • As far as I know, there's no (intended) way to bypass this if you're not a browser.
    • Added CloudFlare-specific error message if this happens in the future
  • Add fix for Paheal changing their API response format
  • Make example.js only specify the "cat" default tag if you don't specify a site
  • Change from tsc -> typescript for package.json scripts, since tsc is deprecated.
  • Update dependencies

2.3.3

  • Fix Paheal failing to provide a useful error message.
    • Details: Paheal was returning an HTML error page instead of a JSON response. The previous way of scraping an error message off HTML pages failed on the page Paheal returned.
  • Move from terser-folder to a custom minify.js, which handles both .js and .json minifying
    • terser-folder also hasn't been updated in 2 years
  • Update circle ci to use node 14 instead of 11
  • Update dependencies, no more security vulnerabilities!

2.3.2

  • Added Post#available, to check if a post isn't deleted/banned
  • By default, unavailable posts aren't returned in search results
    • You can use SearchParameters#showUnavailable to still get them
    • Booru.search('db', ['cat'], { showUnavailable: true })
  • Fix for danbooru occasionally having invalid fileUrl or missing IDs
    • You can use Post#available to check for this

2.3.0

  • Fix for illegal invocation errors when using booru on the web
    • Some of the APIs don't have the required CORS headers however
  • Add encodeURI to tags when searching, to avoid encoding errors from the API
  • Better example.js file, now supports command line input
  • Remove lolibooru

2.2.3

  • Various fixes for Derpibooru support

2.2.2

  • Fix default tags missing from post results
  • Fix scores/sources/createdAt post props for some sites

2.2.1

  • Added missing check for results.posts in API response

2.2.0

  • Support for e621/e926's new api
  • Fix BooruError wiping out stack trace of caught error
  • Dependency updates

2.1.0

  • Update dependencies
  • Fix typo in "hypo" for hypnohub's aliases #42
  • Workaround for JS projects trying to use new booru(site) #40
    • Will still "work" for certain projects, but now booru.forSite(site) is preferred

2.0.5

  • Last release before changelog started