Tuned Global

Tuned Global Documentation Home

This API provides READ access to public information about artists, albums, playlists, stations, tags and more.

Tuned Global Metadata aAPIs 

Authentication

API Key Authentication

Basic HTTP Authentication

HMAC Authentication

Catalogue

Release

LiveVideo

Author

Content Control

Podcast

Track

Song

AudioBook

Artist

Album

Grouped Catalogue

Station

ShadowQueue

Playlist

Content Pages and Carousel

Page

Content

Settings

Group

Search

Advanced song search. Multiple input parameters supported. If your service has custom tag groups included, these can be exposed via this search end point

AdvancedSongSearch

To test api connection. Use for monitoring search

TestConnection

TagSearch

GetTrendingTerms. This will return trending artist searches

GetTrendingTerms

UserSearch

Search for videos. Note these are Video on Demand, not Live Video, separate call is available for Live Video

VideoSearch

AuthorSearch

Search for channels. Search for channels (podcasts) only

ChannelSearch

Search for episodes. Search for podcast episodes only

EpisodeSearch

PlaylistSearch

Search for live video channels. A channel is the header to the live video shows

LiveShowSearch

LiveChannelSearch

Search for songs.
             <strong>Note:</strong> This search API is not STRICT on song title only, it does include an Artists Name as part of the search algorithm. 
             If you are requiring a STRICT search on title, use AdvancedSongSearch, with input only on title.

SongSearch

AlbumSearch

ArtistSearch

StationSearch

Search across the catalogue. Returns all available categories, eg. Songs, Stations, Playlists, Video etc. 
             V2.2 Playlist response only System or Verified Users’s Public Playlists.
             Updated playlist response in V2.3. Supports user public playlists with new param <type> Valid inputs this parameter:</type><para>System</para><para>Verified</para><para>User</para><para>Defaults to return playlists which are either System or Verified (created by verified users) if no type is passed.</para>

Search for songs via matching. Pass various parameters to enable a song to be matched to the catalogue.  Eg, ISRC, Duration, Artist etc.

SongSearchMatching

Search third party catalogue, meaning NOT the Tuned catalogue (if applicable)

ThirdPartyCatalogueStatus

AudioBookSearch

Search for audiobook authors

AudioBookChapterSearch

GetByName

GetMultipleByName

GetArtistsByTag

Retrieve podcast channel that have been assigned to this tag

GetPodcastChannelByTag

GetAlbumsByTag

GetStationsByTag

Retrieve Audiobooks that have been assigned to this tag

GetAudiobooksByTag

GetAlbumsByTagGroups

GetArtistsByTagGroups

GetTagsByTagType

GetPlaylistsByTag

GetPlaylistsByTags

User

Get User Public Profile by user Id. <strong>Note:</strong> A user must have their allow public as active

GetProfileById

Retrieve a list of profiles (ids) the given public user is following.

GetFollowing

Get User Public Profile by username. <strong>Note:</strong> A user must have their allow public as active

GetProfileByUsername

Check if email exists in third party systems. <strong> Note: </strong> This API is only available if 3rd party authentication systems are used and this feature is available.  
            It is not available by default.

ExternalEmailExists

Image Engine

Default

Metadata

