close
The Wayback Machine - https://web.archive.org/web/20140803064440/https://developer.beatsmusic.com/docs/read/search/Search

Search

You can submit keywords to our public Search API to find the following information in the Beats Music Catalog:

  • artists
  • tracks
  • albums
  • playlists
  • users
  • genres

Endpoint URL

/api/search

HTTP Method

GET

Authentication

Client ID required. See how to authenticate public resources here.

Parameters

Name Required Description Example
q required Query string for the search. dr+dre
type required The type of entity for the search.
Values: genre, artist, album, track, playlist, user

 

 artist
offset optional A zero-based integer offset into the results. Default 0. 0
limit optional Specifies the maximum number of records to retrieve. The number of results returned will be less than or equal to this value. No results are returned if it is set to zero or less. The maximum permitted value is 200. If value higher than 200 is specified, no more 200 results will be returned. Default 20. 20
filters optional

Array of streamability filter operations to be applied. Each operation is specified as filter:value.
Streamability indicates whether an entity, such as a track or album, can be streamed. Each entity can be in one of three states:

  • streamable: The entity can currently be streamed.
  • future_streamable: The entity is scheduled to be streamable sometime in the future.
  • never_streamable: The entity is not currently streamable and not scheduled to be streamable in the future.

Values:

streamable:true|false Determines whether to Include streamable entities. Default streamable:true.
future_streamable:true|false Determines whether to Include future_streamable entities. Default future_streamable:false.
never_streamable:true|false Determines whether to Include never_streamable entities. Default never_streamable:false.


Example:
filters=streamable:false&filters=future_streamable:true

 

Response Elements

ResponseDescription
code

Beats API response code. OK if successful; otherwise an error code is returned.
info

Contains paging information used to display the results.

offset

A zero-based integer offset into the results. Always matches the parameter value if it was specified.

count

The number of results returned for this request.

total

The total number of elements available for this resource.
data

List of matching search results. Each element is a search_result object:

type

The entity type of the API object

result_type

The entity type of the search result object.

id

The unique ID of the referenced item.

display

Text to be displayed when displaying a link to the item.

detail

Additional text detail describing the item.

related

Object with keys corresponding to referenced object types, and values providing the information needed for linking to the objects.
ref_type
The API object type of the referenced item.
id
The unique ID of the referenced item.
display
Text to be displayed when displaying a link to the referenced item.

 

 

Example Request

Suppose you performed a search of the Beats Music Catalog for artists whose information contains "Dr Dre". You would specify q=dr+dre for the query string, and type=artist to indicate that you would like the results to be artists.

curl -X GET "https://partner.api.beatsmusic.com/v1/api/search?
    q=dr+dre
    &type=artist
    &client_id=[YOUR_CLIENT_ID]"

Example Response

{
    data: [
    {
        type: "search_result",
        result_type: "artist",
        id: "ar8917",
        display: "Dr. Dre",
        detail: "",
        related: {
            ref_type: "artist",
            id: "ar8917",
            display: "Dr. Dre"
        }
    }
    ...
    ],
    info: {
        offset: 0,
        count: 11,
        total: 11
    },
    code: "OK"
}

version 38 as of 2 months ago by Robin

Docs Navigation