Deep Dive

1

Search & Recommendations patterns

The Tuned Global search system provides comprehensive catalogue search capabilities across all content types. The search API searches across all territories you have available and includes territory availability in the response. Catalogues are made available subject to licensing and territorial restrictions.

Available Search Types

• Global Search - Broad search across all content types
• Catalogue Search - Search for albums, artists, tracks, playlists, stations, and videos
• Audiobook Search - Search audiobooks, authors, and chapters
• Podcast Search - Search podcast channels, episodes, and authors
• Live Shows - Search live channels and shows
• Advanced Search - Fine-grained search with specific parameters
• Tag Search - Find content by genre, mood, and other metadata tags

Key Capabilities

• Territory-aware results - Only display content available for user's location (country)
• Entity-specific endpoints - Optimized search for each content type (songs, albums, artists, radio stations, playlists)
• Search term tracking - Capture trending search terms within your service.
• Matching algorithms - Advanced song matching and similarity

Search Endpoints

• Global Search: /Search/Catalogue/Search - Universal search across all content types
• Track Search: /Search/Catalogue/SongSearch - Search specifically for tracks
• Album Search: /Search/Catalogue/AlbumSearch - Find albums in your catalogue
• Artist Search: /Search/Catalogue/ArtistSearch - Discover artists
• Playlist Search: /Search/Catalogue/PlaylistSearch - Find curated playlists
• Station Search: /Search/Catalogue/StationSearch - Browse radio stations
• Video Search: /Search/Catalogue/VideoSearch - Search video content
• Advanced Song Search: /Search/Catalogue/AdvancedSongSearch - Fine-grained track filtering
• Trending Terms: /Search/Other/Gettrendingterms - Get popular search queries

Recommendations

• Track Recommendations: /Catalogue/Track/GetRecommended - Get similar tracks
• Track IQ Recommendations: /Catalogue/Track/GetIQRecommendations - AI-powered suggestions
• Similar Artists: /Catalogue/Artist/Similar - Find similar artists
• Similar Tracks: /Catalogue/Track/Similar - Discover related tracks

Full documentation https://docs-api-metadata.tunedglobal.com/search-1

2

Playback & entitlement

Playback in Tuned Global’s systems allow users to play tracks instantly if they are entitled, or will prevent them from streaming if they do not have the entitlement.

Sequence

Billing & Subscriptions: entitlement check → OK

Playback: stream URL/token (with geo/rights rules) → Player starts.

Playback Endpoint

POST /api/v3/plays/{trackId}/{device}/stream

Inputs:

• Tuned Global Track ID
• Device ID (Provided by Tuned Global with your test key and account)
• Query parameters:
• streamType=Music or Podcast or Audiobook
• streamProvider=Tuned or External

Returns:

• A signed streaming URL which your player can use for playback.

Example:

curl --location --request POST "https://api-services-connect.tunedglobal.com/api/v3/plays/{trackId}/{device}/stream?streamType=Music&streamProvider=Tuned" --header "StoreID: XXYY" --header "Authorization: Bearer xxxyyyy"

Key Points:

• This validates playback wiring, entitlements, and device-level rights enforcement
• The streaming URL includes geo/rights rules enforcement
• URL has a time-to-live (TTL) expiry for security

Common Errors:

• 403 on playback → Token expired or user not entitled. Re-authenticate; check subscription/package.
• 401 error → Invalid or missing authorization token

3

Play logging & reporting hooks

Tuned Global provides an extensive playlogging solution, to ensure that plays are reliably captured and reports can reconcile, even if the user was offline. Playback events should be logged for reporting, licensing, and analytics purposes. Accurate play logs power royalty reporting and help you understand user behaviour.

Sequence

Start play → (optional) end/duration → Play Logging (retry if offline) → Reporting.

Play Logging Endpoint

POST /api/v3/plays/{device id}

Minimum Schema Fields:

• TrackId: The Tuned Global track identifier
• LogPlayType: Event type ("Start", “Progress”, "End", "Skip")
• Seconds: Duration in seconds (e.g., 30 for the 30-second point)
• Source: Where the play originated (e.g., "Album", "Playlist", "Radio")
• SourceId: ID of the source (album ID, playlist ID, etc.)
• Guid: Unique identifier for this play event
• Country: Two-letter country code (e.g., "AU", "US")
• PlayerType: Device type (e.g., "MobilePhone", "Desktop", "WebPlayer")

Recommended Logging Events:

• Start of Play - When playback begins
• 30-second point - Mandatory for reporting (required for royalty calculations)
• Skip event - Include the timestamp at the moment of skip
• End of File - When track completes

Offline Retry Guidance:

• Implement retry logic for failed log attempts
• Queue play events locally when offline
• Batch send queued events when connection is restored
• Maintain event ordering and timestamps

Sample Payload:

{"TrackId": {trackId}, "LogPlayType": "Start", "Seconds": 30, "Source": "Album", "SourceId": {albumId}, "Guid": "ao2n-d3fw-dd5v-ddx3", "Country": "AU", "PlayerType": "MobilePhone"}

