Advanced Search
API 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.
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
- song
- album
- album_disk (NOTE API8 only; earlier versions have no album disk formatter and return an empty result)
- artist
- song_artist (NOTE same rules as artist but only returns song artists)
- album_artist (NOTE same rules as artist but only returns album artists)
- label
- playlist
- podcast
- podcast_episode
- genre
- tag (*Alias of genre)
- user
- video
advanced_search parameters
@param array $input
| Input | Type | Description | Optional |
|---|---|---|---|
| operator | string | and, 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 |
| rule_*_group | integer | Group id for this rule, to combine it with other rules sharing the id (see "Grouping rules" below) | YES |
| group_*_operator | string | and, or (operator joining the rules assigned to that group id) | YES |
| type | string | song (default), album, album_disk, artist, album_artist, song_artist, label, playlist, podcast, podcast_episode, genre, tag, user, video | YES |
| random | boolean | 0, 1 (random order of results; default to 0) | YES |
| offset | integer | YES | |
| limit' | integer | YES |
Using advanced_search
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
| Base Rules | Title | Operator Type | Valid Types |
|---|---|---|---|
| anywhere | Any searchable text | text | song |
| none | Empty / No rule search | is_true | song |
| title | Title / Name | text | song, album, artist, label, playlist, podcast, podcast_episode, genre |
| name | (*Alias of title) | ||
| song | Song Title | text | song, album, artist |
| song_title | (*Alias of song) | ||
| album | Album Title | text | song, album, artist |
| album_title | (*Alias of album) | ||
| artist | Artist | text | song, album, artist |
| artist_title | (*Alias of artist) | ||
| podcast | Podcast | text | podcast_episode |
| podcast_title | (*Alias of podcast) | ||
| podcast_episode | Podcast Episode | text | podcast |
| podcast_episode_title | (*Alias of podcast_episode) | ||
| album_artist | Album Artist | text | song, album |
| album_artist_title | (*Alias of album_artist) | ||
| song_artist | Song Artist | text | song, album |
| song_artist_title | (*Alias of song_artist) | ||
| composer | Composer | text | song |
| track | Track | numeric | song |
| year | Year | numeric | song, album |
| original_year | Original Year | numeric | album |
| username | Username | text | user |
| summary | Summary | text | artist |
| yearformed | Year Formed | numeric | artist |
| placeformed | Place Formed | text | artist |
| release_type | Release Type | text | album |
| release_status | Release Status | text | album |
| barcode | Barcode | text | album |
| catalog_number | Catalog Number | text | album |
| version | Release Version | text | album |
| release_comment | (*Alias of version) | ||
| subtitle | (*Alias of version) | ||
| album_count | Album Count | numeric | artist, genre |
| artist_count | Artist Count | numeric | genre |
| song_count | Song Count | numeric | album, artist, genre |
| disk_count | Disk Count | numeric | album |
| episode_count | Episode Count | numeric | podcasts |
| time | Length (in minutes) | numeric | song, album, artist, podcast, podcast_episode |
| bpm | BPM | numeric | song |
| label | Label | text | song |
| comment | Comment | text | song |
| lyrics | Lyrics | text | song |
| type | Playlist Type (private, public) | boolean_numeric | playlist |
| state | File state (completed, pending skipped) | boolean_numeric | podcast, podcast_episode |
| status | (*Alias of state) | ||
| category | Category | text | label |
| Rating Rules | Title | Operator Type | Valid Types |
|---|---|---|---|
| myrating | My Rating | numeric | song, album, artist, podcast, podcast_episode |
| rating | Rating (Average) | numeric | song, album, artist, podcast, podcast_episode |
| albumrating | My Rating (Album) | numeric | song, artist |
| artistrating | My Rating (Artist) | numeric | song, album |
| songrating | My Rating (Song) | numeric | album, artist |
| my_flagged_song | My Favorite Songs | boolean | song, album, artist |
| my_flagged_album | My Favorite Albums | boolean | song, album, artist |
| my_flagged_artist | My Favorite Artists | boolean | song, album, artist |
| favorite | Favorites | text | song, album, artist, podcast, podcast_episode |
| favorite_album | Favorites (Album) | text | song |
| favorite_artist | Favorites (Artist) | text | song |
| other_user | Another User | user_numeric | song, album, artist, podcast, podcast_episode |
| other_user_album | Another User (Album) | user_numeric | song |
| other_user_artist | Another User (Artist) | user_numeric | song |
| Play History | Title | Operator Type | Valid Types |
|---|---|---|---|
| played_times | # Played | numeric | song, album, artist, podcast, podcast_episode |
| skipped_times | # Skipped | numeric | song, album, artist, podcast, podcast_episode |
| played_or_skipped_times | # Skipped | numeric | song, album, artist, podcast, podcast_episode |
| play_skip_ratio | Played/Skipped ratio | numeric | song |
| last_play | My Last Play | days | song, album, artist, podcast, podcast_episode |
| last_skip | My Last Skip | days | song, album, artist, podcast, podcast_episode |
| last_play_or_skip | My Last Play OR skip | days | song, album, artist, podcast, podcast_episode |
| last_play_song | My Last Play (Song) | days | album, artist |
| last_skip_song | My Last Skip (Song) | days | album, artist |
| last_play_or_skip_song | My Last Play OR skip (Song) | days | album, artist |
| last_play_album | My Last Play (Album) | days | song, album, artist |
| last_skip_album | My Last Skip (Album) | days | song, album, artist |
| last_play_or_skip_album | My Last Play OR skip (Album) | days | song, album, artist |
| last_play_artist | My Last Play (Artist) | days | song, album, artist |
| last_skip_artist | My Last Skip (Artist) | days | song, album, artist |
| last_play_or_skip_artist | My Last Play OR skip (Artist) | days | song, album, artist |
| played | Played | boolean | song, album, artist, podcast, podcast_episode |
| myplayed | Played by Me | boolean | song, album, artist, podcast, podcast_episode |
| myplayedalbum | Played by Me (Album) | boolean | song |
| myplayedartist | Played by Me (Artist) | boolean | song, album |
| myplayed_times | # Played by Me | numeric | song, album, artist, podcast, podcast_episode |
| myskipped_times | # Skipped by Me | numeric | song, album, artist, podcast, podcast_episode |
| myplayed_or_skipped_times | # Played or Skipped by Me | numeric | song, album, artist, podcast, podcast_episode |
| recent_played | Recently Played | numeric_limit | song, album, artist |
| Genre Rules | Title | Operator Type | Valid Types |
|---|---|---|---|
| genre | Genre | tags | song, album, artist |
| tag | (*Alias of genre) | ||
| album_genre | Album Genre | tags | song, album |
| album_tag | (*Alias of album_genre) | ||
| artist_genre | Artist Genre | tags | song, artist |
| artist_tag | (*Alias of artist_genre) | ||
| song_genre | Song Genre | tags | song, album, artist |
| song_tag | (*Alias of song_genre) | ||
| no_genre | No Genre | is_true | song, album, artist |
| no_tag | (*Alias of no_genre) | ||
| genre_count_song | Genres with a count of Songs | numeric | song, album, artist |
| genre_count_album | Genres with a count of Albums | numeric | song, album, artist |
| genre_count_artist | Genres with a count of Artists | numeric | song, album, artist |
| Playlist Rules | Title | Operator Type | Valid Types |
|---|---|---|---|
| playlist | Playlist | boolean_subsearch | song, album, artist |
| smartplaylist | Smart Playlist | boolean_subsearch | song, album |
| playlist_name | Playlist Name | text | song, album, artist |
| File Data | Title | Operator Type | Valid Types |
|---|---|---|---|
| file | Filename | text | song, album, artist, video, podcast, podcast_episode |
| bitrate | Bitrate | numeric | song |
| added | Added | date | song, album, podcast, podcast_episode |
| updated | Updated | date | song, album, podcast, podcast_episode |
| pubdate | Publication Date | date | podcast, podcast_episode |
| license | Music License | boolean_numeric | song |
| no_license | No License | is_true | song |
| recent_added | Recently Added | numeric_limit | song, album |
| recent_updated | Recently Updated | numeric_limit | song |
| days_added | Added | days | song, album, artist, podcast, podcast_episode |
| days_updated | Updated | days | song, podcast, podcast_episode |
| possible_duplicate | Possible Duplicate | is_true | song, album, artist |
| duplicate_tracks | Duplicate Album Tracks | is_true | song, album |
| duplicate_mbid_group | Duplicate MusicBrainz Release Group | is_true | album |
| possible_duplicate_album | Possible Duplicate Albums | is_true | song, album, artist |
| orphaned_album | Orphaned Album | is_true | song |
| catalog | Catalog | boolean_numeric | song, album, artist |
| has_image | Local Image | boolean | album, artist |
| image_height | Image Height | numeric | album, artist |
| image_width | Image Width | numeric | album, artist |
| metadata | Metadata | metadata (mixed) | song |
| waveform | Song has a saved waveform | boolean | song |
| Musicbrainz | Title | Operator Type | Valid Types |
|---|---|---|---|
| mbid | MusicBrainz ID | text | song, album, artist |
| mbid_album | MusicBrainz ID (Album) | text | song, album, artist |
| mbid_artist | MusicBrainz ID (Artist) | text | song, album, artist |
| mbid_song | MusicBrainz ID (Song) | text | song, album, artist |
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_operator | text / tags | numeric / user_numeric | date | boolean, boolean_numeric, boolean_subsearch | days |
|---|---|---|---|---|---|
| 0 | contains | is greater than or equal to / has loved | before | is true | before (x) days ago |
| 1 | does not contain | is less than or equal to / has rated 5 stars | after | is false | after (x) days ago |
| 2 | starts with | equals / has rated 4 stars | is not before (x) days ago | ||
| 3 | ends with | does not equal / has rated 3 stars | is not after (x) days ago | ||
| 4 | is | is greater than / has rated 2 stars | |||
| 5 | is not | is 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_operator | Metadata |
|---|---|
| 0 | contains |
| 1 | does not contain |
| 2 | starts with |
| 3 | ends with |
| 4 | is |
| 5 | is 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 |
| 10 | is greater than or equal to |
| 11 | is less than or equal to |
| 12 | is |
| 13 | is not |
| 14 | is greater than |
| 15 | is 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'])
Grouping rules (Ampache 8.3.0+)
A rule may optionally carry rule_<n>_group (an int) to bucket it with every other rule sharing
that id into one group, combined by its own group_<id>_operator (and/or) instead of the
top-level operator. This is exactly two levels -- a group id cannot contain another group -- and
every rule with no rule_<n>_group stays at the top level exactly as before, joined by operator
same as always.
Not the same thing as search_group/SearchGroupMethod (GET /search/{search_type}/groups),
which is a named bundle of object types to search across (all, music, song_artist, ...) --
an unrelated, pre-existing meaning of "group". The grouping described here only ever groups the
rules of one advanced_search call.
For example, to find songs titled "Rock" OR "Metal", that are also by an artist named "Deep" --
i.e. (title = Rock OR title = Metal) AND artist contains Deep -- put rules 1 and 2 in group 1
with an or operator, and leave rule 3 ungrouped at the top level with the default and:
action=advanced_search&operator=and&type=song
&rule_1=title&rule_1_operator=4&rule_1_input=Rock&rule_1_group=1
&rule_2=title&rule_2_operator=4&rule_2_input=Metal&rule_2_group=1
&group_1_operator=or
&rule_3=artist&rule_3_operator=0&rule_3_input=Deep
Example URLs
Here are some example calls that might help you get an idea of the URL required to create an advanced search.
Artist https://music.com.au/server/xml.server.php?action=advanced_search&auth=eeb9f1b6056246a7d563f479f518bb34&operator=or&type=artist&offset=0&limit=4&random=0&rule_1=favorite&rule_1_operator=0&rule_1_input=%25&rule_2=artist&rule_2_operator=2&rule_2_input=Car
Album https://music.com.au/server/xml.server.php?action=advanced_search&auth=eeb9f1b6056246a7d563f479f518bb34&operator=or&type=album&offset=0&limit=4&random=0&rule_1=favorite&rule_1_operator=0&rule_1_input=%25&rule_2=artist&rule_2_operator=0&rule_2_input=Men
Song https://music.com.au/server/xml.server.php?action=advanced_search&auth=eeb9f1b6056246a7d563f479f518bb34&operator=or&type=song&offset=0&limit=4&random=0&rule_1=favorite&rule_1_operator=0&rule_1_input=%25&rule_2=title&rule_2_operator=2&rule_2_input=Dance