GMD API v2

Best Practices

We recommend the following best practices.

Headlines

We suggest using a URL encoding library to encode the request’s query parameters. For example, Python's Requests Library. We recommend to not cache Gracenote IDs (any ID starting with ‘GN’), and encourage you to refresh data frequently to ensure you get the latest metadata for each object.

Matching a customer’s existing assets to GMD objects

One of the Use Cases for the GMD Lookup API is to enrich a customer’s existing Artist, Album, and Track assets with GMD’s Artist, Album, and Recording assets, in the form of factual metadata such as Recording Name and Artist Name, and descriptive metadata such as Artist Genre or Sonic Style.

Recordings

To most accurately facilitate the matching of track assets to GMD assets, we strongly recommend using the ‘Recording Text Search’ endpoint initially, and querying on the following parameters:

• artistName
• recordingName
• isrc

Note: isrc is an optional parameter, but highly recommended, if available.

The ‘Recording Text Search’ endpoint utilizes a hybrid search based on both isrc and strings. If the desired isrc is not available in GMD, the algorithm will resort to a text search.

If an object is not surfaced in the Recording Text Search endpoint, and if isrc is available, Gracenote suggests a follow up call to the ‘Recording Lookup’ endpoint.

If an object is still not returned, and if isrc is available, Gracenote suggests leveraging the ‘Sonic Descriptor’ endpoint.

It is important to note that Sonic Descriptors in the Sonic Descriptor API are un-normalized, and the factual metadata should be used for validation purposes only. Therefore, it is strongly recommended that customers re-query on the isrc in either the Recording Lookup API, or the Recording Text Search API within a few week’s time, to receive back a set of normalized Sonic Descriptors for the track.

If the track has made its way into GMD, the track will be normalized into a GMD Recording and will have referential integrity to other GMD objects such as Artists.

Following these best practices will provide users with the best opportunity to match via both string text and isrc.

Albums

To facilitate the matching of a customer’s album assets with GMD Albums, Gracenote recommends using the ‘Album Text Search’ endpoint, and querying on the following parameters:

• artistName
• albumName
• recordingName

recordingName is an optional parameter; however, if your requirement as a developer is for accuracy - for example, a Deluxe Edition of an Album Master, for the exact track configuration, Gracenote would suggest querying on this parameter.

If you don’t require an exact match to the track configuration, say, for a Cover Art Use Case, then consider recordingName as a ‘nice to have’, but not a hard requirement.

Artists

To most accurately facilitate the matching of a customer’s artist assets with GMD Artists, Gracenote strongly recommends leveraging either the ‘Recording Text Search’ endpoint or the ‘Album Text Search’ endpoint.

Recording Text Search endpoint requirements:

• artistName
• recordingName
• isrc (optional)

Album Text Search endpoint requirements:

• artistName
• albumName
• recordingName (optional)

Gracenote suggests using either the Recording Text Search endpoint or the Album Text Search endpoint, as there are additional signals to help accurately map your assets.

Example: There are at least two artists named Nirvana in GMD, including the Seattle Grunge artist and the England Psychedelic Rock artist. Leveraging the Recording Text Search or Album Text Search endpoint and including additional signals such as the recordingName (such as In Bloom), isrc, or albumName (such as Nevermind) can help to surface the desired Nirvana.

Note that ‘artistName’ in the Recording Text Search endpoint refers to the name of the Recording Artist, and ‘artistName’ in the Album Text Search endpoint refers to either the name of the Album Artist or the name of the Track Artist.

The Artist Text Search endpoint can also be leveraged to match artist assets, but note that the only query parameter is artistName, and for lesser-known artists with ambiguous names, the desired artist might not be surfaced. For less ambiguous artists, such as Animal Collective, it would be appropriate to only leverage the Recording Text Search endpoint.

Rich Media

As discussed previously, Gracenote encourages customers to refresh data frequently. With respect to Rich Media, Gracenote’s Rich Media team continuously works to update, or add Artist Images for the most heavily consumed Artists globally, and in that respect, the expectation is that there will be changes to images between Exports.

Gracenote recommends caching assets, but not caching the Image URL, be it, for Artist Images or Cover Art.

Artist Images

There are multiple ways of accessing Artist Images in the GMD Lookup API.

Depending on data availability, all three options may work equally well:

• If a recordingName is known by the desired (recording) artist, use the ‘Recording Text Search’ endpoint.
• If an albumName is known by the desired (album) artist, use the ‘Album Text Search’ endpoint.
• If the artist desired has a less ambiguous name, use the ‘Artist Text Search’ endpoint.

Cover Art

As with Artist Images, there are multiple ways of accessing Cover Art in the GMD Lookup API.

Unlike Artist Images, the methodology to surface the Cover Art which you desire depends on the Use Case.

• If a single, algorithmically assigned Cover Art is desired for a given Recording, leverage the ‘Recording Text Search’ endpoint, and query on the recordingName and artistName. Note that this assumes knowledge of the Recording for which Cover Art is desired for.
  • Example: I know the Recording is ‘Penny Lane’, and I want one representative Cover Art from the set of track instances which have been normalized into a Recording.
• If a specific Cover Art from an Album is desired, leverage the ‘Album Text Search’ endpoint, and query on albumName and artistName.
  • If a specific Cover Art from an Album is desired, along with the factual metadata such as trackCount and releaseYear, suggest also querying on recordingName, as there may be certain additional tracks in one release, which are not available in another.