API Methods.5. Search Methods

API Methods.5.1. search/artist
API Methods.5.2. search/track
API Methods.5.3. search/release

API Methods.5.1. search/artist

Description

Search is performed by artists represented on the site by at least one release, own compilation, remix, single, or live. If artists appear only in soundtracks or various artists compilations they will not appear in the search results.

Endpoint

http://api.mp3caprice.com/1.0/search/artist/{pageSize}/{pageNumber}

Method Parameters

pageSize

positive integer value; specifies the result page size to be returned. Maximum allowed value is 200.

pageNumber

positive integer value; specifies the results page number to be returned.

Allowed HTTP GET Parameters

q

case insensitive and Url encoded artist search string. Should contain name of artist or group you wish to find. Optional.

Result Structure

Table API Methods.11. Artists search result structure

Attribute Type Required Details
totalResults integer yes The total number of found artists.
searchQuery String no The artists query string.
searchResults Paginator yes Paginated artist search results.

or Error

Result sorting order

If parameter q is defined search results will be ordered by:

  • Score - DESC . Most relevant search results are shown on the top of the list.

If parameter q is missing or an empty string the results will be ordered by:

  • Date - DESC . The date they were added to the catalog, i.e. last added artists will be shown on the top.

Features

Aggressive stemming filter is applied, i.e. the following two queries will return the same result:

http://api.mp3caprice.com/1.0/search/artist/10/1.json?q=madonna
http://api.mp3caprice.com/1.0/search/artist/10/1.json?q=madonnas

A predefined list of synonyms is applied, e.g. S.O.D and Stormtroopers Of Death. Search by ANY of these names will return results.

Stop words: the, buy, download, purchase, various, artists, albums, info, va, music, mp3, genre, genres, series

Method Example

Example API Methods.18. Search artists

http://api.mp3caprice.com/1.0/search/artist/10/1.xml?q=madonna&api_key={API Key}&sub_account={sub_account}
                  

<apiResponse>
  <totalResults>1</totalResults>
  <searchQuery>madonna</searchQuery>
  <searchResults>
    <pageNumber>1</pageNumber>
    <pageSize>10</pageSize>
    <pageCount>1</pageCount>
    <pageItems>
      <item xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="artist">
        <artistId>15</artistId>
        <artistName>Madonna</artistName>
        <releasesCount>85</releasesCount>
        <tracksCount>549</tracksCount>
        <artistUrl>http://mp3caprice.com/artist/madonna-15?pid=P_00109
        </artistUrl>
        <artistLargeCoverUrl>http://cvr.mp3caprice.com/covers/artists/000/015/230.jpg
        </artistLargeCoverUrl>
        <artistSmallCoverUrl>http://cvr.mp3caprice.com/covers/artists/000/015/90.jpg
        </artistSmallCoverUrl>
      </item>
    </pageItems>
  </searchResults>
</apiResponse>
[Note]

To get artist search results in json format use url like

http://api.mp3caprice.com/1.0/search/artist/10/1.json?q=madonna&api_key={API Key}&sub_account={sub_account}
                  

API Methods.5.2. search/track

Description

Search is performed by a composite index, which takes into account names of artist and tracks. It gathers facet information on the found results and sorts it by the found artists. Facet result is the list of pairs of values: artist – number of found results.

Endpoint

http://api.mp3caprice.com/1.0/search/track/{pageSize}/{pageNumber}

Method Parameters

pageSize

positive integer value; specifies the result page size to be returned. Maximum allowed value is 200.

pageNumber

positive integer value; specifies the results page number to be returned.

Allowed HTTP GET Parameters

q

case insensitive and Url encoded artist search string. Can contain names of tracks and artists. Optional.

Example:

http://api.mp3caprice.com/1.0/search/track/10/1.json?q=eminem+Soldier

af

integer positive value, contains artist id filter. By specifying this parameter you will be able to search for tracks of a certain artist. Optional.

Example:

http://api.mp3caprice.com/1.0/search/track/10/1.json?q=love&af=1

Looks for all tracks of the group Aerosmith(id=1) with the word love in the title.

f

boolean, enable/disable artist faceting information. Disabled by default. Optional.

Example:

http://api.mp3caprice.com/1.0/search/track/10/1.json?q=love&f=true

fm

the maximum number of facets to be included in search results. Max allowed value is 100. Set to 10 by default. Optional.

Result Structure

Table API Methods.12. Tracks search result structure

Attribute Type Required Details
totalResults integer yes The total number of found tracks.
searchQuery String no The tracks query string.
searchResults Paginator yes Paginated track search results.
artistFacets List no Contains artist facets.

or Error

Result sorting order

If parameter q is defined search results will be ordered by:

  • Score - DESC . Most relevant search results are shown on the top of the list.

If parameter q is missing or an empty string the results will be ordered by:

  • Date - DESC . The date they were added to the catalog, i.e. last added artists will be shown on the top.

Features

