Skip to main content


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.

NOTE We have also condensed this page into subpages for each search type as well so you can focus on the objects you want.

Search Types

You can search for multiple object types in advanced_search.

This is passed as a type argument and will only return this object in results

advanced_search parameters

@param array $input

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, label, playlist, podcast, podcast_episode, genre, user, videoNO
randomboolean0, 1 (random order of results; default to 0)YES

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)

Searching 'anywhere' searches song title, song filename, song genre, album title, artist title, label title and song comment

rule_1TitleOperator TypeValid Types
anywhereAny searchable texttextsong
titleTitle / Nametextsong, album, artist, playlist, label, podcast, podcast_episode, genre
name(*Alias of title)
songSong Titletextsong, album, artist
song_title(*Alias of song)
albumAlbum Titletextsong, album, artist
album_title(*Alias of album)
artistArtisttextsong, album, artist
artist_title(*Alias of artist)
podcast_title(*Alias of podcast)
podcast_episodePodcast Episodetextpodcast
podcast_episode_title(*Alias of podcast_episode)
album_artistAlbum Artisttextsong, album
album_artist_title(*Alias of album_artist)
song_artistSong Artisttextsong, album
song_artist_title(*Alias of song_artist)
yearYearnumericsong, album
original_yearOriginal Yearnumericalbum
yearformedYear Formednumericartist
placeformedPlace Formedtextartist
release_typeRelease Typetextalbum
release_statusRelease Statustextalbum
catalog_numberCatalog Numbertextalbum
versionRelease Versiontextalbum
release_comment(*Alias of version)
subtitle(*Alias of version)
myratingMy Ratingnumericsong, album, artist
ratingRating (Average)numericsong, album, artist
songratingMy Rating (Song)numericalbum, artist
albumratingMy Rating (Album)numericsong, artist
artistratingMy Rating (Artist)numericsong, album
favoriteFavoritestextsong, album, artist
favorite_albumFavorites (Album)textsong
favorite_artistFavorites (Artist)textsong
played_times# Playednumericsong, album, artist, podcast, podcast_episode
skipped_times# Skippednumericsong, podcast, podcast_episode
play_skip_ratioPlayed/Skipped rationumericsong, podcast, podcast_episode
last_playMy Last Playdayssong, album, artist, podcast, podcast_episode
last_play_or_skipMy Last Play OR skipdayssong, album, artist, podcast, podcast_episode
playedPlayedbooleansong, album, artist, podcast, podcast_episode
myplayedPlayed by Mebooleansong, album, artist, podcast, podcast_episode
myplayedalbumPlayed by Me (Album)booleansong
myplayedartistPlayed by Me (Artist)booleansong, album
album_countAlbum Countnumericartist
song_countSong Countnumericalbum, artist
timeLength (in minutes)numericsong, album, artist, podcast, podcast_episode
genreGenretagssong, album, artist
tag(*Alias of genre)
song_genreSong Genretagssong, album, artist
song_tag(*Alias of song_genre)
album_genreAlbum Genretagssong, album
album_tag(*Alias of album_genre)
artist_genreArtist Genretagssong, artist
artist_tag(*Alias of artist_genre)
no_genreNo Genreis_truesong, album, artist
no_tag(*Alias of no_genre)
other_userAnother Useruser_numericsong, album, artist
other_user_albumAnother User (Album)user_numericsong
other_user_artistAnother User (Artist)user_numericsong
licenseMusic Licenseboolean_numericsong
playlistPlaylistboolean_numericsong, album, artist
smartplaylistSmart Playlistboolean_subsearchsong, album
playlist_namePlaylist Nametextsong, album, artist
typePlaylist Type (private, public)boolean_numericplaylist
fileFilenametextsong, album, artist, video, podcast, podcast_episode
stateFile state (completed, pending skipped)boolean_numericpodcast, podcast_episode
status(*Alias of state)
addedAddeddatesong, podcast, podcast_episode
pubdatePublication Datedatepodcast, podcast_episode
recent_playedRecently Playednumeric_limitsong, album, artist
recent_addedRecently Addednumeric_limitsong, album
recent_updatedRecently Updatednumeric_limitsong
catalogCatalogboolean_numericsong, album, artist
mbidMusicBrainz IDtextsong, album, artist
mbid_albumMusicBrainz ID (Album)textsong, album, artist
mbid_artistMusicBrainz ID (Artist)textsong, album, artist
mbid_songMusicBrainz ID (Song)textsong, album, artist
metadataMetadatametadata (mixed)song
has_imageLocal Imagebooleanalbum, artist
image_heightImage Heightnumericalbum, artist
image_widthImage Widthnumericalbum, artist
possible_duplicatePossible Duplicateis_truesong, album, artist
possible_duplicate_albumPossible Duplicate Albumsis_truesong, album, artist
categoryCategorytextlabel, genre

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 / tagsnumeric / user_numericdateboolean, boolean_numeric, boolean_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.


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

1does not contain
2starts with
3ends with
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
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'])

Example URLs

Here are some example calls that might help you get an idea of the URL required to create an advanced search.