<p class="slate-p" placeholder="Type / for widgets">Tuned Global Advanced APIs (aAPIs) consist of a group of Metadata, Services and Authentication APIs.</p><p class="slate-p" placeholder="Type / for widgets">These Metadata APIs are used where user context is not required, the Services APIs are where user context is required.  This means that the security models are different between Metadata and Services APIs.</p><p class="slate-p" placeholder="Type / for widgets"></p><div  data-type="error" style="background-color:#FFF1F1;color:#ff3030"><div ><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M9.08366 9.9801C9.25033 9.9801 9.39269 9.92107 9.51074 9.80302C9.6288 9.68496 9.68783 9.53566 9.68783 9.3551V5.31344C9.68783 5.14677 9.62533 5.00441 9.50033 4.88635C9.37533 4.7683 9.22949 4.70927 9.06283 4.70927C8.88227 4.70927 8.73296 4.7683 8.61491 4.88635C8.49685 5.00441 8.43783 5.15371 8.43783 5.33427V9.37594C8.43783 9.5426 8.50033 9.68496 8.62533 9.80302C8.75033 9.92107 8.9031 9.9801 9.08366 9.9801ZM9.00033 13.1676C9.19477 13.1676 9.35796 13.1016 9.48991 12.9697C9.62185 12.8377 9.68783 12.6745 9.68783 12.4801C9.68783 12.2857 9.62185 12.1225 9.48991 11.9905C9.35796 11.8586 9.19477 11.7926 9.00033 11.7926C8.80588 11.7926 8.64269 11.8586 8.51074 11.9905C8.3788 12.1225 8.31283 12.2857 8.31283 12.4801C8.31283 12.6745 8.3788 12.8377 8.51074 12.9697C8.64269 13.1016 8.80588 13.1676 9.00033 13.1676ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C10.9448 16.0843 12.6114 15.3898 14.0003 14.0009C15.3892 12.612 16.0837 10.9454 16.0837 9.00094C16.0837 7.05649 15.3892 5.38982 14.0003 4.00094C12.6114 2.61205 10.9448 1.9176 9.00033 1.9176C7.05588 1.9176 5.38921 2.61205 4.00033 4.00094C2.61144 5.38982 1.91699 7.05649 1.91699 9.00094C1.91699 10.9454 2.61144 12.612 4.00033 14.0009C5.38921 15.3898 7.05588 16.0843 9.00033 16.0843Z" fill="#E90005"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">Unless explicitly stated in either your direct licensor agreements or your Tuned Global agreements, Tuned Global content, being either the assets or metadata, cannot be used to train Machine Learning or AI models.</p></div></div><h3 class="slate-h3">Usage</h3><p class="slate-p" placeholder="Type / for widgets">The Metadata APIs provided READ access to public information about artists, albums, playlists, stations, videos, podcasts, tags and more.  This group of APIs provides the ability to search your catalogue.</p><p class="slate-p" placeholder="Type / for widgets">General usage of the APIs would be as follows;</p><ol class="slate-ol"><li class="slate-li"><div style="position:relative">Understand the security models assigned to different APIs. Refer to the Authentication Section for more information.</div></li><li class="slate-li"><div style="position:relative">If you are initially building a general access view, where user context is not required, use these metadata APIs as the recommended first step in development</div></li><li class="slate-li"><div style="position:relative">Use the Services APIs to access contextual information, usually involving the catalogue and the user</div></li><li class="slate-li"><div style="position:relative">If you need access to alternate environments, these will need to be added to your MSA (Development)</div></li></ol><h3 class="slate-h3">Use Cases</h3><p class="slate-p" placeholder="Type / for widgets">The suite of Advanced APIs provide a wide range of tools to get the output you are looking for in regards to your project.  Our team and systems are used in many different use cases, ranging from traditional streaming, metadata usage, background music services, airlines, gaming and web3 experiences to name a few.  Contact our team with you specific use case if you are unsure and we will provide details of the APIs that will provide the results you are looking for.</p><h3 class="slate-h3">CMS - AutoTune</h3><p class="slate-p" placeholder="Type / for widgets">There are many of the metadata APIs that provide output that you have defined via the AutoTuned CMS.  Instructions on AutoTune CMS are not part of this API documentation but are available via credentials you have been provided.  If unsure, please check with Tuned Support team for more information.or.</p><h3 class="slate-h3">Images</h3><p class="slate-p" placeholder="Type / for widgets">A important note is in regards to Images.  Images are generally provided at the highest resolution available within the URL responses.  This is for Artist Images, Album Images and Artwork (such as playlist images).  You will not want to use this URL as it is usually too large, bit also not right sized for your interfaces.</p><p class="slate-p" placeholder="Type / for widgets">Tuned Global makes an image engine available for both sizing the image required and also applying a number of effects.  This is detailed in <a href="https://app.theneo.io/tuned-global/metadata/image-engine" target="_self">Image Engine</a></p><p class="slate-p" placeholder="Type / for widgets"></p>

