Search & Recommendations
Overview
Tuned Global provides a comprehensive suite of search, discovery, and recommendation APIs. These range from simple keyword search across the entire catalogue, to advanced filtered queries, tag-based browsing, trending content, similarity matching, and personalised recommendations powered by TunedIQ — Tuned Global's machine-learning recommendation engine.
This guide covers all the search and recommendation endpoints available through the Metadata API (v2.4) and Services API (v3), along with integration patterns for building discovery experiences in your application.
Prerequisites
- A StoreId issued by Tuned Global
- OAuth2 credentials for authenticated endpoints (Services API)
- A Bearer token (see DSP Quick Start or Telco Quick Start for authentication steps)
- For TunedIQ personalisation: an active TunedIQ subscription — contact Tuned Global to enable
Catalogue Search
Search endpoints let users find content by keyword across the entire licensed catalogue. All search endpoints are on the Metadata API and require the StoreId header.
Universal Search
Search across all content types in a single request.
Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search?q=Bohemian%20Rhapsody&types=song,artist,album,playlist" \
-H "StoreId: YOUR_STORE_ID" \
-H "Country: AU"
| Parameter | Type | Description |
|---|---|---|
q |
string, required | Search text |
types |
array, optional | Filter by entity type: song, album, artist, playlist, station, user, video, channel, episode, author, audiobook, audiobookchapter, audiobookauthor, livechannel, liveshow, karaoke |
applyCountryFilter |
boolean, optional | Restrict results to the store's territory |
playlistType |
string, optional | Filter playlist type |
Type-Specific Search
For more targeted results, use the dedicated search endpoints:
| Endpoint | Description |
|---|---|
GET /api/v2.4/search/songs?q={query} |
Search songs |
GET /api/v2.4/search/albums?q={query} |
Search albums |
GET /api/v2.4/search/artists?q={query} |
Search artists |
GET /api/v2.4/search/playlists?q={query} |
Search playlists |
GET /api/v2.4/search/stations?q={query} |
Search stations |
GET /api/v2.4/search/videos?q={query} |
Search videos |
GET /api/v2.4/search/channels?q={query} |
Search podcast channels |
GET /api/v2.4/search/episodes?q={query} |
Search podcast episodes |
GET /api/v2.4/search/authors?q={query} |
Search authors |
GET /api/v2.4/search/audiobooks?q={query} |
Search audiobooks |
GET /api/v2.4/search/audiobook-chapters?q={query} |
Search audiobook chapters |
GET /api/v2.4/search/audiobook-authors?q={query} |
Search audiobook authors |
GET /api/v2.4/search/karaokes?q={query} |
Search karaoke tracks |
GET /api/v2.4/search/live-channels?q={query} |
Search live video channels |
GET /api/v2.4/search/live-shows?q={query} |
Search live shows |
GET /api/v2.4/search/users?q={query} |
Search user profiles |
All type-specific endpoints accept offset (default 1) and count (default 10) for pagination, plus applyCountryFilter where applicable.
Example — song search with pagination:
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Let%20It%20Be&offset=1&count=20&applyCountryFilter=true" \
-H "StoreId: YOUR_STORE_ID" \
-H "Country: AU"
Advanced Song Search
The advanced search endpoint gives you fine-grained control over filtering by metadata attributes. Use this for building filtered browse experiences, programmatic playlist curation, or content discovery tools.
Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced?filter.releaseDecade=1990&filter.tags=Rock&filter.tempoMin=120&filter.tempoMax=160&filter.count=20&filter.sortType=Popularity" \
-H "StoreId: YOUR_STORE_ID" \
-H "Country: AU"
Filter Parameters
| Parameter | Type | Description |
|---|---|---|
filter.name |
string | Song name |
filter.artistName |
string | Artist name |
filter.albumTitle |
string | Album title |
filter.tags |
array | Genre, mood, or custom tags |
filter.releaseYear |
int | Specific release year |
filter.releaseDecade |
int | Decade (e.g. 1990, 2000, 2010) |
filter.tempoMin |
int | Minimum BPM |
filter.tempoMax |
int | Maximum BPM |
filter.durationMin |
int | Minimum duration (seconds) |
filter.durationMax |
int | Maximum duration (seconds) |
filter.key |
int | Musical key |
filter.label |
string | Record label |
filter.thematic |
string | Track thematic category |
filter.newReleasesOnly |
boolean | Last 90 days only |
filter.explicit |
boolean | Include explicit content |
filter.lyrics |
boolean | Filter by lyrics availability |
filter.contentLanguage |
string | Track language |
filter.owner |
string | Content owner |
filter.allTagsMustPresent |
boolean | Require all specified tags (AND logic vs default OR) |
filter.enableArtistNameMatch |
boolean | Include artist name in search matching |
filter.sortType |
enum | Relevance, Popularity, AToZ, ZToA, OldToNew, NewToOld |
filter.offset |
int | Pagination start (default 1) |
filter.count |
int | Results per page (default 10) |
Musiio Audio Analysis Filters
If your store has Musiio audio analysis enabled, additional filters are available:
| Parameter | Type | Description |
|---|---|---|
filter.musiioBpmMin |
int | Minimum Musiio-detected BPM |
filter.musiioBpmMax |
int | Maximum Musiio-detected BPM |
Song Matching
Match songs by combining ISRC, song name, artist name, and duration — useful for catalogue ingestion, de-duplication, and cross-referencing with external systems.
Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/search-matching
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/search-matching?isrc=USUM71507297&songName=Sorry&artistName=Justin%20Bieber&durationInSecs=199" \
-H "StoreId: YOUR_STORE_ID"
| Parameter | Type | Match Type | Description |
|---|---|---|---|
isrc |
string | Exact | ISRC code |
songName |
string | Fuzzy (±2 chars) | Song name |
artistName |
string | Fuzzy (±2 chars) | Artist name |
durationInSecs |
string | Exact | Duration in seconds |
All parameters are optional — use any combination. ISRC provides the most precise matching.
Tag-Based Discovery
Tags are a powerful way to browse the catalogue by genre, mood, era, instrument, energy, and custom classifications. The tag system supports multiple tag types for rich filtering.
Search Tags
Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/tags
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/tags?term=Jazz&tagType=Genre&count=20" \
-H "StoreId: YOUR_STORE_ID"
Available Tag Types
| Tag Type | Description |
|---|---|
Genre |
Music genre |
MusiioGenre |
AI-detected genre |
MusiioMood |
AI-detected mood |
MusiioEnergy |
AI-detected energy level |
MusiioInstrumentation |
AI-detected instrumentation |
MusiioInstrument |
AI-detected specific instruments |
MusiioVocalGender |
AI-detected vocal gender |
MusiioBpm |
AI-detected tempo range |
MusiioUseCase |
AI-detected use case category |
RHGenre |
Rights holder genre |
RHSubGenre |
Rights holder sub-genre |
RHInstruments |
Rights holder instrument tags |
RHLanguage |
Rights holder language |
RHIndustry |
Rights holder industry tag |
RHMood |
Rights holder mood |
CountryOfOrigin |
Artist country of origin |
TargetTime |
Time-of-day targeting |
AirlineSchedule |
Airline/IFE scheduling tags |
Audiobook |
Audiobook classification |
User |
User-defined tags |
Browse Content by Tag
Retrieve content filtered by tag:
| Endpoint | Description |
|---|---|
GET /api/v2.4/tags/artists?tag={tag} |
Artists matching tag |
GET /api/v2.4/tags/albums?tag={tag} |
Albums matching tag |
GET /api/v2.4/tags/stations?tag={tag} |
Stations matching tag |
GET /api/v2.4/tags/podcasts?tag={tag} |
Podcasts matching tag |
GET /api/v2.4/tags/audiobooks?tag={tag} |
Audiobooks matching tag |
Albums, stations, and audiobooks support sortType: popular, newreleases, or title.
Browse by Tag Groups
For multi-faceted filtering, use tag groups to combine multiple tag types:
GET /api/v2.4/tags/groups/albums?groups={tagGroups}
GET /api/v2.4/tags/groups/artists?groups={tagGroups}
Browse Playlists by Tags
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/by-tags?filter.tags=Chill,Acoustic&filter.sortType=Popularity&filter.count=10" \
-H "StoreId: YOUR_STORE_ID"
Trending Content
Trending endpoints surface popular content over the last 30 days, providing ready-made discovery feeds for your application.
| Endpoint | Description |
|---|---|
GET /api/v2.4/songs/trending |
Top trending songs |
GET /api/v2.4/albums/trending |
Top trending albums |
GET /api/v2.4/artists/trending |
Top trending artists |
GET /api/v2.4/playlists/trending |
Top trending playlists |
GET /api/v2.4/stations/trending |
Top trending stations |
GET /api/v2.4/stations/trendingartists |
Top 20 artists by liked songs (rolling month) |
GET /api/v2.4/stations/stationtrendingartists?id={id} |
Top 10 trending artists in a specific station |
GET /api/v2.4/search/trending/artists |
Trending artist search terms |
Example — trending songs:
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/songs/trending?offset=1&count=20" \
-H "StoreId: YOUR_STORE_ID"
Trending Playlists
The playlist trending endpoint supports media type filtering:
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/trending?type=Audio&count=10" \
-H "StoreId: YOUR_STORE_ID"
Types: Audio, Video, or All.
New Releases
Surface fresh content with new release endpoints:
| Endpoint | Description |
|---|---|
GET /api/v2.4/songs/new |
Recently released songs |
GET /api/v2.4/albums/new |
New albums ordered by priority |
GET /api/v2.4/albums/newreleases |
Trending new releases |
GET /api/v2.4/albums/newbydate |
Albums ordered by release date |
GET /api/v2.4/artists/newartists?date={date}&count={n} |
Artists added after a given date |
GET /api/v2.4/podcasts/new?from={date} |
New podcasts |
GET /api/v2.4/audiobooks/new?from={date} |
New audiobooks |
Similar Content
Find content similar to a known entity — useful for "More like this" features and radio-style experiences.
Similar Artists
Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/artists/{id}/similar
curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/artists/12345/similar" \
-H "StoreId: YOUR_STORE_ID"
Returns artists with overlapping listening patterns and catalogue attributes.
Similar Artists by Tags
For tag-based similarity (rather than behavioural):
GET /api/v2.4/artists/{id}/similarbytags
Similar Stations
GET /api/v2.4/stations/{id}/similar
Returns stations sharing the most tracks by the same artists.
Similar Podcasts
GET /api/v2.4/podcasts/{id}/similar
Returns podcasts with matching channel tags.
Artist Derived Tags
Retrieve the top 50 tags associated with an artist and their albums — useful for building artist profiles and similarity models:
GET /api/v2.4/artists/{id}/derivedtags
Search Analytics
Track what users are searching for and surface popular terms.
Log a Search Term
Endpoint: POST https://api-metadata-connect.tunedglobal.com/api/v2.4/search/search-term
Log search terms from your application for analytics and trending calculations.
Top Search Terms
GET /api/v2.4/search/search-term/top?groupId={groupId}
Top Searched Products
GET /api/v2.4/search/search-term/top-products?groupId={groupId}&productTypes=Artist,Album,Track
Supported product types: Artist, Album, Station, Playlist, Track, Podcast, Video, Episode, Author, Audiobook, AudiobookChapter, AudiobookAuthor, Karaoke, LiveChannel, LiveShow, User.
Play History
Retrieve a user's listening history for building personalised experiences and "recently played" features.
Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/plays/playhistory
curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/plays/playhistory" \
-H "StoreId: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Requires user authentication (Services API v3).
Personalised Playlists
Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/playlists/trending-by-tagType
curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/playlists/trending-by-tagType?tagType=Genre&count=10" \
-H "StoreId: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Returns playlists tailored to a user's tag preferences and the specified tag type.
TunedIQ — Personalised Recommendations
TunedIQ is Tuned Global's intelligent recommendation engine. Unlike traditional systems that rely on static metadata and genre tags, TunedIQ learns directly from real listening behaviour using collaborative filtering and machine learning.
How TunedIQ Works
| Component | Description |
|---|---|
| Collaborative filtering core | Generates 1:1 recommendations based on behaviour patterns, not metadata tags |
| Cohort-based logic | Groups similar user behaviours to surface smarter discovery — effective even with smaller datasets |
| Adaptive learning | Continuously updates based on the latest listening activity |
| Client-specific models | Isolated per service — no cross-service data sharing |
TunedIQ is particularly effective for catalogues with limited or inconsistent metadata tagging, because it operates on listening patterns rather than genre classifications.
What TunedIQ Delivers
TunedIQ powers several personalised experiences that can appear as dynamic shelves in your application:
| Feature | Description |
|---|---|
| Daily Discovery Mixes | Blends of familiar favourites and new tracks the user hasn't heard |
| Personalised Trending | Trending tracks filtered and ranked by the user's taste profile |
| User-Specific Trending Artists | Artists rising in popularity within the user's preference space |
| Continuous Play | Automatically extends listening sessions from a seed track with contextually relevant suggestions |
Integration
TunedIQ is delivered as a plug-and-play API solution that integrates into white-label apps and custom platforms with minimal engineering effort. Recommendations appear as dynamic shelves — if a user doesn't have enough listening history for a particular shelf, it is automatically hidden rather than showing poor results.
Enabling TunedIQ
TunedIQ requires activation on your store. Contact Tuned Global to:
- Enable TunedIQ for your StoreId
- Confirm the recommendation features available for your plan
- Receive endpoint documentation specific to your integration
- Discuss data requirements and cold-start handling for new users
Note: TunedIQ works without static metadata, making it especially valuable for services operating in regions where catalogue tagging may be sparse or inconsistent (e.g. Southeast Asian, African, or emerging market catalogues).
Building Discovery Experiences
Here's how to combine the search and recommendation APIs to build common discovery features in your application:
Home Screen
1. Trending songs/albums/playlists → /api/v2.4/{type}/trending
2. New releases → /api/v2.4/albums/new
3. Personalised recommendations → TunedIQ shelves (if enabled)
4. Curated playlists by tag → /api/v2.4/playlists/by-tags
5. Carousel content → /api/v2.4/pages/carouselbylanguage
Search Results Page
1. Universal search → /api/v2.4/search?q={query}&types=song,artist,album
2. Log the search term → POST /api/v2.4/search/search-term
3. Show top search terms → /api/v2.4/search/search-term/top
Artist Detail Page
1. Artist profile → /api/v2.4/artists/{id}
2. Artist songs → /api/v2.4/artists/{id}/songs
3. Artist albums → /api/v2.4/artists/{id}/albums
4. Similar artists → /api/v2.4/artists/{id}/similar
5. Featured stations → /api/v2.4/artists/{id}/stations
6. Artist playlists → /api/v2.4/artists/{id}/playlists
Radio / Auto-Play
1. Seed from a track or artist
2. Similar artists → /api/v2.4/artists/{id}/similar
3. Similar stations → /api/v2.4/stations/{id}/similar
4. TunedIQ continuous play → extends sessions automatically
Quick Reference — Endpoints
Metadata API (v2.4) — Search
Endpoint Method Description
------------------------------------------------ ------ ----------------------------------
/api/v2.4/search GET Universal catalogue search
/api/v2.4/search/songs GET Song search
/api/v2.4/search/songs/advanced GET Advanced filtered song search
/api/v2.4/search/search-matching GET ISRC/name/duration matching
/api/v2.4/search/albums GET Album search
/api/v2.4/search/artists GET Artist search
/api/v2.4/search/playlists GET Playlist search
/api/v2.4/search/stations GET Station search
/api/v2.4/search/tags GET Tag search
/api/v2.4/search/search-term POST Log a search term
/api/v2.4/search/search-term/top GET Top search terms
/api/v2.4/search/search-term/top-products GET Top searched products
Metadata API (v2.4) — Discovery
Endpoint Method Description
------------------------------------------------ ------ ----------------------------------
/api/v2.4/songs/trending GET Trending songs (30 days)
/api/v2.4/albums/trending GET Trending albums
/api/v2.4/artists/trending GET Trending artists
/api/v2.4/playlists/trending GET Trending playlists
/api/v2.4/songs/new GET New songs
/api/v2.4/albums/new GET New albums
/api/v2.4/artists/{id}/similar GET Similar artists
/api/v2.4/artists/{id}/similarbytags GET Similar artists (tag-based)
/api/v2.4/stations/{id}/similar GET Similar stations
/api/v2.4/podcasts/{id}/similar GET Similar podcasts
/api/v2.4/tags/artists GET Artists by tag
/api/v2.4/tags/albums GET Albums by tag
/api/v2.4/playlists/by-tags GET Playlists by tags
Services API (v3) — Personalisation
Endpoint Method Description
------------------------------------------------ ------ ----------------------------------
/api/v3/plays/playhistory GET User play history
/api/v3/playlists/trending-by-tagType GET Personalised trending playlists
/api/v3/artists/{id}/similar GET Similar artists (authenticated)
Notes
- Metadata API endpoints use version 2.4. Services API endpoints use v3.
- All requests require the
StoreIdheader. Services API endpoints additionally requireAuthorization: Bearer {token}. - Pagination: use
offsetandcounton all list endpoints. Defaults vary by endpoint (typically offset=1, count=10). - Country filtering: pass the
Countryheader and/orapplyCountryFilter=trueto restrict results to your store's territory. - TunedIQ is a separately licensed feature. Contact Tuned Global to enable personalised recommendations for your service.