Advanced Search

The advanced search combines our different search modalities into a single endpoint and extends its functionality with a powerful dynamic metadata filter and the ability to use multiple tracks as search input. Additionally it allows for retrieving fine grained search scores which help to understand similarities throughout an entire track. These scores are available on full track level and additionally on a segment level, highlighting the most similar regions of the resulting tracks.

Public Preview

This feature is currently in Public Preview. The API surface, including arguments and return types, might change in future releases without prior notice. Use with caution in production environments.

Advanced Search Endpoint

The advancedSearch query allows you to specify your search criteria and retrieve matching tracks.

query AdvancedSearchExample(
    $trackID: ID
    $trackIDs: [ID!]
    $text: String
    $target: AdvancedSearchTarget!
    $filter: JSONObject
    $searchMode: SimilarTracksSearchMode
    $retrieveSegmentScores: Boolean
    $first: Int
) {
  advancedSearch(
      trackID: $trackID
      trackIDs: $trackIDs
      text: $text
      target: $target
      metadataFilter: $filter
      searchMode: $searchMode
      retrieveSegmentScores: $retrieveSegmentScores
      first: $first
  ) {
    # Results depend on the fields you want to query
  }
}

Advanced Search Arguments

Argument	Type	Required	Description
trackID	ID	No	Track ID as reference input to perform the advanced search and find matching tracks. Use Spotify ID or Library Track ID. Use this or trackIDs or text.
trackIDs	[ID!]	No	A list of specific track IDs to be used as reference for the search. Accepts Spotify IDs or Library Track IDs. Maximum of 50 IDs; additional IDs will be omitted. Use this or trackID or text.
text	String	No	Our free text search is language agnostic and will understand and interpret your search prompt in nearly every language. Maximum of 1024 characters; additional characters will be omitted. Use this or trackID or trackIDs.
target	AdvancedSearchTarget	Yes	Specifies the scope of the search (where to look for matches). You must provide exactly one target (e.g., library, crate, or spotify).
metadataFilter	JSONObject	No	Advanced search metadata filter that contains custom flexibly search criterias for tracks. A detailed documentation can be found under: Metadata Filter.
searchMode	SimilarTracksSearchMode	No	Specifies which part of the input track to use when searching based on a single trackID. Options: complete (default), mostRepresentative, interval. Only applicable when trackID is used.
retrieveSegmentScores	Boolean	No	Set to true to retrieve detailed scores for the highest-scoring segments within matching tracks. Defaults to false. Required if you query the topScoringSegments field.
first	Int	No	The maximum number of matching tracks to return. Defaults to 10. Maximum is 500. If retrieveSegmentScores is true, the maximum is reduced to 30.

Advanced Search Results

The query returns an AdvancedSearchResult, which is a GraphQL Union type. This means the result will be one of the following concrete types:

1. AdvancedSearchConnection: Returned on a successful search. This follows the standard GraphQL Relay Connection specification.
2. AdvancedSearchError: Returned if the search could not be performed successfully. Contains a message and an error code.

query AdvancedSearchExample(
  $trackID: ID
  $trackIDs: [ID!]
  $text: String
  $target: AdvancedSearchTarget!
  $filter: JSONObject
  $searchMode: SimilarTracksSearchMode
  $retrieveSegmentScores: Boolean
  $first: Int
) {
  advancedSearch(
    trackID: $trackID
    trackIDs: $trackIDs
    text: $text
    target: $target
    metadataFilter: $filter
    searchMode: $searchMode
    retrieveSegmentScores: $retrieveSegmentScores
    first: $first
  ) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
            ... on AdvancedSearchNodeSpotifyTrack {
              id
            }
          }
        }
      }
    }
  }
}

Advanced Search Examples

Library tracks with Segments

Search for your library tracks with a single reference track as input and get similar tracks including the top segment scores.

query AdvancedSearchLibraryTracksWithSegments {
  advancedSearch(
    trackID: 1
    target: { library: {} }
    retrieveSegmentScores: true
    first: 50
  ) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
          }
          score
          topScoringSegments {
            score
            timeRangeStart
            timeRangeEnd
          }
        }
      }
    }
  }
}

Free text search

Search for tracks by providing a prompt which describes what you are looking for. Our free text search is language agnostic and will understand and interpret your search prompt in nearly every language.

query AdvancedFreeTextSearch {
  advancedSearch(
    text: "relaxing and quiet song for meditation"
    target: { library: {} }
    first: 10
  ) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
          }
        }
      }
    }
  }
}

Crate search

Search for similar tracks in a crate with a single reference track as input.

query AdvancedCrateSearch {
  advancedSearch(trackID: 1, target: { crate: { id: 1 } }, first: 10) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
          }
        }
      }
    }
  }
}

Spotify Search

Search for similar spotify tracks with a single reference library or spotify track as input.

query AdvancedSpotifySearch {
  advancedSearch(trackID: 1, target: { spotify: {} }, first: 10) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeSpotifyTrack {
              id
            }
          }
        }
      }
    }
  }
}

Multi Track Search

Use multiple tracks as reference input to perform a similarity search.

query AdvancedMultiTracksInputSearch($trackIDs: [ID!]!) {
  advancedSearch(trackIDs: [1, 2, 3], target: { library: {} }, first: 50) {
    ... on AdvancedSearchError {
      code
      message
    }
    ... on AdvancedSearchConnection {
      edges {
        node {
          track {
            ... on AdvancedSearchNodeLibraryTrack {
              id
            }
          }
        }
      }
    }
  }
}

Important Considerations

• Preview Status: Remember this API is subject to change.
• Target Requirement: You must specify exactly one target (library, crate, or spotify).
• ID Limits: Maximum 50 trackIDs.
• Text Limits: Maximum 1024 characters for text.
• Result Limits: Maximum 500 results by default, but reduced to 50 if retrieveSegmentScores is true.
• Segment Scores: You must set retrieveSegmentScores: true in the arguments and query the topScoringSegments field (or similar) within the AdvancedSearchConnection nodes to get segment data.
• Error Handling: Always include an inline fragment (... on AdvancedSearchError) to handle potential errors gracefully.