Tuned Global Advanced APIs (aAPIs) consist of a group of Metadata, Services and Authentication APIs.

These Metadata APIs are used where user context is not required, the Services APIs are where user context is required.  This means that the security models are different between Metadata and Services APIs.

The Metadata APIs provided READ access to public information about artists, albums, playlists, stations, videos, podcasts, tags and more.  This group of APIs provides the ability to search your catalogue.

General usage of the APIs would be as follows;

The suite of Advanced APIs provide a wide range of tools to get the output you are looking for in regards to your project.  Our team and systems are used in many different use cases, ranging from traditional streaming, metadata usage, background music services, airlines, gaming and web3 experiences to name a few.  Contact our team with you specific use case if you are unsure and we will provide details of the APIs that will provide the results you are looking for.

There are many of the metadata APIs that provide output that you have defined via the AutoTuned CMS.  Instructions on AutoTune CMS are not part of this API documentation but are available via credentials you have been provided.  If unsure, please check with Tuned Support team for more information.or.

A important note is in regards to Images.  Images are generally provided at the highest resolution available within the URL responses.  This is for Artist Images, Album Images and Artwork (such as playlist images).  You will not want to use this URL as it is usually too large, bit also not right sized for your interfaces.

Tuned Global makes an image engine available for both sizing the image required and also applying a number of effects.  This is detailed in 

<p class="slate-p" placeholder="Type / for widgets">This method involves including a unique API key with each request under a special http header called “StoreId”. Tuned Global will provide the API key once your details are registered in our system. 
Since this model only requires an API Key in the header, it does not deliver sensitive information and is used to request catalogue metadata i.e. search, images etc.</p><p class="slate-p" placeholder="Type / for widgets"></p><h2 class="slate-h2"><span style="color:#666666" class="slate-color">Examples</span></h2><p class="slate-p" placeholder="Type / for widgets">Following are the usage examples from the curl and postman. </p><pre class="slate-CodeBlockElement slate-code_block"><div contenteditable="false"><div ><span aria-live="polite" aria-atomic="false" aria-relevant="additions text" ></span><div ><div ><div >Select...</div><div ><div  style="display:inline-block"><input type="text" autoCapitalize="none" autoComplete="off" autoCorrect="off" id="react-select-4-input" spellcheck="false" tabindex="0" value="" aria-autocomplete="list" style="box-sizing:content-box;width:1px;label:input;background:0;border:0;font-size:inherit;opacity:1;outline:0;padding:0;color:inherit"/><div style="position:absolute;top:0;left:0;visibility:hidden;height:0;overflow:scroll;white-space:pre"></div></div></div></div><div ><span ></span><div  aria-hidden="true"><svg height="20" width="20" viewBox="0 0 20 20" aria-hidden="true" focusable="false" ><path d="M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z"></path></svg></div></div></div></div></div><code class="language-shell keep-markup drop-tokens"><div class="slate-code_line">curl -X GET --header &quot;Accept: application/json&quot; --header &quot;StoreId: TESTAPIKEY&quot; &quot;https://api-delivery-connect.tunedglobal.com/api/v5/search/master/songs?filter.name=hello</div></code></pre><p class="slate-p" placeholder="Type / for widgets"></p><div style="text-align:left"> <img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/49a31285-e206-442f-93f4-8c0bc9935768.jpg" alt=""/></div><p class="slate-p" placeholder="Type / for widgets"></p>

This method involves including a unique API key with each request under a special http header called “StoreId”. Tuned Global will provide the API key once your details are registered in our system. 
Since this model only requires an API Key in the header, it does not deliver sensitive information and is used to request catalogue metadata i.e. search, images etc.

Following are the usage examples from the curl and postman. 

200 - OK

The request was unacceptable, often due to missing a required parameter.

400 - Bad request

401 - Unauthorized

The parameters were valid but the request failed.

402 - Request Failed

The API key doesnt have permissions to perform the request.

