Skip to main content

Keyword Search

The keyword search allows for searching tracks based on multiple keywords simultaneously where each keyword can be weighted for their impact on the search.

The keyword taxonomy currently contains 1500 unique terms spanning the categories mood, genre, situation, brand values and style. A single keyword can be weighted from the range -1 to +1. For example the keyword search input sparkling: 0.5, sad: -1, rock: 1, dreamy: 1, would refer to a search for a rock track which is dreamy, slightly sparkling and not at all sad.

The access to the keyword search must be explicitly requested from the cyanite sales team.

Available keywords​

A list of all available keywords can be retrieved via the Query.keywords field.

query Keywords {
  keywords {
    edges {
      node {
        keyword
      }
    }
  }
}

All the keywords returned by the Query.keywords field are eligible for performing a keyword search and can be used as an import for the Query.keywordSearch field.

Specifying a target​

The Query.keywordSearch field requires the Query.keywordSearch(target:) argument of the KeywordSearchTarget! input type.

This argument specifies what kind of search results we want. Currently, it is possible to get results from the library, a crate or spotify.

TargetQuery.keywordSearch(target:) value
library{ library: {} }
crate{ crate: { crateId: "$crateId" } }
spotify{ spotify: {} }
caution

It is only possible to specify one target. Mixing options e.g. { library: {}, spotify: {} } might result in an error.

Specifying keywords​

The Query.keywordSearch field requires the Query.keywordSearch(keywords:) argument of the [KeywordSearchKeyword!]! input type.

The KeywordSearchKeyword input types describes a weighted keyword.

[
  {
    "keyword": "sparkling",
    "weight": 0.5
  },
  {
    "keyword": "sad",
    "weight": -1
  },
  {
    "keyword": "rock",
    "weight": 1
  },
  {
    "keyword": "dreamy",
    "weight": 1
  }
]

It is possible to specify up to 10 keywords. A single keyword can be weighted from the range -1 to +1. The example input sparkling: 0.5, sad: -1, rock: 1, dreamy: 1, would refer to a search for a rock track which is dreamy, slightly sparkling and not at all sad.

Keyword search result​

The keyword search returns either an error (KeywordSearchError) or a connection of tracks (KeywordSearchConnection).

An error is described by the KeywordSearchError type. The KeywordSearchError.code field describes the error reason.