images – query image database

This is part of IbSearch API v1.x.

https://ibsear.ch/api/v1/images.format?parameters

Example

q The query string. It has the same format as accepted by the site's main search function (on your left) and is described below.
limit Number of records to retrieve (size of the page). Defaults to 25. Maximum value is 100.
page Starts from and defaults to 1. Bigger number navigates further into result set (it also takes much longer to generate the further you get).
shuffle Randomly reorders images on the current page. This is unlike random and sort that return random images each time. If numeric value is given keeps (outputs) only that number of results - useful if you want to quickly get pseudo-random images each time: limit=50&shuffle=20.
sources If set to 1, result will have one image entry per indexed site instead of one unique image entry. This way you search sites instead of images getting results on each found image across indexed boorus. Some extra fields are returned (like image ID on that site) - see below. You can determine if the image is duplicate by its IBID. Same image is not necessary grouped by all sites, you can get image 1 from Gelbooru, image 2 from Danbooru, then image 1 again but from Danbooru unless you sort by ID (but doing so may slow down your search). If set to one only adds those extra fields filled with the first (undetermined) site without duplicating image entries.
relations Enables fetching of parent/child relations. If set to 1child, 1parent or 1both (or just 1 - alias to it), two extra fields (first parent and first child) are added to each image entry (all images are still returned but with extra info on each, that can be empty - unlike the following mode). If set to child (images that are child of some others), parent (images with children) or both (any of those), result will have one image entry per each image relation (child and/or parent) instead of one unique image entry - similar to using sources (they can be combined) and the same notes apply here. Note: this parameter makes your query much heavier so use only when needed and request only what's needed (e.g. if you only need info on one parent don't use 1both). Note: when doing 1child/child/1parent/parent don't rely on what is returned in the other field (i.e. ignore child ID for 1parent/child and parent ID for 1child/parent).

Note: if you combine parameters that expand image entries with those that don't (like sources as one but relations as child) expansion won't happen and images won't duplicate as if you used non-expanding values for all parameters. This is not optimal for the query so expand either all or none (it's okay to expand on multiple parameters).

Picture rating

IbSearch is not one but two sites: ibsear.ch with safe-for-work content only (s) and ibsearch.xxx with both SFW and mature content (s q e). This restriction is global and unaffected by search filters so a query for rating:e,q,s on .ch will always round down to rating:s.

