You are here: Best Practices Global Music Data (GMD) APIOnline Guide
Best Practices
General
We suggest using a URL encoding library (such as Python's Requests Library) to encode the request’s query parameters. We recommend not caching Gracenote IDs (any ID starting with GM). We encourage you to refresh data frequently to ensure that you receive the latest metadata for each endpoint.
Matching Existing Assets to Endpoints
You can enrich your existing assets with Artists, Albums, and Recordings. This can add factual metadata such as Recording Name and Artist Name, and descriptive metadata such as Artist Genre or Sonic Style.
Recordings
To match your track assets most accurately to GMD assets, we strongly recommend using the Recording Text Search endpoint initially, and querying on the following parameters:
artistNamerecordingNameisrc
**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 endpoint is not surfaced in the Recording Text Search endpoint, and if ISRC is available, we suggest a follow-up call to the Recording Lookup endpoint with the ISRC.
If an endpoint is still not returned, we suggest using the Track Lookup endpoint with the ISRC.
We strongly recommend that you re-query using the ISRC in either the Recording Lookup API or the Recording Text Search API within a few weeks’ time, especially if there has been a new release. This will help ensure that the track instance is normalized into a GMD Recording.
Following these best practices will provide users with the best opportunity to match via both string text and ISRC.
Album Editions
To facilitate the matching of your album assets with GMD Album Editions, we recommend using the Album Text Search endpoint, and querying on the following parameters:
artistNamealbumEditionNamerecordingName
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, we suggest querying on this parameter.
If you do not 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 facilitate the matching of your artist assets most accurately with GMD Artists, we strongly recommend using either the Recording Text Search endpoint or the Album Text Search endpoint, as there are additional signals to help accurately map your assets.
Recording Text Search endpoint requirements:
artistNamerecordingNameisrc(optional)
Album Text Search endpoint requirements:
artistNamealbumEditionNamerecordingName(optional)
Example: There are at least two artists named Nirvana in GMD, including the Seattle Grunge artist and the England Psychedelic Rock artist. Using the Recording Text Search or Album Text Search endpoint and including additional signals such as the recordingName (such as In Bloom), or albumEditionName (such as Nevermind) can help to get the desired Nirvana album edition.
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.
You can use the Artist Text Search endpoint to match artist assets. However, the only query parameter is artistName. For lesser-known artists with ambiguous names, the desired artist might not be as easily located. Consider using Descriptors to refine the search. See [Descriptors](key concepts and terminology.md#_heading=h.6sz4aqjsy73g).
Artist Text Search endpoint requirements:
artistName
Images
Gracenote continuously updates or adds Artist Images for the most heavily consumed Artists globally. We encourage you to refresh data frequently to ensure you have the latest images available. We recommend caching image files, but not URLs for Artist Images or Cover Art as these may change.
Artist Images
There are multiple ways of accessing Artist Images in the GMD API.
Depending on data availability, all three options may work equally well:
- If a
recordingNameis known by the desired (recording) artist, use the Recording Text Search endpoint. - If an
albumEditionNameis known by the desired (album) artist, use the Album Edition 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 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, artistName, and optionally, on isrc. Note that this assumes knowledge of the Recording for which Cover Art is desired.
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 albumEditionName 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.
Disc Numbers for display Use Cases
Track numbers (trackNumber) and disc numbers (discNumber) are now available in the GMD API. The benefit of having these two data elements in combination, as when compared with ordinal, is to discriminate against different discs and the track listing to fully represent a release as intended by the distributor.
For many historical releases with multiple discs such as Mellon Collie and the Infinite Sadness by The Smashing Pumpkins, this data is essential to have. For more recent releases, there may be instances of the release not even being released as a physical copy.
From a display use case perspective, if the discNumber of an Album Edition exceeds 1, it is suggested to display the discNumber and the corresponding disc; else, the best practice dictates to not display the discNumber.
Explore Endpoints
With the GMD API Explore endpoints you can explore GMD data like never before. These endpoints use the best of GMD metadata, such as related artist data, release type data, and popularity scores:
- By default, for Artists and Recordings, Explore endpoints will generate a set of endpoints based in descending order by Popularity Score.
- By default, for Album Editions, Explore endpoints require an
artistIDand will order the set of endpoints in descending order by Release Year. - For Recordings, when entering an
artistIDas a query parameter, a best practice should always be to include the query parameter ofincludeRelatedArtistswith the values ofmemberOfKeyArtistsandmemberOfCollaborations. This will ensure a complete set of recordings for the given artist. For example, consider the artist Prince. WithoutmemberOfKeyArtiststhe results will not include recordings such as Purple Rain and Let's Go Crazy (both attributed to Prince & the Revolution) - For Album Editions, when entering an
artistIDas a query parameter, we suggest also including the query parameter of “includeRelatedArtists” with the value ofmemberOfKeyArtists. This will ensure a complete set of album editions for the given artist.