Example:

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/222" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"TrackId": {trackId}, "LogPlayType": "Start", "Seconds": 30, "Source": "Album", "SourceId": {albumId}, "Guid": "ao2n-d3fw-dd5v-ddx3", "Country": "AU", "PlayerType": "MobilePhone"}'

Troubleshooting:

• No play logged → Verify timestamps, user ID, and duration threshold
• Missing plays in reports → Ensure 30-second point is being logged
• Duplicate plays → Check Guid uniqueness and retry logic

4

Playlists & library

Tuned Global's Playlist APIs enable comprehensive playlist management for both user-generated and system-curated content. Our platform supports full lifecycle management including creation, modification, sharing, and deletion of playlists, with robust privacy controls and bulk operations to handle large track collections efficiently.

Flow: Create playlist (user or system) → Add tracks (individual or bulk) → Manage content (reorder, remove tracks) → Update metadata (title, description, privacy) → Delete playlist.

Key Endpoints:

Playlist Management

• Create a Playlist POST /api/v2/playlists Creates a new playlist. The body accepts metadata including name, description, and flags for visibility (public), allowing suggestions, or designating as a video playlist. Defaults to private.
• Edit Playlist Metadata PATCH /api/v2/playlists/{id} Performs partial updates to playlist properties. key parameters include Name, Description (multilingual), IsPublic, AllowSuggestions, and IsDraft.
• Get Playlist Details GET /api/v2/playlists/{id} Retrieves full metadata for a specific playlist, including creator information, track count, duration, and creation/update timestamps. The tracklist itself can be retrieved from the below endpoint.
• Get Playlist Tracks GET /api/v2/playlists/{id}/tracks Retrieves the tracklist for a specific playlist.
• Delete a Playlist DELETE /api/v2/playlists/{id} Permanently removes the specified playlist from the user’s collection and the public catalogue.
• Get My Playlists GET /api/v2/playlists Returns a summarized list of playlists created by the logged-in user. Supports pagination via offset and count, and filtering by media type (Audio, Video, Karaoke, or All).

Track Operations

• Add Tracks POST /api/v2/playlists/{id}/tracks Appends a list of track IDs to an existing playlist. Supports the optional query parameter skipHistoryCheck to allow re-adding previously deleted tracks.
• Remove Tracks DELETE /api/v2/playlists/{id}/tracks Removes specific items from a playlist. The request body must specify the track IDs to be deleted.
• Replace Track List PUT /api/v2/playlists/{id}/tracks Completely resets the playlist contents, replacing the current track list with a new set of IDs.
• Clear Track List DELETE /api/v2/playlists/{id}/tracks/clear Empties the playlist completely without deleting the playlist object itself.
• Reorder Tracks PATCH /api/v2/playlists/{id}/tracks Updates the position of a specific track within the list using the track's existing ID and the desired new position.

Discovery & Utilities

• Upload Cover Image PUT /api/v2/playlists/{id}/image/cover Sets a custom cover image for the playlist. Supports JPEG, PNG, GIF, BMP, and TIFF formats.
• Get User Context GET /api/v2/playlists/{id}/context Returns metadata regarding the current user's relationship to a playlist (e.g., whether they are following it) to aid personalization.
• Retrieve Recommendations (Playlists By Onboarding Tags, Trending Playlists By Tag Type) Returns curated or trending playlists based on user interests, tags, or onboarding selections.

5

Radio inside a DSP (optional)

Tuned Global’s Station APIs provide a "lean-back" listening experience, allowing users to stream curated or algorithmic content with minimal input. The platform supports pre-programmed pools, programmatic "seed-based" radio, and external live streams, all while enforcing licensing rules such as DMCA skip limits and play logging.

Flow: Select Station (Curated, Seeded, or External) → Retrieve initial tracks → Play & Log → Request next tracks (on-demand) → Manage user feedback (Likes/Dislikes) → Enforce skip rules. Key Endpoints:

• Add Station by Seed POST /api/v2/stations/addbyseed Creates a programmatic station based on a "seed" (e.g., an Artist ID). The system generates a unique playout of that artist and similar content using tag-based logic.
• Get Station Tracks POST /api/v2/stations/{id}/gettracks Retrieves the next set of tracks for a station. To maintain the "radio" experience and comply with licensing, the system typically returns a limited number of upcoming tracks rather than a full list.
• Submit Votes (Likes/Dislikes) PUT /api/v2/stations/{id}/vote Submits user feedback for the current track. These votes directly influence the station's future playout for that specific user, and will prevent any disliked tracks from being played again.
• Calculate Remaining Skips GET /api/v2/stations/{id}/{deviceId}/skipsremaining Returns the number of skips remaining for the user in the current hour, based on service-level or DMCA rules.

6

Check subscription (optional)

Confirm that the user has premium playback privileges before generating the stream URL to prevent unauthorized access.

Services → Billing & Subscriptions