So if you want all images - query ibsearch.xxx in the same way as described here. When querying ibsear.ch you can be sure that results will be appropriate regardless of your input (but we can't guarantee that every image in the database is rated correctly).

Result

Produces an array of entries with the members described below. Empty array is returned if there are no matches (or the end of result set is reached when page is used).

Key Meaning Example
id The IBID - IbSearch Image ID. Unique number that identifies the same image across all indexed sites ("same" here means identical on the binary level - so resaving the image will yield "different" version). 4394433
rating How explicit ("lewd") the image is. ? means "unknown", e means "explicit" (totally adult), q means "questionable" (some edgy content may appear), s means "safe" (show to your kids). q
tags List of space-separated tags for this image in traditional booru notation (spaces in tags replaced with underscores). Not necessary ordered and might contain duplicates (it usually doesn't but there are cases when it does). Always lower case. 1girl black_hair kirishima_(kantai_collection)
format Picture format: one of png, jpg, gif. Special value ? is nt supposed to appear but you should know it exists. jpg
width Horizontal dimension of the image. Canvas width in pixels. 1600
height Vertical dimension of the image. Canvas height in pixels. 1200
area Canvas width multiplied by height. This is useful if you want to look for images that are "large" but don't care about how large each side is. 1920000
aspectw Canvas width divided by height, multiplied by 1000 and with removed decimal part. Tells how big image width is when compared to height. An image of 16:10 aspect ratio will have this as 1600 (16 / 10 * 1000). 1600
aspecth Like aspectw but for height. A 16:10 image will have this as 625 (10 / 16 * 1000). 625
sha1 SHA-1 hash of the image file in hexadecimal form (40 symbols). 0835798E3D3F7A51298CD06E1AA33F84AD96C84F
md5 MD5 hash of the image file in hexadecimal form (32 symbols). 8D923D3C4678D8AB76684E34BD59751F
found Unix timestamp (number of seconds since 01.01.1970) indicating when the image was first indexed by IbSearch (IBID created). 1427592710
size Image file size in bytes. 504434
server IbSearch subdomain name where the image file is stored. im1
path Path to the image file on server subdomain. You can construct complete URL like this: https://server.ibsear.ch/path. All thumbs have fixed dimensions and reside under the same URL but with t before path (e.g. t3/74/b2d...). Path structure may change (and did change) so don't assume anything about it. 8/d9/23d3c4678d8ab76684e34bd59751f.jpg
random A random number between 0 and 65,535 (unsigned 16-bit integer) updated daily per image. 700533780
hits Number of times this image was viewed on IbSearch. This is a very rough metric, it doesn't track duplicate views. Can given an idea of how popular the image is, relatively. 7183
Extra fields returned when sources is set (one might return blanks in all these fields for some rare images with unavailable source info)
site IbSearch site ID, a small number. Map it to actual sites using sources API function. 2
site_id Image ID on that particular site. Is unique site-wise but might be not unique to IbSearch. 1153817
site_found Timestamp indicating when the image was first indexed by IbSearch on that site. 1427568392
site_uploaded Timestamp indicating when the image was uploaded to that site. 1426399127
site_deleted If the image was deleted from that site this is the timestamp of the event (or timestamp of when this was detected by IbSearch since some sites don't show deletion date/time). Note that images going into private/premium sections (e.g. on Danboru) are also marked as "deleted". 1426481272
site_page URL of the image page (i.e. its HTML description) relative to site's root. Begins with a slash. /index.php?page=post&s=view&id=2622005
site_file Absolute URL of the image file on the source site. http://danbooru.donmai.us/data/b7bf2146e2b5c1d73a02688e72d7001e.png
Extra fields returned when relations is set
rel_parent IBID of the parent image. Can be empty if relations begins with 1 and if there's no parent for this image. Can also be empty if there is a parent on one of the boorus but it is yet to be indexed by IbSearch. In latter case you can try determining what that image is by other means, e.g. by using sources. If relations doesn't begin with 1 then either this field or rel_child will be equal to id of this entry meaning that it's either a parent of some other image or its child. 2230604
rel_child IBID of the image that is a "child" of rel_parent. Can be empty (see rel_parent above). 11680572

Query string

IbSearch query string is the quintessense of search, supporting numerous modifiers to find exact images that you want. It blends two parts in one string: tags to search for and modifiers that work on other image properties.

If you are unsure how IbSearch recognizes your query string - use your API key's area to parse it (these keys are free, get one here).

Shortcut queries

If a query exactly corresponds to one of the patterns below it is expanded into standard modifiers. This can be used to jump to an image by its MD5 hash, search wallpapers fitting specific aspect ratio, etc.

D below stands for a single digit (0-9).

Pattern Meaning Example/Expanded
DDDDDD… Find image by its IBID (6 or 7 digits). 114013
id=114013
32 hex symbols Find image by its MD5 hash. 4873047A9E23469F270E3C1C5E26F2CB
md5=4873047A9E23469F270E3C1C5E26F2CB
40 hex symbols Find image by its SHA-1 hash. f8d69aae8c90c0078c8aacddca11f38925d50060
sha1=f8d69aae8c90c0078c8aacddca11f38925d50060
Tilde (~), then any pattern above Find similar images to the one matched by any single-match pattern of the above. Involves internal lookup of that image's IBID. ~4873047A9E23469F270E3C1C5E26F2CB
like=found_ibid
D…xD… Find images of specific dimensions. Expects only lower case x. 1600x1200
width=1600 height=1200
D…:D… Find images of specific aspect ratio (width × height). aspectw = W / H * 1000. 4:3
aspectw=1333

Tags

"Tags" are space-separated values, with spaces inside replaced with underscores (long_hair - single tag). Order of tags and their character case don't matter. By default all listed tags should be present for the image to be returned (AND mode). However, there are special constructs to tweak the behaviour.

IbSearch has a big list of tag aliases (like 1girls = 1girl) and ignores most non-word symbols (so twin_tails = twintails) to find relevant results regardless of taggers' habits.

Note: prior to 14.11.2015, tags used very different MySQL Boolean Full-Text Search format which is no more supported. Now it's more like Sphinx Extended Query Syntax.

Warning: tag search is not supported by backend:mysql.

Construct Description
tag_name & other_tag Regular match in AND mode - image must have both tags. Ampersand (&) can be omitted: tag_name other_tag.
tag_name | other_tag OR mode - image must be tagged with either tag_name or other_tag.
required ?optional Image must have required tag. Images that also have optional tag are shown first (ranked higher). Images with only optional tag and without required are not shown. A required tag must be present somewhere before optional(s): doll ?twintails ?1girl but not ?twintails ?1girl doll.
-black_tag Image must not have that tag. Example: (1girl | 1boy) -loli -trap selects 1girl or 1boy images that are neither loli nor trap.
tag_na* Truncated tag - expands to at most 16 tags that start with tag_na (e.g. tag_na, tag_name, tag_naorulous, etc.). This is identical to listing them manually (1girl | 1gilr | 1girls | ...). Prefix must be at least 3 chars long (ta* is too short).
(grouped tags) Brackets can be used to group tags into expressions for more flexible search. For example, 1girl & (wing* | tail) will select images of 1girl that have a tag starting with wing, the tail tag or both. Brackets can be nested and can contain tags in any form. Brackets are not recognized inside tags: tag(tag is just one tag while tag1 (tag2 | tag3) tag4 are 2 ungrouped and 2 grouped tags. Do not mix & and | operators in one group (this & is | wrong - this is either this & (is | correct) or (this & is) | correct).
-(grouped tags) Whole group can be blacklisted just like a single -tag.
"exact tag" Tags often contain strange symbols like brackets and colons that can be treated as something special. For example, does (:) stand for one tag or for tag : that is wrapped in grouping brackets? Does >:-* say to look for all tags starting with >:- or is it a single smiley? Tags with symbols other than a-z A-Z 0-9 _ should be always wrapped in quotes: "kurokami_(anime)" ":)" ">:-*". Or you can wrap all tags in quotes, this never hurts. Spaces inside quotes conveniently turn into underscores ("long hair" equals to "long_hair").
-"exact tag"* | stuff Quoted tags are still regular tags that support prefixes, suffixes, operators and grouping. first & "-second*"* reads as: find images with one exact tag first and with a truncated tag -second* (dash and star are parts of the name). That tag matches -second*, -second*foo, -second*$%#@, etc.
"w. "quotes" Double quotes can be part of the quoted tag's name except for ambiguous cases like this: "tag" tag" - these are two tags: tag and tag". These are fine: "tag"tag" (tag tag"tag), "tag ""tag" (tag tag ""tag), """ (tag "), "tag"" (tag tag").
(many more tags /2) So-called "quorum". Requires that at least N tags from the list are present. Compare: (many | more | tags) (match images with either of 3 tags) and (many more tags /2) (match images having many and more, or many and tags, or all 3 tags, or any other combination with at least 2 tags). Operators, prefixes, suffixes and brackets cannot be used, only plain and quoted tags are allowed as in: (many "more" tags /2). If N equals to/exceeds the number of tags, entire construct turns to AND: (many more tags /3) becomes (many & more & tags).

Example of a complex tag search (all & can be omitted):

solo* & (tagme | tag_me) & (tongue | ":D" | ":O" | ":)") & (red_eyes blue_eyes green_eyes /2) & -"x_x"

Look for images having at least one tag starting with "solo". They should also be tagged with either "tagme" or "tag_me" and with either "tongue", ":D", ":O" or ":)". They also should have at least two of the listed eye tags. They should not be tagged with "x_x".

Modifiers

Modifiers are special values that appear alongside the tags. Grouping and order don't affect them. Their format is: -modifier=value where - reverses the modifier's effect and = is that modifier's supported operator. Multiple occurrences of the same modifier are replaced with the last.

Generic types mentioned below share the same operators and value format between different modifiers.

Type Operators Value Format Description Examples
int < > <= >= : = != <> [-] modifier (op num)+ Performs numeric comparison, or multiple comparisons (in AND mode) if more than one op-num pair is given. Leading - negates the effect. : is alias to =, <> is alias to !=. op-num pair after the first can use comma to repeat the last operator: mod!=50,60,77. Special: when using comma on = the result is OR: mod=1,2,3 (matches values 1 to 3). -mod:99
mod>10<=100
mod<>1,2,3
timestamp as int as int Identical to int but each value can be either numeric (exact timestamp) or a date/time string recognized by PHP's strtotime(). Since values cannot contain spaces use underscores to replace them. mod>=1_year_ago<yesterday
-mod<1396125569
mod:2015-03-21T12:18:49
list : = [-] modifier op value (, value)* Works on the list of fixed values, excluding them from the search if starts with -. All values after the first are comma-separated: mod=val,ue. : is alias to =. -mod:val,ue
mod=value
mod=va,lu,e

List of modifiers:

Modifier Generic Type Description Example
id int * The IBID - unique image number inside IbSearch database. See what this means above. (*) Value supports k and m suffixes (1,000). id>1000<50k
width int Image width in pixels. width=1024
height int Image height in pixels. -height<200
area int * Image area in pixels - multiplication of width and height. (*) Value supports k and m suffixes (1,000) and matrix form with x X * as delimiters: area:800x600. For example, a 1900×1200 image has the area of 2280000, 2280k or 1900*1200. area>=2m
area:800x600
aspectw
aspecth
int * Relation of image dimensions to each other (details here). (*) Value supports k and m suffixes (1,000). For example, search for large portrait images with height of at least two times bigger than width: width>=1600 aspecth>=2k. aspectw>=600
aspecth<2k
aspecth:625
found timestamp When the image was first indexed by IbSearch and its IBID was created. found>yesterday
size int * Size of the image file in bytes. (*) Value supports k and m suffixes (1,024). For example, an image of 6,487,046 bytes roughly equals to 6335k or 6m. size<2000k
random Random seed for sort:random. Every search with this exact seed produces the same order of images (note: seems not to be the case now). Switches sorting to random. Value can be omitted as a simple shortcut to sort:random. (BE) Not supported by backend:mysql. random=363862847
random:
hits int * Image view counter (on IbSearch only, see here). (*) Value supports k and m suffixes (1,000). hits>=1k
like list * Finds images "similar" to given IBID(s). The more IBIDs, the more broad the similarity is. Uses tag lookup. (*) 10 values at most. May end on /N[.N] to control how many "similar" tags should match as in quorum (by default 0.5, half). (BE) Not supported by backend:mysql. like=16137
like:16137,285541/11
relevance int Obsolete. Used to specify how many tags of the tag string the image must have to be included into results. Superceded by (quorum search /N).
upload timestamp Time when the image was first uploaded across all indexed boorus. (BE) Not supported by backend:mysql. upload>=2001-07-18T11:11Z
rating list Level of image's appropriateness. Values: e q s (details here). -rating:e,?
md5 list MD5 hash of the image file data (32 hex symbols in any case). md5:4eb6...,f8a4...
sha1 list SHA-1 hash of the image file data (40 hex symbols in any case). sha1=E2F71A81...
format list Image file format. Values: png jpg gif. format:gif
server list IbSearch subdomain where the image file is stored. Values: im1 (details here). server:im1
sort list * Changes the way results are sorted before being split into pages. Values: id width height area aspectw aspecth size found hits site upload random. (*) Prefix value with - to sort from last to first (descending, on that field only). -sort form inverts the order of all fields and the meaning of each field's dash: -sort:id,-width equals to sort:-id,width. (BE) backend:mysql supports only one value and doesn't support site upload random. sort:site,-upload
-sort:found
site list * Only returns images present on the listed boorus (or not present when -site). Values are those boorus' names. (*) Each value can have a regular int expression (with k/m suffixes for 1,000) to additionally filter by image ID on that booru: -site=gelbooru<1m (omit all images on Gelbooru with ID before 1,000,000). Similar to API's sources parameter. (BE) ID filtering is not supported by backend:sphinx. site:gelbooru,danbooru>10<100
site:gelbooru:188,danbooru:202 site:gelbooru=188=189,danbooru:2
has list Images with parents and/or children. Values: child parent (combine to get both in one image). Similar to API's relations parameter. (BE) Not supported by backend:mysql. has:child
deleted list Deleted images. Values: ibsearch (images in the index), booru (images on boorus); combine to get both. (BE) Not supported by backend:sphinx. -deleted:booru
backend Forces specific search backend. Values: mysql, sphinx. The former is typically very slow, does not support tags and is only used for rare complex queries. backend:mysql
ranker Similar to sort; controls image positions in result depending on how well their tags match query tags. Values: bm25 (default), wordcount, none (fastest). Others, less useful: proximity_bm25 sph04 proximity matchany. (BE) Not supported by backend:mysql. ranker:none

Example of a complex set of modifiers (can be combined with tags):

width>=1440 aspectw>=1500 upload>2015-01-01 random: rating:s,q format:jpg

Look for safe or edgy images in JPEG format at least 1440 pixels wide and with height at least 1.5 times smaller, uploaded after 1st January 2015 (UTC). Since random is used this query will produce different results with each run.

Test your queries in the API area.

Scroll to top