← API reference

Genre map

Every Noise at Once — coverage, colour, trajectory, neighbours.

3 of 3 · v0.120.0
GET /api/v1/genre-map #
Token reador Session

The map, your genres on it, and your average colour.

Scope: read (since v0.120). The canvas is 1500 × 22,648 — fifteen times taller than wide — so a client must compress the y axis in the coordinates, not with preserveAspectRatio, which would squash the circles into ellipses too.

colour is blended in linear light, not sRGB; mixing gamma-encoded values drags every user toward the same brown-grey.

Responses

200

OK.

application/json

object

Everything on the map, and where your listening sits on it.

map object required
width number · double required
height number · double required
points array required

[name, x, y, colour] per genre — positional to keep ~6,300 rows small.

each item
array
each item
one of
option 1 string
option 2 number
mine array required

Your genres that have a place on the map.

each item
object
name string required
plays integer · int64 required
x number · double required
y number · double required
color string required
colour string | null

Play-weighted average colour of mine, blended in linear light — what your listening sounds like.

placed_tags integer required
unplaced_plays integer · int64 required

Plays on tags with no place on the map — instruments, nationalities, roles.

listens_with_genres integer · int64 required

So a half-backfilled history says so rather than looking like a small life.

listens_total integer · int64 required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
409

The map has not been fetched yet. Run the scrape in Settings.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/genre-map/trajectory #
Token reador Session

Where your listening sat, period by period.

Scope: read (since v0.120). The play-weighted centroid of each period.

Three honesty constraints, all load-bearing. It is an artist-mix trajectory, not a track-level one — every track by an artist carries that artist's genres and sits at the same point. A period under 25 placed plays is omitted, not drawn, because a centroid from four listens reads as a real movement inside a path. And each period reports its own enrichment coverage, to be drawn faintly below 90% — the genre backfill runs newest-first, so a time-sliced view is the one most distorted by a half-done pass.

The server picks month or year by how much history there is and says which it used. Buckets are in the user's own timezone.

Parameters

by query

year or month. Omitted lets the server pick from the span: by month under a few years of history, by year otherwise.

string

Responses

200

OK.

application/json

object

The play-weighted centre of each period's listening, on the map's coordinates.

years array required
each item
object
year string required

2024, or 2024-03 by month.

x number · double required
y number · double required
plays integer · int64 required
colour string | null
listens integer · int64 required

Listens in the period…

enriched integer · int64 required

…and how many of them have genres resolved. A thin period is labelled rather than drawn as if it were complete.

unit string required

year or month.

min_plays integer | null · int64

Periods with fewer placed plays than this are left out.

note string | null

Set when nothing could be drawn.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/genre-map/neighbours #
Token reador Session

What sits next to your listening.

Scope: read (since v0.120). Walks Every Noise's precomputed adjacency, seeded from your top 25 genres.

This does not recommend music, and the response shape is what enforces that. Two artist fields that are never both populated on the same card:

  • your_artists — from your own history. Only ever set on next_door.
  • exemplar_artists — Every Noise's own exemplars, for a genre you own nothing in. These name music you do not have. Any client showing them owes the reader that provenance, in words and in styling.

exemplar_artists is empty until a tier-2 scrape has run — a tier-1-only instance has adjacency but no exemplars. Say so rather than rendering bare cards that look like a bug.

Responses

200

OK.

application/json

object

Genres bordering your listening, split by whether you already own music there.

next_door array required

Bordering genres you already own music in and underplay. This half leads.

each item
object

A genre bordering your listening. your_artists and exemplar_artists are never both populated, so nothing can present an Every Noise exemplar as something the listener owns.

name string required
x number · double required
y number · double required
color string required
borders integer required

How many of your top genres border it.

affinity number · double required

plays / sqrt(rank + 1), summed: weighted by your play counts and discounted by Every Noise's own neighbour rank.

your_plays integer · int64 required
your_artists array required

From your own history. Empty is what puts a genre in unexplored.

each item
object
artist string required
plays integer · int64 required
exemplar_artists array required

Every Noise's exemplars — not your music. Set only where your_artists is empty. Requires a tier-2 scrape; empty otherwise.

each item
string
unexplored array required

Bordering genres you own nothing in — a region, never a suggestion.

each item
object

A genre bordering your listening. your_artists and exemplar_artists are never both populated, so nothing can present an Every Noise exemplar as something the listener owns.

name string required
x number · double required
y number · double required
color string required
borders integer required

How many of your top genres border it.

affinity number · double required

plays / sqrt(rank + 1), summed: weighted by your play counts and discounted by Every Noise's own neighbour rank.

your_plays integer · int64 required
your_artists array required

From your own history. Empty is what puts a genre in unexplored.

each item
object
artist string required
plays integer · int64 required
exemplar_artists array required

Every Noise's exemplars — not your music. Set only where your_artists is empty. Requires a tier-2 scrape; empty otherwise.

each item
string
opposite array required

Furthest from your listening. Suggests nothing by construction.

each item
object

A genre bordering your listening. your_artists and exemplar_artists are never both populated, so nothing can present an Every Noise exemplar as something the listener owns.

name string required
x number · double required
y number · double required
color string required
borders integer required

How many of your top genres border it.

affinity number · double required

plays / sqrt(rank + 1), summed: weighted by your play counts and discounted by Every Noise's own neighbour rank.

your_plays integer · int64 required
your_artists array required

From your own history. Empty is what puts a genre in unexplored.

each item
object
artist string required
plays integer · int64 required
exemplar_artists array required

Every Noise's exemplars — not your music. Set only where your_artists is empty. Requires a tier-2 scrape; empty otherwise.

each item
string
seeded_from integer required

How many of your top genres the walk started from.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
409

None of your genres are on the map yet.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.