Skip to main content

Search by reference

Reference-Based Search

Let users search by typing a song they already know. The API finds Epidemic Sound tracks that sound similar to any Spotify track.

Users often think in references: "I want something that sounds like Never Gonna Give You Up". This feature lets them search that way—no music vocabulary needed.

Which discovery feature do I want?​

For other discovery scenarios (Epidemic Sound track references, audio uploads), see the Find Similar guide. The guide covers Finding Epidemic Sound tracks when you only have an external reference (e.g., a Spotify track name).

How it works​

  1. User types a song name (e.g., "never gonna give")
  2. Search suggestions endpoint returns Spotify matches (e.g., "Never Gonna Give You Up - Rick Astley")
  3. User selects the Spotify suggestion
  4. Pass the Spotify URL to the search endpoint
  5. User gets Epidemic Sound tracks with a similar vibe

Example autosuggest response​

The search suggestions endpoint returns two kinds of suggestion, and a single response can contain both:

  • text — an autocompletion of what the user has typed, like any search-box typeahead. Typing epic tra suggests epic trap, epic trailer, epic trailers.
  • external/spotify — a known song matching what the user typed. Its value is the Spotify URL that makes reference search work.
{
  "suggestions": [
    {
      "value": "epic trailer",
      "title": "epic trailer",
      "type": "text"
    },
    {
      "value": "https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8",
      "title": "Never Gonna Give You Up - Rick Astley",
      "type": "external/spotify"
    }
  ]
}

Show title to the user in both cases. On selection, pass the suggestion's value as the term parameter — a text value runs an ordinary semantic search, a Spotify URL runs a reference search.

The mix depends on the query: a distinctive song title tends to return only Spotify suggestions, a descriptive phrase only text ones. A query that matches nothing returns an empty suggestions array, so handle that case — unlike search itself, autosuggest can come back empty.

The two-step flow is required — the song title alone is not a reference

Reference matching is triggered by the Spotify URL, not by the song name. Passing term=Never Gonna Give You Up is treated as an ordinary semantic search and returns tracks matching those words, not tracks that sound like the Rick Astley recording. You must go through autosuggest to obtain the URL, or let the user paste one directly.

Expect a 503 on the first request for a reference

The first time a given Spotify track is used as a term, the API may respond 503 with {"message": "Search results are not ready yet, please retry shortly"} while the reference is analysed. This is not an outage - retry after a short delay and the same request returns 200 with results.

Retry with a short backoff (for example 1s, 2s, 4s) and show a "finding matches" state rather than an error.

Implementation tips​

  • Show a Spotify icon next to Spotify suggestions so users know what they're selecting
  • Debounce autosuggest calls (e.g., 300ms delay) to avoid excessive API requests
  • Users can also paste Spotify URLs directly into your search field