403 - Forbidden

404 - Not Found

<p class="slate-p" placeholder="Type / for widgets">This relates to the play log end points as noted in the documentation. The logging endpoints are only applicable where Tuned Global is responsible for generating reports on the behalf of a client. If a client is managing their reports internally, then the endpoint (and basic http auth) isn&apos;t required.</p><p class="slate-p" placeholder="Type / for widgets"> This model uses a simple challenge and response mechanism with which a server can request authentication information (Username and password) from a client. </p><p class="slate-p" placeholder="Type / for widgets">The client passes the authentication information to the server in an Authorization header e.g. Authorization: Basic &lt;credentials&gt;, where &lt;credentials&gt; is the Base64 encoding of Username and password joined by a single colon;</p><p class="slate-p" placeholder="Type / for widgets">Note: Please include the API Key under the ‘StoreId: TestKey’ http header with Basic HTTP Authentication. </p><h2 class="slate-h2"><span style="color:#999999" class="slate-color">Examples</span></h2><p class="slate-p" placeholder="Type / for widgets">Following are the usage examples from the curl and postman.</p><pre class="slate-CodeBlockElement slate-code_block"><div contenteditable="false"><div ><span aria-live="polite" aria-atomic="false" aria-relevant="additions text" ></span><div ><div ><div >Select...</div><div ><div  style="display:inline-block"><input type="text" autoCapitalize="none" autoComplete="off" autoCorrect="off" id="react-select-51-input" spellcheck="false" tabindex="0" value="" aria-autocomplete="list" style="box-sizing:content-box;width:1px;label:input;background:0;border:0;font-size:inherit;opacity:1;outline:0;padding:0;color:inherit"/><div style="position:absolute;top:0;left:0;visibility:hidden;height:0;overflow:scroll;white-space:pre"></div></div></div></div><div ><span ></span><div  aria-hidden="true"><svg height="20" width="20" viewBox="0 0 20 20" aria-hidden="true" focusable="false" ><path d="M4.516 7.548c0.436-0.446 1.043-0.481 1.576 0l3.908 3.747 3.908-3.747c0.533-0.481 1.141-0.446 1.574 0 0.436 0.445 0.408 1.197 0 1.615-0.406 0.418-4.695 4.502-4.695 4.502-0.217 0.223-0.502 0.335-0.787 0.335s-0.57-0.112-0.789-0.335c0 0-4.287-4.084-4.695-4.502s-0.436-1.17 0-1.615z"></path></svg></div></div></div></div></div><code class="language-shell keep-markup drop-tokens"><div class="slate-code_line">curl --location &apos;&apos; --header &apos;StoreId: TestAPIKey&apos; --header &apos;Content-Type: application/json&apos; --header <span style="color:#000000" class="slate-color"><strong style="color:#000000" class="slate-bold">&apos;Authorization: Basic VGVzdEFjY2Vzc0tleUZyb21URzpUZXN0U2VjcmV0S2V5RnJvbVRH&apos;</strong></span> --data &apos;{
&quot;UserId&quot;: 0,
&quot;TrackId&quot;: 0,
&quot;Country&quot;: &quot;string&quot;,
&quot;LogPlayType&quot;: &quot;Start&quot;,
&quot;Seconds&quot;: 0,
&quot;Source&quot;: &quot;Queue&quot;,
&quot;PlayType&quot;: &quot;Stream&quot;,
&quot;SourceId&quot;: 0,
&quot;UserIp&quot;: &quot;string&quot;,
&quot;DeviceId&quot;: 0,
&quot;SubId&quot;: 0,
&quot;Guid&quot;: &quot;string&quot;,
&quot;AudioQuality&quot;: &quot;low&quot;,
&quot;ExternalPlanId&quot;: &quot;string&quot;
}&apos;</div><div class="slate-code_line">&apos;https://api-delivery-connect.tunedglobal.com/api/v5/play/logplay&apos;</div></code></pre><p class="slate-p" placeholder="Type / for widgets"></p><div style="text-align:undefined"><img src="https://theneo-prod-public.s3.amazonaws.com/images-1690173286241.png" alt=""/></div><p class="slate-p" placeholder="Type / for widgets"></p>

