Get Recommendations
get_recommendationsRead-only
Recommended tracks for one or more seed tracks — the drop-in for Spotify's removed GET /v1/recommendations. Blends up to 5 catalog seed tracks into a single point in audio-feature space and returns the nearest catalogue tracks, RE-RANKED by genre affinity (so a feature-close cross-genre track doesn't outrank same-genre picks).
Returns `seeds` (each {id, found}), `count`, and `tracks` (each {track, score,
genre_relation}; each track carries its `genre`). `genre_relation` is "same", "compatible"
(different but mixable family), "cross" (unrelated), or "unknown" (either side has no mapped
genre), measured against the PRIMARY seed — the first of your seed_tracks we could actually
use, so reordering seed_tracks changes it and a skipped seed never becomes the reference.
With a SINGLE seed the field is the ranking's own verdict, so it explains the order (same as
suggest_next_track). With SEVERAL seeds the ranking considers ALL of them while the label stays
relative to your primary seed, so a "cross" label on a multi-seed call does NOT mean the track
was pushed down — it may share a family with another of your seeds. `score` is the raw
audio-feature cosine similarity in [0,1]; genre affinity influences the ORDER, not the score,
so the list is NOT strictly score-descending.
Use cross_genre=strict to return same-genre-family tracks ONLY (off-genre dropped
server-side), or allow to disable the genre ranking. seed_tracks are catalog itunes_track_ids
from search_catalog or the itunes_track_id field of a get_audio_features result.
NO id? Pass `track` (+ optional `artist`) instead and we resolve the name to the best catalog
match and seed on it — the resolved track is echoed back as `seed_query`; seed_tracks wins if
both are given.
TUNING: `min`/`max` are HARD filters and `target` is a preference (nearer ranks higher,
nothing removed), over acousticness, danceability, duration_ms, energy, instrumentalness,
liveness, loudness, popularity, speechiness, tempo and valence. e.g. min={"tempo": 100},
max={"tempo": 130}, target={"energy": 0.8} for energetic 100-130 BPM tracks. When you tune,
the response adds a `filters` block saying what applied, how many tracks each bound removed
(`dropped_by`) and whether the bounds ran out of catalogue before `limit` (`limit_reached`)
— if the list comes back short, read that BEFORE assuming the catalogue is thin.
Costs 2 quota units.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | HARD upper bounds, e.g. {'tempo': 130}. Same attributes as `min`. Combine the two for a range. | |
| min | No | HARD lower bounds, e.g. {'tempo': 100, 'energy': 0.5}. Tracks below the bound — and tracks we hold no analysed value for — are dropped. Attributes: acousticness, danceability, duration_ms, energy, instrumentalness, liveness, loudness, popularity, speechiness, tempo, valence. | |
| limit | No | Number of recommendations to return (default 20). | |
| track | No | Seed by track NAME instead of an id — resolved to the best catalog match (echoed back as seed_query). Pair with artist to disambiguate. Ignored when seed_tracks is given. | |
| artist | No | Artist name narrowing the track seed (case-insensitive). | |
| target | No | PREFERRED values, e.g. {'energy': 0.8}. Tracks nearer the value rank higher; unlike min/max nothing is removed. Same attributes as `min`. | |
| cross_genre | No | Genre handling (mirrors suggest_next_track): 'auto' (default) re-ranks by genre affinity so a feature-close cross-genre track can't outrank same-genre picks; 'strict' = same genre-family only (off-genre dropped server-side); 'allow' = genre-blind (pure audio-feature cosine). | auto |
| seed_tracks | No | 1-5 catalog itunes_track_ids to base recommendations on, e.g. ['apple_ad1829eeccb70f9a'] (blended into a feature-space centroid). Omit and use track(+artist) to seed by name instead. | |
| exclude_seed_artists | No | Drop tracks by any of the seed artists (default false). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||