images – query image database
This is part of IbSearch API v1.x.
|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:
|sources||If set to
|relations||Enables fetching of parent/child relations. If set to
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).
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
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).
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).
|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.
|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
|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 (
|aspecth||Like aspectw but for height. A 16:10 image will have this as 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:
|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 (
|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
|rel_child||IBID of the image that is a "child" of rel_parent. Can be empty (see rel_parent above).||11680572|
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).
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 (
||Find image by its IBID (6 or 7 digits).||114013|
|32 hex symbols||Find image by its MD5 hash.||4873047A9E23469F270E3C1C5E26F2CB|
|40 hex symbols||Find image by its SHA-1 hash.||f8d69aae8c90c0078c8aacddca11f38925d50060|
||Find similar images to the one matched by any single-match pattern of the above. Involves internal lookup of that image's IBID.||~4873047A9E23469F270E3C1C5E26F2CB|
||Find images of specific dimensions. Expects only lower case
||Find images of specific aspect ratio (width × height).
"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.
Warning: tag search is not supported by backend:mysql.
|tag_name & other_tag||Regular match in AND mode - image must have both tags. Ampersand (
|tag_name | other_tag||OR mode - image must be tagged with either
|required ?optional||Image must have
|-black_tag||Image must not have that tag. Example:
|tag_na*||Truncated tag - expands to at most 16 tags that start with
|(grouped tags)||Brackets can be used to group tags into expressions for more flexible search. For example,
|-(grouped tags)||Whole group can be blacklisted just like a single
|"exact tag"||Tags often contain strange symbols like brackets and colons that can be treated as something special. For example, does
|-"exact tag"* | stuff||Quoted tags are still regular tags that support prefixes, suffixes, operators and grouping.
find images with one exact tag. That tag matches
|"w. "quotes"||Double quotes can be part of the quoted tag's name except for ambiguous cases like this:
|(many more tags /2)||So-called "quorum". Requires that at least N tags from the list are present. Compare:
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 are special values that appear alongside the tags. Grouping and order don't affect them. Their format is:
- 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.
|int||< > <= >= : = != <>||[-] modifier (op num)+||
Performs numeric comparison, or multiple comparisons (in AND mode) if more than one op-num pair is given. Leading
|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.||
|list||: =||[-] modifier op value (, value)*||
Works on the list of fixed values, excluding them from the search if starts with
List of modifiers:
|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
|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:
|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
|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
|relevance||int||Obsolete. Used to specify how many tags of the tag string the image must have to be included into results. Superceded by
|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:
|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:
|server||list||IbSearch subdomain where the image file is stored. Values:
|sort||list *||Changes the way results are sorted before being split into pages. Values:
|site||list *||Only returns images present on the listed boorus (or not present when
|has||list||Images with parents and/or children. Values:
|deleted||list||Deleted images. Values:
|backend||–||Forces specific search backend. Values:
|ranker||–||Similar to sort; controls image positions in result depending on how well their tags match query tags. Values:
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.