After a few months of development, the new release of OneMusicAPI is now released! There's a whole bunch of additional features in the new version including general release metadata, disc queries and vastly improved coverage for Acoustid fingerprint and MusicBrainz disc ID queries. OneMusicAPI also now supports FreeDB queries for discs!

First things first: to use the new version you'll have to use a new endpoint. As part of our promise to existing customers the one existing version of OneMusicAPI will not be disabled and will continue to function as before. To use the new version you'll have to use the new endpoint:

http://api.onemusicapi.com/20130307/...

Some actual examples are below...

General release metadata

For queries that return information about releases, we've now added further metadata including year, genre and track information. Here's an example query:

http://api.onemusicapi.com/20130307/release?title=Play&artist=Moby

Remember you'll need to add your user_key (signup here!). And the results...

[
  {
    "title": "Play",
    "artist": "Moby",
    "year": "1999",
    "genre": "Electronica",
    "media": [
      
    ],
    "images": [
      
    ],
    "score": 1
  },
  {
    "title": "Play",
    "artist": "Moby",
    "year": "1999",
    "genre": "Electronic",
    "media": [
      {
        "tracks": [
          {
            "title": "Honey",
            "number": "1",
            "artist": ""
          },
          {
            "title": "Find My Baby",
            "number": "2",
            "artist": ""
          },
          {
            "title": "Porcelain",
            "number": "3",
            "artist": ""
          }
          ...
        ]
      }
    ]
  },
  ...
]   

A couple of goodies to notice here... First, "inc=images" is no longer mandatory. You can omit it if you don't want cover art.

Next, you can see a lot more metadata than before. Titles, artists, year, genre and track information are all included.

Disc queries

There's now a new /disc endpoint added to the API to support writers of CD-oriented software and hardware. Why's that? Well, in the case of multi disc releases, CD oriented products need to be mindful of which disc they are displaying information about.

OneMusicAPI now offers a /disc endpoint which accepts any number of Acoustid fingerprints, MusicBrainz disc IDs and FreeDB disc IDs. Here's an example query, just with a MusicBrainz disc ID:

http://api.onemusicapi.com/20130307/disc?musicBrainzDiscId=0tffAN0PLpn1Lc4yM7uoeOajAGM-

This is a query for the second CD of 4hero's Two Pages. The results (much abridged)...

{
  "disc_match": {
    "position": "2",
    "tracks": [
      {
        "title": "We Who Are Not as Others",
        "number": "1",
        "artist": "4hero"
      },
      {
        "title": "Humans",
        "number": "2",
        "artist": "4hero"
      },
      {
        "title": "In the Shadows",
        "number": "3",
        "artist": "4hero"
      },
      ...
    ]
  },
  "associated_releases": [
    {
      "title": "Two Pages",
      "artist": "4hero",
      "year": "1998",
      "genre": "broken beat",
      "media": [
        {
          "position": "1",
          "tracks": [
            {
              "title": "Loveless (feat. Ursula Rucker)",
              "number": "1",
              "artist": "4hero,Ursula Rucker"
            },
            {
              "title": "Golden Age of Life",
              "number": "2",
              "artist": "4hero"
            },
            {
              "title": "Planeteria (A Theme From a Dream)",
              "number": "3",
              "artist": "4hero"
            },
            ...
          ]
        },
        {
          "position": "2",
          "tracks": [
            {
              "title": "We Who Are Not as Others",
              "number": "1",
              "artist": "4hero"
            },
            {
              "title": "Humans",
              "number": "2",
              "artist": "4hero"
            },
            {
              "title": "In the Shadows",
              "number": "3",
              "artist": "4hero"
            },            
            ...
          ]
        }
      ]
    }
    ...
  ]
}

The latter associated_releases object contains all release information that could be found in the same way the existing release endpoint does. It's the former disc_match object which is important to CD oriented products. This shows the information just for the CD that was sent in the query, identified in this example by the MusicBrainz Disc ID. You can also see that while just the information for the second disc is present in disc_match, associated_releases also contains information for the first disc should you need it.

There's also a special feature available to disc queries... aggregated. If set to "first" then OneMusicAPI creates an extra object at the start of the response containing the first occurence of each field found in all of the results. This is really useful if you just want to interrogate one object:

http://api.onemusicapi.com/20130307/disc?musicBrainzDiscId=0tffAN0PLpn1Lc4yM7uoeOajAGM-&aggregated=first&inc=images

Here are the results:

{
  "aggregated": {
    "title": "Two Pages",
    "artist": "4hero",
    "year": "1998",
    "genre": "broken beat",
    "image": "http://api.discogs.com/image/R-9937-1143266804.jpeg",
    "tracks": [
      {
        "title": "We Who Are Not as Others",
        "number": "1",
        "artist": "4hero"
      },
      {
        "title": "Humans",
        "number": "2",
        "artist": "4hero"
      },
      {
        "title": "In the Shadows",
        "number": "3",
        "artist": "4hero"
      },
      ...
    ]
  },
  "disc_match": {
    "position": "2",
    "tracks": [
      {
        "title": "We Who Are Not as Others",
        "number": "1",
        "artist": "4hero"
      },
      {
        "title": "Humans",
        "number": "2",
        "artist": "4hero"
      },
      {
        "title": "In the Shadows",
        "number": "3",
        "artist": "4hero"
      },
      ...
    ]
  },
  "associated_releases": [
    ...
  ]
}

Notice how all information, including cover art, year and genre, are included in that first result along with the correct track listing for that disc. Handy!

Better coverage

In the previous version of the API, results for Acoustid fingerprints and MusicBrainz Disc IDs weren't as successful as simple tag based title queries. The reason was two-fold. First, only MusicBrainz was interrogated for those queries, so the possible set of matches was decreased. Second, and more importantly, cover art was the only data returned and MusicBrainz only has around 10% of its releases containing cover art sourced from the Cover Art Archive (at the time of writing).

The queries that OneMusicAPI sends have now been shuffled so that the queries work together. If, for example, the barcode of a release is found on MusicBrainz, that barcode is then used to query Discogs. This means the data sources for OneMusicAPI work together a lot better and return many more results.


That's enough for now. To give OneMusicAPI a try all you need to do is sign up and you'll get 1000 free queries. Further queries can be purchased on a rolling monthly basis or as a credit top-up. When you do sign up, use the new reference documentation that has been released.

comments powered by Disqus
© 2017 elsten software limited, Unit 4934, PO Box 6945, London, W1A 6US, UK | terms and conditions | privacy policy