# Usage

In general you need to set a useragent for your application, start searches to get to know corresponding MusicBrainz IDs and then retrieve information about these entities.

The data is returned in form of a `dict`.

If you also want to submit data, then you must authenticate as a MusicBrainz user.

This part of the documentation will give you usage examples. For an overview of available functions you can have a look at the API.

## Identification

To access the MusicBrainz webservice through this library, you need to identify your application by setting the useragent header made in HTTP requests to one that is unique to your application.

To ease this, the convenience function `musicbrainzngs.set_useragent()` is provided which automatically sets the useragent based on information about the application name, version and contact information to the format recommended by MusicBrainz.

If a request is made without setting the useragent beforehand, a `musicbrainzngs.UsageError` will be raised.

## Authentication

Certain calls to the webservice require user authentication prior to the call itself. The affected functions state this requirement in their documentation. The user and password used for authentication are the same as for the MusicBrainz website itself and can be set with the `musicbrainzngs.auth()` method. After calling this function, the credentials will be saved and automaticall used by all functions requiring them.

If a method requiring authentication is called without authenticating, a `musicbrainzngs.UsageError` will be raised.

If the credentials provided are wrong and the server returns a status code of 401, a `musicbrainzngs.AuthenticationError` will be raised.

## Getting Data

### Regular MusicBrainz Data

You can get MusicBrainz entities as a `dict` when retrieving them with some form of identifier. An example using `musicbrainzngs.get_artist_by_id()`:

    artist_id = "c5c2ea1c-4bde-4f4d-bd0b-47b200bf99d6"
    try:
        result = musicbrainzngs.get_artist_by_id(artist_id)
    except WebServiceError as exc:
        print("Something went wrong with the request: %s" % exc)
    else:
        artist = result["artist"]
        print("name:\t\t%s" % artist["name"])
        print("sort name:\t%s" % artist["sort-name"])

You can get more information about entities connected to the artist with adding includes and you filter releases and release_groups:

    result = musicbrainzngs.get_artist_by_id(artist_id,
                  includes=["release-groups"], release_type=["album", "ep"])
    for release_group in result["artist"]["release-group-list"]:
        print("{title} ({type})".format(title=release_group["title"],
                                        type=release_group["type"]))

Tip

Compilations are also of primary type “album”. You have to filter these out manually if you don’t want them.

Note

You can only get at most 25 release groups using this method. If you want to fetch all release groups you will have to browse.

### Cover Art Data

This library includes a few methods to access data from the Cover Art Archive which has a documented API.

Both `musicbrainzngs.get_image_list()` and `musicbrainzngs.get_release_group_image_list()` return the deserialized cover art listing for a release or release group. To find out whether a release has an approved front image, you could use the following example code:

    release_id = "46a48e90-819b-4bed-81fa-5ca8aa33fbf3"
    data = musicbrainzngs.get_cover_art_list("46a48e90-819b-4bed-81fa-5ca8aa33fbf3")
    for image in data["images"]:
        if "Front" in image["types"] and image["approved"]:
            print "%s is an approved front image!" % image["thumbnails"]["large"]
            break

To retrieve an image itself, use `musicbrainzngs.get_image()`. A few convenience functions like `musicbrainzngs.get_image_front()` are provided to allow easy access to often requested images.

Warning

There is no upper bound for the size of images uploaded to the Cover Art Archive and downloading an image will return the binary data in memory. Consider using the `tempfile` module or similar techniques to save images to disk as soon as possible.

## Searching

When you don’t know the MusicBrainz IDs yet, you have to start a search. Using `musicbrainzngs.search_artists()`:

    result = musicbrainzngs.search_artists(artist="xx", type="group",
                                           country="GB")
    for artist in result['artist-list']:
        print(u"{id}: {name}".format(id=artist['id'], name=artist["name"]))

Tip

Musicbrainzngs returns unicode strings. It’s up to you to make sure Python (2) doesn’t try to convert these to ascii again. In the example we force a unicode literal for print. Python 3 works without fixes like these.

You can also use the query without specifying the search fields:

    musicbrainzngs.search_release_groups("the clash london calling")

The query and the search fields can also be used at the same time.

## Browsing

When you want to fetch a list of entities greater than 25, you have to use one of the browse functions. Not only can you specify a limit as high as 100, but you can also specify an offset to get the complete list in multiple requests.

An example would be using `musicbrainzngs.browse_release_groups()` to get all releases for a label:

    label = "71247f6b-fd24-4a56-89a2-23512f006f0c"
    limit = 100
    offset = 0
    releases = []
    page = 1
    print("fetching page number %d.." % page)
    result = musicbrainzngs.browse_releases(label=label, includes=["labels"],
                    release_type=["album"], limit=limit)
    page_releases = result['release-list']
    releases += page_releases
    # release-count is only available starting with musicbrainzngs 0.5
    if "release-count" in result:
            count = result['release-count']
            print("")
    while len(page_releases) >= limit:
        offset += limit
        page += 1
        print("fetching page number %d.." % page)
        result = musicbrainzngs.browse_releases(label=label, includes=["labels"],
                            release_type=["album"], limit=limit, offset=offset)
        page_releases = result['release-list']
        releases += page_releases
    print("")
    for release in releases:
        for label_info in release['label-info-list']:
            catnum = label_info.get('catalog-number')
            if label_info['label']['id'] == label and catnum:
                print("{catnum:>17}: {date:10} {title}".format(catnum=catnum,
                            date=release['date'], title=release['title']))
    print("\n%d releases on  %d pages" % (len(releases), page))

Tip

You should always try to filter in the query, when possible, rather than fetching everything and filtering afterwards. This will make your application faster since web service requests are throttled. In the example we filter by release_type.

## Submitting

You can also submit data using musicbrainzngs. Please use `musicbrainzngs.set_hostname()` to set the host to test.musicbrainz.org when testing the submission part of your application.

Authentication is necessary to submit any data to MusicBrainz.

An example using `musicbrainzngs.submit_barcodes()` looks like this:

    musicbrainzngs.set_hostname("test.musicbrainz.org")
    musicbrainzngs.auth("test", "mb")

    barcodes = {
        "174a5513-73d1-3c9d-a316-3c1c179e35f8": "5099749534728",
        "838952af-600d-3f51-84d5-941d15880400": "602517737280"
    }
    musicbrainzngs.submit_barcodes(barcodes)

See Submitting in the API for other possibilites.

## More Examples

You can find some examples for using musicbrainzngs in the examples directory.