Skip to main content

advanced_search 4.2

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_1TitleTypeValid Items
anywhereAny searchable texttextsong
titleTitle / Nametextsong, album, artist, playlist, label
artistArtisttextsong, album
yearYearnumericsong, album
original_yearOriginal Yearnumericalbum
yearformedYear Formednumericartist
placeformedPlace Formedtextartist
release_typeRelease Typetextalbum
myratingMy Ratingnumericsong, album, artist
ratingRating (Average)numericsong, album, artist
albumratingMy Rating (Album)numericsong
artistratingMy Rating (Artist)numericsong, album
favoriteFavoritestextsong, album, artist
played_times# Playednumericsong, album, artist
last_playMy Last Playdayssong, album, artist
myplayedPlayed by Mebooleansong
myplayedalbumPlayed by Me (Album)booleansong
myplayedartistPlayed by Me (Artist)booleansong
timeLength (in minutes)numericsong, album
tagTagtagssong, album, artist
album_tagAlbum tagtagssong
artist_tagArtist tagtagssong
other_userAnother Useruser_numericsong, album, artist
other_user_albumAnother Useruser_numericsong
other_user_artistAnother Useruser_numericsong
licenseMusic Licenseboolean_numericsong
smartplaylistSmart Playlistboolean_subsearchsong
playlist_namePlaylist Nametextsong
fileFilenametextsong, video
recent_addedRecently Addeddatesong
recent_updatedRecently Updateddatesong
catalogCatalogboolean_numericsong, album
metadataMetadatametadata (mixed)song
has_imageLocal Imagebooleanalbum, artist
image_heightImage Heightnumericalbum, artist
image_widthImage Widthnumericalbum, artist

Available search operators

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

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.


NOTE To search metadata you need to add a 4th rule "rule_X_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'])

advanced_search parameters

@param array $input

* ampache_url = (string)
* ampache_API = (string)
* operator = (string) 'and'|'or' (whether to match one rule or all)
* rules = (array) = [[`rule_1`, `rule_1_operator`, `rule_1_input`], [`rule_2`, `rule_2_operator`, `rule_2_input`], [etc]]
* type = (string) `song`, `album`, `artist`, `playlist`, `label`, `user`, `video`
* random = (integer) `0`, `1` (random order of results; default to 0)
* offset = (integer)
* limit' = (integer)