Class | MusicBrainz::Webservice::Query |
In: |
lib/rbrainz/webservice/query.rb
|
Parent: | Object |
A simple interface to the MusicBrainz web service.
This is a facade which provides a simple interface to the MusicBrainz web service. It hides all the details like fetching data from a server, parsing the XML and creating an object tree. Using this class, you can request data by ID or search the collection of all resources (artists, labels, releases or tracks) to retrieve those matching given criteria. This document contains examples to get you started.
MusicBrainz uses absolute URIs as identifiers. For example, the artist ‘Tori Amos’ is identified using the following URI:
http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5
In some situations it is obvious from the context what type of resource an ID refers to. In these cases, abbreviated identifiers may be used, which are just the UUID part of the URI. Thus the ID above may also be written like this:
c0b2500e-0cef-4130-869d-732b23ed9df5
All methods in this class which require IDs accept both the absolute URI and the abbreviated form (aka the relative URI).
In most cases, creating a Query object is as simple as this:
require 'rbrainz' q = MusicBrainz::Webservice::Query.new
The instantiated object uses the standard Webservice class to access the MusicBrainz web service. If you want to use a different server or you have to pass user name and password because one of your queries requires authentication, you have to create the Webservice object yourself and configure it appropriately.
This example uses the MusicBrainz test server and also sets authentication data:
require 'rbrainz' service = MusicBrainz::Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'whatever', :password => 'secret' ) q = MusicBrainz::Webservice::Query.new(service)
If the MusicBrainz ID of a resource is known, then the get_artist_by_id, get_label_by_id, get_release_by_id or get_track_by_id method can be used to retrieve it.
Example:
require 'rbrainz' q = MusicBrainz::Webservice::Query.new artist = q.get_artist_by_id('c0b2500e-0cef-4130-869d-732b23ed9df5') puts artist.name puts artist.sort_name puts artist.type
produces:
Tori Amos Amos, Tori http://musicbrainz.org/ns/mmd-1.0#Person
This returned just the basic artist data, however. To get more detail about a resource, the includes parameters may be used which expect an ArtistIncludes, ReleaseIncludes, TrackIncludes or LabelIncludes object, depending on the resource type. It is also possible to use a Hash for the includes parameter where it will then get automaticly wrapped in the appropriate includes class.
To get data about a release which also includes the main artist and all tracks, for example, the following query can be used:
require 'rbrainz' q = MusicBrainz::Webservice::Query.new release_id = '33dbcf02-25b9-4a35-bdb7-729455f33ad7' release = q.get_release_by_id(release_id, :artist=>true, :tracks=>true) puts release.title puts release.artist.name puts release.tracks[0].title
produces:
Tales of a Librarian Tori Amos Precious Things
Note that the query gets more expensive for the server the more data you request, so please be nice.
For each resource type (artist, release, and track), there is one collection which contains all resources of a type. You can search these collections using the get_artists, get_releases, and get_tracks methods. The collections are huge, so you have to use filters (ArtistFilter, ReleaseFilter, TrackFilter or LabelFilter) to retrieve only resources matching given criteria. As with includes it is also possible to use a Hash as the filter where it will then get wrapped in the appropriate filter class.
For example, If you want to search the release collection for releases with a specified DiscID, you would use get_releases:
require 'rbrainz' q = MusicBrainz::Webservice::Query.new results = q.get_releases(ReleaseFilter.new(:disc_id=>discId='8jJklE258v6GofIqDIrE.c5ejBE-')) puts results[0].score puts results[0].entity.title
produces:
100 Under the Pink
The query returns a list of results in a ScoredCollection, which orders entities by score, with a higher score indicating a better match. Note that those results don‘t contain all the data about a resource. If you need more detail, you can then use the get_artist_by_id, get_label_by_id, get_release_by_id, or get_track_by_id methods to request the resource.
All filters support the limit argument to limit the number of results returned. This defaults to 25, but the server won‘t send more than 100 results to save bandwidth and processing power. In case you want to retrieve results above the 100 results limit you can use the offset argument in the filters. The offset specifies how many entries at the beginning of the collection should be skipped.
You can pass a custom Webservice object. If none is given a default webservice will be used.
If the constructor is called without arguments, an instance of WebService is used, preconfigured to use the MusicBrainz server. This should be enough for most users.
If you want to use queries which require authentication you have to pass a Webservice instance where user name and password have been set.
The client_id option is required for data submission. The format is ‘application-version‘, where application is your application‘s name and version is a version number which may not include a ’-’ character.
Available options:
Returns an artist.
The parameter includes must be an instance of ArtistIncludes or a options hash as expected by ArtistIncludes.
If no artist with that ID can be found, include contains invalid tags or there‘s a server problem, an exception is raised.
Raises: | ConnectionError, RequestError, ResourceNotFoundError, ResponseError |
Returns artists matching the given criteria.
The parameter filter must be an instance of ArtistFilter or an option hash as expected by ArtistFilter.
Raises: | ConnectionError, RequestError, ResponseError |
Returns an label.
The parameter includes must be an instance of LabelIncludes or a options hash as expected by LabelIncludes.
If no label with that ID can be found, include contains invalid tags or there‘s a server problem, and exception is raised.
Raises: | ConnectionError, RequestError, ResourceNotFoundError, ResponseError |
Returns labels matching given criteria.
The parameter filter must be an instance of LabelFilter or a options hash as expected by LabelFilter.
Raises: | ConnectionError, RequestError, ResponseError |
Returns a release.
The parameter includes must be an instance of ReleaseIncludes or a options hash as expected by ReleaseIncludes.
If no release with that ID can be found, include contains invalid tags or there‘s a server problem, an exception is raised.
Raises: | ConnectionError, RequestError, ResourceNotFoundError, ResponseError |
Returns a release group.
The parameter includes must be an instance of ReleaseGroupIncludes or a options hash as expected by ReleaseGroupIncludes.
If no release group with that ID can be found, include contains invalid tags or there‘s a server problem, an exception is raised.
Raises: | ConnectionError, RequestError, ResourceNotFoundError, ResponseError |
Returns release groups matching the given criteria.
The parameter filter must be an instance of ReleaseGroupFilter or an option hash as expected by ReleaseGroupFilter.
Raises: | ConnectionError, RequestError, ResponseError |
Returns releases matching the given criteria.
The parameter filter must be an instance of ReleaseFilter or an option hash as expected by ReleaseFilter.
Raises: | ConnectionError, RequestError, ResponseError |
Returns a track.
The parameter includes must be an instance of TrackIncludes or a options hash as expected by TrackIncludes.
If no track with that ID can be found, include contains invalid tags or there‘s a server problem, an exception is raised.
Raises: | ConnectionError, RequestError, ResourceNotFoundError, ResponseError |
Returns tracks matching the given criteria.
The parameter filter must be an instance of TrackFilter or an option hash as expected by TrackFilter.
Raises: | ConnectionError, RequestError, ResponseError |
Returns information about a MusicBrainz user.
You can only request user data if you know the user name and password for that account. If username and/or password are incorrect, an AuthenticationError is raised.
See the example in Query on how to supply user name and password.
Raises: | ConnectionError, RequestError, AuthenticationError, ResponseError |
Returns the Model::Rating a user has applied to the entity identified by mbid.
Note that this method only works if a valid user name and password have been set. Only the tags the authenticated user applied to the entity will be returned. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws) mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0') rating = query.get_user_rating(mbid)
See: | Model::Rating |
Raises: | ConnectionError, RequestError, ResponseError, AuthenticationError |
Returns a Model::Collection of tags a user has applied to the entity identified by mbid.
Note that this method only works if a valid user name and password have been set. Only the tags the authenticated user applied to the entity will be returned. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws) mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0') query.get_user_tags(mbid)
See: | Model::Tag |
Raises: | ConnectionError, RequestError, ResponseError, AuthenticationError |
Submit track to ISRC mappings.
The tracks2isrcs parameter has to be a Hash or Array with track ID/ISRC pairs. The track IDs are either instances of Model::MBID, absolute URIs or the 36 character ASCII representation. ISRCs are either instances of Model::ISRC or 12 character ASCII strings.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws, :client_id=>'My Tagging App 1.0') query.submit_isrcs([ ['7f574ec1-344c-4ae1-970d-3c757f9a717e', 'DED830049301'], ['1393122c-364c-4fb6-9a4b-17eddce90152', 'DED830049302'], ['2634965c-5299-4958-b0dc-47b166bb6898', 'DED830049303'], ['dad6b8a4-0412-4a80-9123-3e0ebddaf82d', 'DED830049304'], ['e1f7e805-33f3-4663-b294-3805b82405f9', 'DED830049305'], ['d9f932ad-de0d-44ca-bf35-ae8184f63909', 'DED830049306'], ['c983b62d-f528-433f-a402-a6317ce3d2d8', 'DED830049307'], ['9d50b06a-4136-427f-8d11-b2efb0141da6', 'DED830049308'], ['f2af3e3f-3f9f-4f8d-8b60-1d1b709aaf69', 'DED830049309'], ['059384bc-fb45-445e-ab77-950d6ccf587a', 'DED830049310'], ['2f4d7b47-a4ba-495a-b447-60b8287ed9c9', 'DED830049311'], ])
Note that this method only works if a valid user name and password have been set. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
See: | musicbrainz.org/doc/ISRC |
Raises: | ConnectionError, RequestError, AuthenticationError, InvalidISRCError |
Submit track to PUID mappings.
The tracks2puids parameter has to be a Hash or Array with track ID/PUID pairs. The track IDs are either instances of Model::MBID, absolute URIs or the 36 character ASCII representation. PUIDs are 36 characters ASCII strings.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws, :client_id=>'My Tagging App 1.0') query.submit_puids([ ['90a56b15-4259-4a33-be13-20d5513504d5', '09ff336b-79e7-1303-f613-7f1cd0d5a346'], ['90a56b15-4259-4a33-be13-20d5513504d5', '18fd245f-bc0c-3361-9d61-61a225ed8c79'], ['6d9276af-b990-41b6-ad14-de2f128437ea', '3b633298-e671-957a-1f74-83fe71969ad0'] ])
Note that this method only works if a valid user name and password have been set. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
See: | musicbrainz.org/doc/PUID |
Raises: | ConnectionError, RequestError, AuthenticationError |
Submit the user‘s rating for an entity. mbid must be an instance of Model::MBID identifying the entity which should be rated and rating is either a Model::Rating object or an integer value between 0 and 5.
Note that this method only works if a valid user name and password have been set. The tags will be applied for the authenticated user. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws) mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0') query.submit_user_rating(mbid, 5)
See: | Model::Rating |
Raises: | ConnectionError, RequestError, AuthenticationError |
Submit tags for an entity. mbid must be an instance of Model::MBID identifying the entity the tag should applied to and tags is either and array or Collection of Model::Tag objects or a string with comma separated tags.
Note that this method only works if a valid user name and password have been set. The tags will be applied for the authenticated user. If username and/or password are incorrect, an AuthenticationError is raised. See the example in Query on how to supply authentication data.
Note that all previously existing tags from the authenticated user are replaced with the ones given to this method. Other users’ tags are not affected.
Example:
ws = Webservice::Webservice.new( :host => 'test.musicbrainz.org', :username => 'outsidecontext', :password => 'secret' ) query = Webservice::Query.new(ws) mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0') query.submit_user_tags(mbid, 'doom metal, british')
See: | Model::Tag |
Raises: | ConnectionError, RequestError, AuthenticationError |