"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/API-advanced-search.md" between
ampache-4.4.3.tar.gz and ampache-5.0.0.tar.gz

About: Ampache is an universal web based audio/video streaming application and file manager.

API-advanced-search.md  (ampache-4.4.3):API-advanced-search.md  (ampache-5.0.0)
--- ---
title: "API 4 advanced_search" title: "API 5 advanced_search"
metaTitle: "API 4 advanced_search" metaTitle: "API 5 advanced_search"
metaDescription: "API documentation" metaDescription: "API documentation"
--- ---
Advanced search is the API method to access the search rules used in the WEB UI. 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 spl It can be confusing to process how the rules are generated so this has been spli
it into it's own page. t into it's own page.
## Using advanced_search ## Using advanced_search
Perform an advanced search given passed rules. This works in a similar way to th e web/UI search pages. Perform an advanced search given passed rules. This works in a similar way to th e web/UI search pages.
You can pass multiple rules as well as joins to create in depth search results 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 wh ich rules are combined. Rules must be sent in groups of 3 using an int (starting from 1) to designate wh ich rules are combined.
Use operator ('and'|'or') to choose whether to join or separate each rule when s earching. Use operator ('and', 'or') to choose whether to join or separate each rule when searching.
* Rule arrays must contain the following: * Rule arrays must contain the following:
* rule name (e.g. rule_1['title'], rule_2['album']) * rule name (e.g. rule_1['title'], rule_2['album'])
* rule operator (e.g. rule_1_operator[0], rule_2_operator[3]) * rule operator (e.g. rule_1_operator[0], rule_2_operator[3])
* rule input (e.g. rule_1_input['Prodigy'], rule_2_input['Land']) * rule input (e.g. rule_1_input['Prodigy'], rule_2_input['Land'])
### Available search rules ### Available search rules
Select the type of search based on the type of data you are searching for. (song s, playlists, etc) Select the type of search based on the type of data you are searching for. (song s, playlists, etc)
| rule_1 | Title | Type | Va | rule_1 | Title | Operator Type | V
lid Items | alid Items |
|-------------------|-------------------------|-------------------|:------------ |--------------------|-------------------------|-------------------|:-----------
--------------------:| ---------------------:|
| anywhere | Any searchable text | text | | anywhere | Any searchable text | text |
song | song |
| title | Title / Name | text | song,album,a | title | Title / Name | text | song,album,
rtist,playlist,label | artist,playlist,label |
| album | Album | text | so | album | Album Title | text |
ng,artist | song,artist |
| artist | Artist | text | song, | artist | Artist | text | son
album,artist | g,album,artist |
| album_artist | Album Artist | text | | album_artist | Album Artist | text |
song | song |
| composer | Composer | text | | composer | Composer | text |
song | song |
| year | Year | numeric | s | year | Year | numeric |
ong,album | song,album |
| original_year | Original Year | numeric | | original_year | Original Year | numeric |
album | album |
| yearformed | Year | numeric | | yearformed | Year | numeric |
artist | artist |
| placeformed | Place | text | | placeformed | Place | text |
artist | artist |
| release_type | Release Type | text | | release_type | Release Type | text |
album | album |
| myrating | My Rating | numeric | song, | release_status | Release Status | text |
album,artist | album |
| rating | Rating (Average) | numeric | song, | myrating | My Rating | numeric | song
album,artist | ,album,artist |
| albumrating | My Rating (Album) | numeric | | rating | Rating (Average) | numeric | song
song | ,album,artist |
| artistrating | My Rating (Artist) | numeric | s | albumrating | My Rating (Album) | numeric |
ong,album | song |
| favorite | Favorites | text | song, | artistrating | My Rating (Artist) | numeric |
album,artist | song,album |
| played_times | # Played | numeric | song, | favorite | Favorites | text | song
album,artist | ,album,artist |
| skipped_times | # Skipped | numeric | | favorite_album | Favorites (Album) | text |
song | song |
| play_skip_ratio | Played/Skipped ratio | numeric | | favorite_artist | Favorites (Artist) | text |
song | song |
| last_play | My Last Play | days | song, | played_times | # Played | numeric | song
album,artist | ,album,artist |
| played | Played | boolean | | skipped_times | # Skipped | numeric |
song | song |
| myplayed | Played by Me | boolean | song, | play_skip_ratio | Played/Skipped ratio | numeric |
album,artist | song |
| myplayedalbum | Played by Me (Album) | boolean | | last_play | My Last Play | days | song
song | ,album,artist |
| myplayedartist | Played by Me (Artist) | boolean | | played | Played | boolean |
song | song |
| time | Length (in minutes) | numeric | song, | myplayed | Played by Me | boolean | song
album,artist | ,album,artist |
| tag | Tag | tags | song, | myplayedalbum | Played by Me (Album) | boolean |
album,artist | song |
| album_tag | Album tag | tags | | myplayedartist | Played by Me (Artist) | boolean |
song | song |
| artist_tag | Artist tag | tags | | time | Length (in minutes) | numeric | song
song | ,album,artist |
| other_user | Another User | user_numeric | song, | tag | Tag | tags | song
album,artist | ,album,artist |
| other_user_album | Another User (Album) | user_numeric | | album_tag | Album tag | tags |
song | song |
| other_user_artist | Another User (Artist) | user_numeric | | artist_tag | Artist tag | tags |
song | song |
| label | Label | text | | other_user | Another User | user_numeric | song
song | ,album,artist |
| license | Music License | boolean_numeric | | other_user_album | Another User (Album) | user_numeric |
song | song |
| playlist | Playlist | boolean_numeric | | other_user_artist | Another User (Artist) | user_numeric |
song | song |
| smartplaylist | Smart Playlist | boolean_subsearch | | label | Label | text |
song | song |
| playlist_name | Playlist Name | text | | license | Music License | boolean_numeric |
song | song |
| comment | Comment | text | | playlist | Playlist | boolean_numeric |
song | song |
| lyrics | Lyrics | text | | smartplaylist | Smart Playlist | boolean_subsearch |
song | song |
| file | Filename | text | s | playlist_name | Playlist Name | text |
ong,video | song |
| bitrate | Bitrate | numeric | | comment | Comment | text |
song | song |
| added | Added | date | | lyrics | Lyrics | text |
song | song |
| updated | Updated | date | | file | Filename | text |
song | song,video |
| recent_added | Recently Added | date | | bitrate | Bitrate | numeric |
song | song |
| recent_updated | Recently Updated | date | | added | Added | date |
song | song |
| catalog | Catalog | boolean_numeric | s | updated | Updated | date |
ong,album | song |
| mbid | MusicBrainz ID | text | song, | recent_played | Recently Played | numeric_limit | song
album,artist | ,album,artist |
| mbid_album | MusicBrainz ID (Album) | text | | recent_added | Recently Added | numeric_limit |
song | song |
| mbid_artist | MusicBrainz ID (Artist) | text | | recent_updated | Recently Updated | numeric_limit |
song | song |
| metadata | Metadata | metadata (mixed) | | catalog | Catalog | boolean_numeric | song
song | ,album,artist |
| has_image | Local Image | boolean | al | mbid | MusicBrainz ID | text | song
bum,artist | ,album,artist |
| image_height | Image Height | numeric | al | mbid_album | MusicBrainz ID (Album) | text |
bum,artist | song |
| image_width | Image Width | numeric | al | mbid_artist | MusicBrainz ID (Artist) | text |
bum,artist | song |
| username | Username | text | | metadata | Metadata | metadata (mixed) |
user | song |
| category | Category | text | | has_image | Local Image | boolean | a
label | lbum,artist |
| image_height | Image Height | numeric | a
lbum,artist |
| image_width | Image Width | numeric | a
lbum,artist |
| possible_duplicate | Possible Duplicate | is_true | song
,album,artist |
| username | Username | text |
user |
| category | Category | text |
label |
### Available search operators ### Available operator values
Select your operator (integer only!) based on the type or your selected search 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, b
ut still required
| rule_1_operator | Text / Tags / Metadata | Numeric / user_numeric | Date | Boolean, Numeric, Subsearch / Days | | rule_1_operator | Text / Tags / Metadata | Numeric / user_numeric | Date | Boolean, Numeric, Subsearch / Days |
|:---------------:|-----------------------------------|------------------------- ---------------------|--------|------------------------------------| |:---------------:|-----------------------------------|------------------------- ---------------------|--------|------------------------------------|
| 0 | contains | is greater than or equal to / has loved | before | is true / before (x) days ago | | 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 | | 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 sta rs | | | | 2 | starts with | equals / has rated 4 sta rs | | |
| 3 | ends with | does not equal / has rat ed 3 stars | | | | 3 | ends with | does not equal / has rat ed 3 stars | | |
| 4 | is | is greater than / has ra ted 2 stars | | | | 4 | is | is greater than / has ra ted 2 stars | | |
| 5 | is not | is less than / has rated 1 stars | | | | 5 | is not | is less than / has rated 1 stars | | |
| 6 (Text Only) | sounds like | | | | | 6 (Text Only) | sounds like | | | |
| 7 (Text Only) | does not sound like | | | | | 7 (Text Only) | does not sound like | | | |
skipping to change at line 108 skipping to change at line 116
| 9 (Text Only) | does not match regular expression | | | | | 9 (Text Only) | does not match regular expression | | | |
Send the correct input based on the type of search. Send the correct input based on the type of search.
| rule_1_input | | rule_1_input |
|--------------| |--------------|
| text | | text |
| integer | | integer |
| boolean | | boolean |
**NOTE** To search metadata you need to add a 4th rule "rule_X_subtype" **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 s ingle list as they can be ints/strings/dates. Operators for metadata are using the text/tag types **AND** numeric types in a s ingle list as they can be ints/strings/dates.
Currently there is not a simple way to identify what metadata types you have sav ed. New methods will be created for this. Currently there is not a simple way to identify what metadata types you have sav ed. New methods will be created for this.
### Metadata operator table ### Metadata operator table
| rule_1_operator | Metadata | | rule_1_operator | Metadata |
|:---------------:|-----------------------------------| |:---------------:|-----------------------------------|
| 0 | contains | | 0 | contains |
| 1 | does not contain | | 1 | does not contain |
| 2 | starts with | | 2 | starts with |
skipping to change at line 145 skipping to change at line 153
* Search rule 1 for band containing 'Prodigy', Search Rule 2 for bbm > 120 * Search rule 1 for band containing 'Prodigy', Search Rule 2 for bbm > 120
* rule name (e.g. rule_1['metadata'], rule_2['metadata']) * rule name (e.g. rule_1['metadata'], rule_2['metadata'])
* rule operator (e.g. rule_1_operator[0], rule_2_operator[12]) * 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 input (e.g. rule_1_input['Prodigy'], rule_2_input['120'])
* rule subtype (e.g. rule_1_subtype['4'], rule_2_subtype['9']) * rule subtype (e.g. rule_1_subtype['4'], rule_2_subtype['9'])
### advanced_search parameters ### advanced_search parameters
@param array $input @param array $input
INPUTS | Input | Type | Description | Optional
* 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_o | operator | string | 'and','or' (whether to match one rule or all) | NO
perator,rule_2_input], [etc]] |
* type = (string) 'song', 'album', 'artist', 'playlist', 'label', 'user', 'v | rule_* | array | [rule_1,rule_1_operator,rule_1_input], | NO
ideo' |
* random = (integer) 0|1 (random order of results; default to 0) | rule_* | array | [rule_2,rule_2_operator,rule_2_input], [etc] | YES
* offset = (integer) |
* limit' = (integer) | type | string | 'song', 'album', 'artist', 'playlist', | NO
|
| | | 'label', 'user', 'video' |
|
| random | boolean | 0, 1 (random order of results; default to 0) | YES
|
| offset | integer | | YES
|
| limit' | integer | | YES
|
 End of changes. 8 change blocks. 
120 lines changed or deleted 133 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)