Search & Deezer Catalog API
Relevant source files
The following files were used as context for generating this wiki page:
The Search and Deezer Catalog API system is a core infrastructure component of Kocteau that enables music discovery and review creation. It leverages the Deezer Search API as its primary external data source while implementing a "Kocteau-first" ranking strategy. This strategy prioritizes internal data—such as existing entities and curated starter picks—over raw external results to provide a tailored editorial experience.
The system is architected to handle multi-source data retrieval, including local database lookups for tracks and artists, curated "starter tracks" for cold-start scenarios, and live API calls to Deezer. It includes sophisticated ranking logic that weighs source reliability, textual overlap, and external popularity metrics (rank) to present the most relevant results to the user.
Sources: README.md:92-100, apps/web/app/api/search/route.ts:182-220, apps/web/lib/search/kocteau-first.ts:98-132
Search Architecture and Data Flow
The search process is triggered via the /api/search endpoint. It orchestrates a parallelized lookup across three distinct candidate pools: local entities, starter tracks, and the external Deezer catalog.
Multi-Source Candidate Retrieval
The system identifies music metadata from the following sources:
- Local Entities: Tracks already reviewed or stored in the Supabase
entitiestable. - Starter Tracks: Curated picks stored in the
starter_trackstable used for editorial discovery. - Deezer External: Live results from the Deezer API, including direct track matches and top tracks for matched artists.
The diagram shows the parallelized retrieval architecture where internal and external sources are aggregated, deduped, and ranked before returning to the client.
Sources: apps/web/app/api/search/route.ts:168-208, apps/web/lib/search/kocteau-first.ts:145-155
Ranking Logic (Kocteau-First)
Kocteau uses a scoring algorithm to ensure that internal or curated content appears higher in search results than generic external results. The total score for a candidate is the sum of source-specific base scores, metadata bonuses, and textual similarity matches.
Scoring Components
The scoring system defines specific weights for various attributes:
| Component | Logic / Description | Weight / Bonus |
|---|---|---|
| Source: Local | Entities already in Kocteau database | 320 |
| Source: Starter | Curated editorial picks | 260 |
| Source: Artist Match | Tracks from a strongly matched artist | 150 |
| Entity ID Bonus | Awarded if the track exists in local DB | +45 |
| Artist Match | Exact match on artist name | +650 |
| Title Match | Exact match on track title | +360 |
| Token Overlap | Per-word overlap in title/artist | +24 per token |
Sources: apps/web/lib/search/kocteau-first.ts:25-35, apps/web/lib/search/kocteau-first.ts:104-128
Deduplication and Tie-Breaking
When the same track is found across multiple sources, the system merges them into a single candidate. It prioritizes the "winner" based on source priority (Local > Starter > Artist Match > Deezer). If scores are identical, tie-breaking is handled by source priority and then the original index from the source.
Sources: apps/web/lib/search/kocteau-first.ts:70-85, apps/web/lib/search/kocteau-first.ts:157-164
Deezer Integration
The deezer.ts library provides a robust wrapper around the Deezer API, including error handling, retries, and data mapping.
Core API Methods
The integration manages several types of requests to populate the catalog:
searchDeezerTracks: General keyword search for tracks.searchDeezerArtists: Finding artists for "strong match" logic.getDeezerArtistTopTracks: Fetching popular songs for a matched artist.getDeezerTrack: Retrieving a single track's metadata by its provider ID.
Reliability Features
The system implements several safeguards for external API calls:
- Timeouts: Requests are aborted after 8,000ms.
- Retries: Implements exponential backoff for 429 (Rate Limit) and 5xx (Server) errors.
- Caching: Uses Next.js
revalidatetags (e.g., 60s for search, 300s for specific resources).
Sources: apps/web/lib/deezer.ts:106-110, apps/web/lib/deezer.ts:121-140, apps/web/lib/deezer.ts:182-192
API Endpoints and Validation
The Search API is strictly validated using Zod schemas to ensure query integrity and prevent injection.
GET /api/search
Primary endpoint for track discovery.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | The search query (max 80 chars). |
type | enum | No | Entity type (defaults to track). |
Sources: apps/web/lib/validation/schemas.ts:68-75, apps/web/app/api/search/route.ts:222-233
Sequence of a Search Request
The sequence diagram illustrates the parallel nature of the search, where local database queries and external API calls happen concurrently to minimize latency.
Sources: apps/web/app/api/search/route.ts:241-260
Conclusion
The Search & Deezer Catalog API is a sophisticated retrieval system that balances external catalog breadth with local editorial control. By implementing a multi-source parallel fetch and a weighted ranking algorithm, Kocteau ensures that users find relevant tracks quickly while reinforcing the platform's internal metadata and curated content.