Skip to main content

API5.1 advanced_search

Advanced search is the API method to access the search rules used in the WEB UI. It can be confusing to process how the rules are generated so this has been split into it's own page.

Perform an advanced search given passed rules. This works in a similar way to the web/UI search pages. You can pass multiple rules as well as joins to create in depth search results

Rules must be sent in groups of 3 using an int (starting from 1) to designate which rules are combined. Use operator ('and', 'or') to choose whether to join or separate each rule when searching.

  • Rule arrays must contain the following:
    • rule name (e.g. rule_1['title'], rule_2['album'])
    • rule operator (e.g. rule_1_operator[0], rule_2_operator[3])
    • rule input (e.g. rule_1_input['Prodigy'], rule_2_input['Land'])

Available search rules

Select the type of search based on the type of data you are searching for. (songs, playlists, etc)

rule_1TitleOperator TypeValid Items
anywhereAny searchable texttextsong
titleTitle / Nametextsong, album, artist, playlist, label
albumAlbum Titletextsong, artist
artistArtisttextsong, album, artist
album_artistAlbum Artisttextsong
composerComposertextsong
yearYearnumericsong, album
original_yearOriginal Yearnumericalbum
yearformedYear Formednumericartist
placeformedPlace Formedtextartist
release_typeRelease Typetextalbum
release_statusRelease Statustextalbum
myratingMy Ratingnumericsong, album, artist
ratingRating (Average)numericsong, album, artist
albumratingMy Rating (Album)numericsong
artistratingMy Rating (Artist)numericsong, album
favoriteFavoritestextsong, album, artist
favorite_albumFavorites (Album)textsong
favorite_artistFavorites (Artist)textsong
played_times# Playednumericsong, album, artist
skipped_times# Skippednumericsong
play_skip_ratioPlayed/Skipped rationumericsong
last_playMy Last Playdayssong, album, artist
playedPlayedbooleansong
myplayedPlayed by Mebooleansong, album, artist
myplayedalbumPlayed by Me (Album)booleansong
myplayedartistPlayed by Me (Artist)booleansong
timeLength (in minutes)numericsong, album, artist
tagTagtagssong, album, artist
album_tagAlbum tagtagssong
artist_tagArtist tagtagssong
other_userAnother Useruser_numericsong, album, artist
other_user_albumAnother User (Album)user_numericsong
other_user_artistAnother User (Artist)user_numericsong
labelLabeltextsong
licenseMusic Licenseboolean_numericsong
playlistPlaylistboolean_numericsong, album
smartplaylistSmart Playlistboolean_subsearchsong
playlist_namePlaylist Nametextsong, album
commentCommenttextsong
lyricsLyricstextsong
fileFilenametextsong, video
bitrateBitratenumericsong
addedAddeddatesong
updatedUpdateddatesong
recent_playedRecently Playednumeric_limitsong, album, artist
recent_addedRecently Addednumeric_limitsong
recent_updatedRecently Updatednumeric_limitsong
catalogCatalogboolean_numericsong, album, artist
mbidMusicBrainz IDtextsong, album, artist
mbid_albumMusicBrainz ID (Album)textsong
mbid_artistMusicBrainz ID (Artist)textsong
metadataMetadatametadata (mixed)song
has_imageLocal Imagebooleanalbum, artist
image_heightImage Heightnumericalbum, artist
image_widthImage Widthnumericalbum, artist
possible_duplicatePossible Duplicateis_truesong, album, artist
usernameUsernametextuser
categoryCategorytextlabel

Available operator values

Select your operator (integer only!) based on the type or your selected search

NOTE with the numeric_limit and is_true operators the operator is ignored, but still required

rule_1_operatorText / Tags / MetadataNumeric / user_numericDateBoolean, Numeric, Subsearch / Days
0containsis greater than or equal to / has lovedbeforeis true / before (x) days ago
1does not containis less than or equal to / has rated 5 starsafteris false / after (x) days ago
2starts withequals / has rated 4 stars
3ends withdoes not equal / has rated 3 stars
4isis greater than / has rated 2 stars
5is notis less than / has rated 1 stars
6 (Text Only)sounds like
7 (Text Only)does not sound like
8 (Text Only)matches regular expression
9 (Text Only)does not match regular expression

Send the correct input based on the type of search.

rule_1_input
text
integer
boolean

NOTE To search metadata you need to add a 4th rule "rule_*_subtype" Operators for metadata are using the text/tag types AND numeric types in a single list as they can be ints/strings/dates. Currently there is not a simple way to identify what metadata types you have saved. New methods will be created for this.

Metadata operator table

rule_1_operatorMetadata
0contains
1does not contain
2starts with
3ends with
4is
5is not
6 (Text Only)sounds like
7 (Text Only)does not sound like
8 (Text Only)matches regular expression
9 (Text Only)does not match regular expression
10is greater than or equal to
11is less than or equal to
12is
13is not
14is greater than
15is less than

To search a mixed type like metadata you must search using 4 rules.

  • Search rule 1 for band containing 'Prodigy', Search Rule 2 for bbm > 120
    • rule name (e.g. rule_1['metadata'], rule_2['metadata'])
    • rule operator (e.g. rule_1_operator[0], rule_2_operator[12])
    • rule input (e.g. rule_1_input['Prodigy'], rule_2_input['120'])
    • rule subtype (e.g. rule_1_subtype['4'], rule_2_subtype['9'])

advanced_search parameters

@param array $input

InputTypeDescriptionOptional
operatorstringand, or (whether to match one rule or all)NO
rule_*array[rule_1, rule_1_operator, rule_1_input]NO
rule_*array[rule_2, rule_2_operator, rule_2_input], [etc]YES
typestringsong, album, artist, playlist, label, user, videoNO
randomboolean0, 1 (random order of results; default to 0)YES
offsetintegerYES
limit'integerYES