tags – access tag database

This is part of IbSearch API v1.x.

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

Example

The tags command lets you query tag database in many versatile ways. Most obvious and basic use case is to provide search autocompletion. It's similar to constructing a SQL statement with given criteria, grouping and sorting.

If you don't pass any parameters then you will get a plain list of tags in no particular order which is only helpful if your intention is simply to get the full list.

Attention: examples below are not URL-encoded for clariness but you must not forget to encode values in your code.

Parameter Meaning Example
columns[] Can be omitted. If given, is a list of cmp criteria, usually used to aggregate result. Affects what exactly is returned. Regular tag info is always included. columns[]=MIN(v)
&columns[]=SUM(v)/#
where[] List of criteria to apply to the query like "tags longer than 5 characters". Can be omitted. Multiple items are joined with AND. where[]=length>5
&where[]=latin yes
group[] List of groupings to use like "tags that sound alike". Can be omitted. Multiple items create multiple groups (GROUP BY item1, item2). group[]=soundex
&group[]=length
order[] List of groupings to order the returned list with. Format and values are identical to group except that any item can begin with ! for descending sort. order[]=tag
&order[]=!volume
limit Number of records to retrieve (size of the page). Defaults to 25. Maximum value is 500.
page Starts from and defaults to 1.

Result

When selecting a column with any aggregate function like AVG(v) or # and no grouping then a list of single item is returned, just like with SQL.

Regardless of the query, produces an array of entries with at least the members below that describe matched tags. Some values might not be relevant depending on the used aggregate function(s).

Key Meaning Example
tag The tag name itself. Never contains spaces, uses underscores instead (_). Note that some tags can be unreasonably long. very_long_hair
volume A generic number relatively representing how many images are tagged with a tag. It's not the exact number of images. Two volumes can be compared to determine which tag has more images and by what multitude. To obtain possible bounds make an additional call to tags with MIN(v) and MAX(v) column aggregates. 10899204
searches A number indicating how often a tag has been mentioned in users' search queries, with any prefix (-tag) or suffix (tag*). 194402
category Coma-separated tag categories, sorted by category name. Empty for uncategorized tags. Known categories are: copyright (a videogame, novel, anime, etc.), artist (a person or group who produced the content). artist,copyright

Criteria

Each item is a string - criteria type optionally followed by a space and parameters. Some types (indicated below) can be immediately followed by ! to negate their match.

Meaning Explanation Example
like[!] mode expression
Tag name match mode means where expression must appear within the tag name: *. (on the right), .* (on the left), *.* (anywhere in the middle, left or right), . (must be the tag exactly), * (expression is a wildcard string itself with * meaning "any number of anything" and \* matching a star exactly). like . the_tag
like * cust*m\*expr*
like! *.* _
latin (any|no|yes)
Non/Latin tags any matches tags with any symbols (encoded as UTF-8), no - only tags that have at least one non-Latin symbol, yes - only plain alphanumeric Latin tags. latin yes
soundexof[!] tag[ tag ...]
Tags that "sound alike" Attempts to match tags that sound similar to any of the given space-separated words (like "hi" and "hey"). Only works well for alphanumeric Latin words. soundexof gun big_gun
soundex[!] code[ code ...]
Tags that "sound alike" Matches tags which SOUNDEX codes are the same as any of the given codes. Corresponds to MySQL version of SOUNDEX which differs from PHP's. Details here. soundex J404
soundex! H000 F0144
category[!] (is|has) (-|cat)
Tag category Matches the kind of thing described by a tag. A tag can of no, one or more categories. If is is used then only tags having that exact category and no others are matched. Dash (-) mean "generic/uncategorized" and only makes sense for is because any tag is already "generic" and so will always match. category! has artist
category is -
cmp lexpr (=|!|<|>) rexpr
Numeric comparison Compares two arbitrary numeric expressions. Each is a case-sensitive string consisting of digits, symbols + - * / . ( ), variables ? # l v s and functions AVG MIN MAX SUM. Variable ? is a random number between 0 and 1, # - count of rows, l - length of the tag in symbols, v - volume, s - number of searches. Spaces are ignored. When used in where and if any expression contains aggregates then the condition will be moved to HAVING. cmp MIN(s) > 1000
cmp v+1 > AVG(v)

Groupings

Any criteria can be used as a grouping and it will result in 0 for negative match and 1 for positive.

Additionally, these criteria can be used without comparing them to anything to work on their immediate value:

Grouping Explanation Example
tag The tag name itself.
soundex [length] Tag's SOUNDEX code, 4 symbols or longer. length restricts it to that length (4 is standard). soundex 4
category Tag category or categories.
cmp expr Numeric result of evaluating the expression. cmp SUM(s)/#

Examples

Attention: examples below are not URL-encoded for clariness but you must not forget to encode values in your code.

Top 10 most searched one-word tags (run)
where[] like! *.* _
order[] !cmp s
limit 10
High-volume tags that begin with a substring, similar by SOUNDEX sorted together (run)
where[] like .* rio_
order[] !cmp v/100
order[] soundex
order[] tag
Count similarly sounding Latin-only tags and their average volume, result ordered by tag name (run)
columns[] #
columns[] AVG(v)
group[] soundex 4
order[] tag

Test your queries in the API area.

Scroll to top