> For the complete documentation index, see [llms.txt](https://cloudinary.gitbook.io/cil-hackathon-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cloudinary.gitbook.io/cil-hackathon-guide/capitol360-december-2018-hacktathon-guide/7digital/using-7digital-api.md).

# UMG Catalog / 7digital API

This guide describes how to use the 7digital API endpoints to access the UMG catalog made available for this hackathon

## Overview <a href="#overview" id="overview"></a>

**Universal Music Group have made a some of their songs available for this hackathon**

* ≈ 20,000 songs
* ≈ 1,500 unique artists
* ≈ 5,000 albums/singles
* Covers many genres, rock, pop, country....etc
* Spans each decade from 1960's to present

**7digital have activated some of their API endpoints to get access to the UMG catalog**

* Browse catalog and discover artists, albums and tracks
* Get data for artists, albums and tracks - artist name, album title, track name
* Retrieve album artwork (CD covers) for every album in the catalog
* Stream full length audio files for every song in the catalog

## API Architecture <a href="#api-architecture" id="api-architecture"></a>

![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LMw7rB6tN87JH_K_qhA%2F-LMwD1UzpvNzajWkgi6a%2F-LMwIvwUUzcirU0BfUue%2FScreen%20Shot%202018-09-21%20at%2014.26.15.png?alt=media\&token=81fbb381-48d4-42e1-b095-abfd1ba61346)

## Catalog Schema <a href="#catalog-schema" id="catalog-schema"></a>

![](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LMw7rB6tN87JH_K_qhA%2F-LMwJ5tFgIIrT6EIKcxI%2F-LMwJqfMuRaZCPrkgRcX%2FScreen%20Shot%202018-09-21%20at%2014.30.11.png?alt=media\&token=149c79a7-6abb-4b0f-a092-ae80d82e0d0e)

**​**[**List of catalog metadata can be found on this page**](https://7digital.gitbook.io/api-doc/catalog-metadata-available)**​**

## Accessing UMG Catalog using 7digital API <a href="#accessing-umg-catalog-using-7digital-api" id="accessing-umg-catalog-using-7digital-api"></a>

**Access to UMG catalog using 7digital services (API)**

* Provided through a REST style interface
* Controlled by a consumer key that needs to passed in as a parameter
* **`consumer_key = 7d4vr6cgb392`**
* Identified by a shop identifier that needs to be passed in as a parameter
* **`shopId = 2020`**

**Streaming audio files requires API requests to be signed with an oauth 1.0 signature**

* Sign requests using consumer key and secret
* **`consumer_key = 7d4vr6cgb392`**
* **`consumer_secret = m4ntskavq56rddsa`**

## Sample API Call <a href="#sample-api-call" id="sample-api-call"></a>

​<http://api.7digital.com/1.2/artist/search?shopId=2020&oauth_consumer_key=7d4vr6cgb392&q=john>​

| Call Components                     | Meaning                            |
| ----------------------------------- | ---------------------------------- |
| <http://api.7digital.com/1.2>       | 7digital API site and version      |
| artist/search                       | API endpoint name - search artists |
| ?shopId=2020                        | Parameter to identify UMG catalog  |
| \&oauth\_consumer\_key=7d4vr6cgb392 | Parameter for consumer key         |
| \&q=john                            | Parameter for search query string  |

## API Endpoint List  <a href="#api-endpoint-list" id="api-endpoint-list"></a>

The following table lists the endpoints that we have made available for this hackathon. For each endpoint there is a sample call that works and returns real results. Click on these links to see how each call is constructed and obtain the call responses

| Endpoint         | Use                                                                            | Sample Call                                                                                                                                                         | Main Parameter                                                   |
| ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Artist browse    | Browse the catalog for artist names that start with supplied text string       | ​[GET artist/browse](http://api.7digital.com/1.2/artist/browse?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&letter=ki)​                                            | letter={text}                                                    |
| Artist search    | Search the catalog for artists that match a supplied text string               | ​[GET artist/search](http://api.7digital.com/1.2/artist/search?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&q=john)​                                               | q={text}                                                         |
| Artist releases  | Returns a list of streamable releases for a specific artist                    | ​[GET artist/releases](http://api.7digital.com/1.2/artist/releases?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&artistId=1448\&usageTypes=adsupportedstreaming)​   | <p>\&artistId={int}</p><p>\&usageTypes=adsupportedstreaming</p>  |
| Artist toptracks | Returns a list of streamable tracks for a specific artist                      | ​[GET artist/toptracks](http://api.7digital.com/1.2/artist/toptracks?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&artistId=1448\&usageTypes=adsupportedstreaming)​ | <p>\&artistId={int}</p><p>\&usageTypes=adsupportedstreaming</p>  |
| Release search   | <p>Search the catalog for releases</p><p>that match a supplied text string</p> | ​[GET release/search](http://api.7digital.com/1.2/release/search?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&q=john\&usageTypes=adsupportedstreaming)​            | <p>\&q={text}</p><p>\&usageTypes=adsupportedstreaming</p>        |
| Release tracks   | Returns a list of streamable tracks for a specific release                     | ​[GET release/tracks](http://api.7digital.com/1.2/release/tracks?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&releaseId=5726299\&usageTypes=adsupportedstreaming)​ | <p>\&releaseId={int}</p><p>\&usageTypes=adsupportedstreaming</p> |
| Track search     | Search the catalog for releases that match a supplied text string              | ​[GET track/search](http://api.7digital.com/1.2/track/search?shopId=2020\&oauth_consumer_key=7d4vr6cgb392\&q=john\&usageTypes=adsupportedstreaming)​                | <p>\&q={text}</p><p>\&usageTypes=adsupportedstreaming</p>        |
| Track stream     | Stream full length (or partial clip) audio for a specific track                | **See later page**                                                                                                                                                  | \&trackId={int}                                                  |