Aggressive stemming filter is applied, i.e. the following two queries will return the same result:

http://api.mp3caprice.com/1.0/search/track/10/1.json?q=love
http://api.mp3caprice.com/1.0/search/track/10/1.json?q=loves

A predefined list of synonyms is applied, e.g. S.O.D and Stormtroopers Of Death. Search by ANY of these names will return results.

Stop words: the, buy, download, purchase, various, artists, albums, info, va, music, mp3, genre, genres, series

Method Example

Example API Methods.19. Search tracks

http://api.mp3caprice.com/1.0/search/track/10/1.xml?q=love&api_key={API Key}&sub_account={sub_account}
                  

<apiResponse>
  <totalResults>16422</totalResults>
  <searchQuery>love</searchQuery>
  <searchResults>
    <pageNumber>1</pageNumber>
    <pageSize>10</pageSize>
    <pageCount>1643</pageCount>
    <pageItems>
      <item xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="track">
        <releaseId>696</releaseId>
        <artistId>248</artistId>
        <artistName>James Blunt</artistName>
        <trackName>Love Love Love</trackName>
        <trackPosition>11</trackPosition>
        <discNumber>0</discNumber>
        <trackPrice>0.12</trackPrice>
        <trackLength>231</trackLength>
        <trackSize>7407117</trackSize>
        <trackBitrate>256</trackBitrate>
        <trackPreview>http://prv.mp3caprice.com/preview/000/834/0-32.mp3
        </trackPreview>
      </item>
      ...
    </pageItems>
  </searchResults>
</apiResponse>
[Note]

To get track search results in json format use url like

http://api.mp3caprice.com/1.0/search/track/10/1.json?q=love&api_key={API Key}&sub_account={sub_account}
                  

API Methods.5.3. search/release

Description

Search is performed by a composite index, which takes into account names of artists, names of releases, genres, series, languages, as well as years of release. It gathers facet information on the found results and sorts it by genres and series.

This search supports various additional filters that may be used to narrow the search results. These filters will allow you to retrieve releases based on the specified parameters.

Example: “You wish to find all compilations belonging to the genre pop released from 2000 through 2009 and added to the catalog during the last two weeks; you also want the results to be sorted in the order they were added to the catalog.” – by using the filters you will build the following query:

http://api.mp3caprice.com/1.0/search/release/10/1?tf=VA_Compilation&yf=2009*2010&df=2011-11-07*2011-11-21&s=-date&gf=10&api_key={API Key}&sub_account={sub_account}
               

Endpoint

http://api.mp3caprice.com/1.0/search/release/{pageSize}/{pageNumber}

Method Parameters

pageSize

positive integer value; specifies the result page size to be returned. Maximum allowed value is 200.

pageNumber

positive integer value; specifies the results page number to be returned.

Allowed HTTP GET Parameters

q

Case insensitive and Url encoded search string. Can contain names of releases, names of artists, genres, series, languages, as well as years of release. Optional.

gf

filter by the genres. Comma separated or single integer positive value(s). Filters the result by the specified genres using the Boolean OR operator. Optional.

Validation Regex: [1-9]+\\d*(,[1-9]+\\d*)*

Examples: gf=1,101,123; gf=3;

http://api.mp3caprice.com/1.0/search/release/10/1.json?gf=1,2

sf

filter by the series. Сomma separated or single integer positive value(s). Filters the result by the specified series using the Boolean OR operator. Optional.

Validation Regex: [1-9]+\\d*(,[1-9]+\\d*)*

Examples: sf=12,15; sf=11;

http://api.mp3caprice.com/1.0/search/release/10/1.json?sf=34,35

tf

filter by the release type. Filters the result by the specified release types using the Boolean OR operator. Allowed values are: Album, Artist_Compilation, VA_Compilation, Live, Remix, Single, Soundtrack. Optional.

Examples: tf=Album; tf=Single,Remix;

http://api.mp3caprice.com/1.0/search/release/10/1.json?tf=Album,Live,Remix

yf

filter by the year of release. Can contain a closed year range, a specific year or an open year range. Optional.

Validation Regex: (?:\\*())?([1][9]\\d{2}|20\\d{2})(?:(?!\\1)\\*([1][9]\\d{2}|20\\d{2})?|)

Possible Values:

yf=*yyyy

all albums released before the year yyyy inclusive

yf=yyyy

all albums released in the year yyyy

yf=yyyy*

all albums released from the year yyyy inclusive

yf=yyyy1*yyyy2

all albums released during the period from yyyy1 to yyyy2 inclusive

Examples: yf=2009*2010

http://api.mp3caprice.com/1.0/search/release/10/1.json?yf=2009*2010

– find all releases released from 2009 to 2010 inclusive.

df

filter by the date releases were added to the catalog. Can contain a closed date range, a specific day, or an open date range. Optional.