This relates to the play log end points as noted in the documentation. The logging endpoints are only applicable where Tuned Global is responsible for generating reports on the behalf of a client. If a client is managing their reports internally, then the endpoint (and basic http auth) isn't required.

 This model uses a simple challenge and response mechanism with which a server can request authentication information (Username and password) from a client. 

The client passes the authentication information to the server in an Authorization header e.g. Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of Username and password joined by a single colon;

Note: Please include the API Key under the ‘StoreId: TestKey’ http header with Basic HTTP Authentication. 

Following are the usage examples from the curl and postman.

Hash-based message authentication code (HMAC) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key. This can be used to verify the integrity and authenticity of a message (sent from a client to a server or server to server).

If an intermediate party attempts to intercept and alter an API call for malicious reasons, or where a fault in an intermediary proxy drops key header information, the signature will not match and the API call will be denied.

Tuned Global will provide the client with a public (Access Key) and a private secret (Secret Key). Both of the keys are base-64 encoded strings, which means they should never contain any non-base-64 characters and the length of each key is always a multiple of 4. 

It's the client’s responsibility is to store the Secret Key securely and never share it with other parties. HMAC tokens are one time use only i.e. client needs to generate a new HMAC for every request to the server even if it's for the same resource.

The client must Hash the request content using MD5 hashing algorithm. This typically applies to HTTP GET, PUT and POST requests in which the data is sent to the server in the request body or in query string parameters.

Following fields are required to create HMAC signature

<p></p><p><span><span>Search provides a number of ways to search the available catalogue.  The “Search” API will provide the broadest response with all other search APIs being more specific.</span></span></p><p></p>

Catalogues are made available within these subject to licensing and territories.  The search API will search across all territories you have available and include an available territory node in the response.  You should only display the products available for the territory of the current user.  Any requests for a protected asset (track) for a user where the rights do not exist for their territory will be denied.

If your content is gated based on publishing, you will only see the cleared tracks within your catalogue.

<p></p><p><span><span>The Tuned  system supports tags.  
These are assigned as follows:</span></span></p><ol><li></li></ol>

The system will utilise these tags to assist in assist in determining similarity, but they will also be available for you to retrieve products by tags or via Advanced Search. 

Examples of tag retrieval usage usage are:

Create a shelf on a content page that displays Albums by Tag.  Use this to create a celebration list where you may tag a grouped set of albums as Christmas2024 and hence control how these are displayed.

A second example is to make a user into a verified user (using AutoTune) and then tag them as a Genre.  

A example here may be EDM.  You could then display these users as “Influential” and allow people to see the playlists they have created within an EDM category

A 3rd example is to create a tag, i.e Rock, using AutoTune.  Make it public and assign an image.  You can now display this with a Genre group of images.

Discuss your grouping ideas directly with Tuned so we can assist in getting the most from tags .

<p></p><p><span><span>The services APIs have all end points for user information.  Metadata only provides minimal public information.</span></span></p><p></p><p></p>

/ Apply Filters //  Watermark / Crop / More

You can use Tuned Global’s automatic image resizing end-point in order to generate images in the size you wish.  The system will resize from the original image automatically.  In order to use and access these images, you will need to first get the Thumbor settings from the TUNED APIs or TUNED directly.  

The standard URL for Thumbor is provided below in the example, if you have custom URLs configured this may change.

In order to get an image., you can then add the Thumbor URL ahead of the image URL (available from the APIs) along with the parameters to resize the image.  

You must build your URL to request an image suitable for your application.  Below is a 

 model, for a quick start.  There is also an Advanced section if you want to customise and optimise the images being retrieved.


To simply ask for a resized image, simply specify the size of the image as follows; 

Image size is defines in pixels width x height

= d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Note: This example is the same as Crop in Advanced below.  It is NOT a proportional resize but will crop the image as defined below.  If you wish to proportionally resize you should use Fit