Validation Regex: (?:\\*())?([0-9]{4}-(((0[13578]|(10|12))-(0[1-9]|[1-2][0-9]|3[0-1]))|(02-(0[1-9]|[1-2][0-9]))|((0[469]|11)-(0[1-9]|[1-2][0-9]|30)))) (?:(?!\\1)\\* ([0-9]{4}-(((0[13578]|(10|12))-(0[1-9]|[1-2][0-9]|3[0-1]))|(02-(0[1-9]|[1-2][0-9]))|((0[469]|11)-(0[1-9]|[1-2][0-9]|30))))?|)

Possible Values:

df=*date

all albums added to the catalog before the date inclusive

df=date

all albums added to the catalog on the date

df= date*

all albums added to the catalog after the date inclusive

df= date1*date2

all albums added to the catalog during the period from date1 to date2 inclusive

date has format yyyy-MM-dd, where yyyy - year, MM-month(1-12), dd – day

Examples: df=2011-11-01*

http://api.mp3caprice.com/1.0/search/release/10/1.json?df=2011-11-01*

– find all releases added to the catalog starting from November 1, 2011.

s

You can specify the additional fields to sort the results by. In the current version the search results can be sorted by the date release was added to the catalog (date) and by the release year (year). Optional.

Validation Regex: ((\\-|\\*)[a-zA-Z]+)+

Examples:

*year

sort by release year (Asc)

-year

sort by release year (Desc)

-year*date

sort first by release year (Desc) and then by the date releases were added to the catalog (Asc).

http://api.mp3caprice.com/1.0/search/release/10/1.json?s=*year

– find all releases and sort the results by albums release year.

[Tip]

If the search string is not empty (parameter q) the search results will be sorted by relevance. You can use this parameter to set up additional sorting. I.e if two albums have identical score they can be sorted using this parameter.

Also remember that the order in which you specify additional fields for sorting is important since for instance *year-date and –date*year will display the search results in absolutely different order.

f

boolean, enable/disable faceting information. Disabled by default. Optional.

fm

the maximum number of facets to be included in search results. Max allowed value is 100. Set to 10 by default. Optional.

Result Structure

Table API Methods.13. Releases search result structure

Attribute Type Required Details
totalResults integer yes The total number of found releases.
searchQuery String no The artist query string.
searchResults Paginator yes Paginated releases search results.
genreFacets List no Contains genre facets.
seriesFacets List no Contains series facets.

or Error

Result sorting order

Search results will be ordered by:

  • Score - DESC . Most relevant search results are shown on the top of the list.

If parameter q is missing or an empty string and parameter s is not specified the results will be ordered by:

  • Date - DESC . The date release was added to the catalog (desc) and by the release year (desc).

Features

Aggressive stemming filter is applied, i.e. the following two queries will return the same result:

http://api.mp3caprice.com/1.0/search/release/10/1.json?q=Pop+Party&tf=VA_Compilation
http://api.mp3caprice.com/1.0/search/release/10/1.json?q=Pop+Parties&tf=VA_Compilation

A predefined list of synonyms is applied, e.g. S.O.D and Stormtroopers Of Death. Search by ANY of these names will return results.

Stop words: the, buy, download, purchase, various, artists, albums, info, va, music, mp3, genre, genres, series

Method Example

Example API Methods.20. Search releases

http://api.mp3caprice.com/1.0/search/release/10/1.xml?tf=VA_Compilation&yf=2009*2010&df=*2011-11-21&s=-date&gf=10&api_key={API Key}&sub_account={sub_account}
                  

<apiResponse>
  <totalResults>30</totalResults>
  <searchResults>
    <pageNumber>1</pageNumber>
    <pageSize>10</pageSize>
    <pageCount>3</pageCount>
    <pageItems>
      <item xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="release">
        <releaseId>25378</releaseId>
        <releaseName>Pop Party 8</releaseName>
        <artistId>-1</artistId>
        <artistName>Various Artists</artistName>
        <releaseType>VA_Compilation</releaseType>
        <releaseSource>CD</releaseSource>
        <releaseLanguage>English</releaseLanguage>
        <releaseYear>2010</releaseYear>
        <tracksCount>23</tracksCount>
        <totalSize>194038671</totalSize>
        <totalPrice>2.76</totalPrice>
        <addedDate>2011-05-29</addedDate>
        <releaseUrl>http://mp3caprice.com/release/pop-party-8-25378?pid=P_00109</releaseUrl>
        <releaseLargeCoverUrl>http://cvr.mp3caprice.com/covers/albums/025/378/230.jpg</releaseLargeCoverUrl>
        <releaseSmallCoverUrl>http://cvr.mp3caprice.com/covers/albums/025/378/90.jpg</releaseSmallCoverUrl>
      </item>
      ...
    </pageItems>
  </searchResults>
</apiResponse>
[Note]

To get release search results in json format use url like

http://api.mp3caprice.com/1.0/search/release/10/1.json?tf=VA_Compilation&yf=2009*2010&df=*2011-11-21&s=-date&gf=10&api_key={API Key}&sub_account={sub_account}