Reference
Models
Every object the public API returns. Fields marked always are always present; others can be missing, and fields shown as … or null can be null. New fields can appear at any time: ignore ones you do not know.
Meta#
Sent with every successful JSON response.
| Field | Type | Description |
|---|---|---|
| apiVersionalways | integer | The API version that answered. |
| migrationPhase | integer | Internal to Rankd. Ignore it. |
| sourceOfTruth | string | Internal to Rankd. Ignore it. |
PageMeta#
Meta, plus the cursor for the next page.
| Field | Type | Description |
|---|---|---|
| apiVersionalways | integer | The API version that answered. |
| migrationPhase | integer | Internal to Rankd. Ignore it. |
| sourceOfTruth | string | Internal to Rankd. Ignore it. |
| nextCursor | string or null | Pass this as cursor to get the next page. null or missing on the last page. |
FeedMeta#
Meta for the feed.
| Field | Type | Description |
|---|---|---|
| apiVersionalways | integer | The API version that answered. |
| migrationPhase | integer | Internal to Rankd. Ignore it. |
| sourceOfTruth | string | Internal to Rankd. Ignore it. |
| nextCursor | string or null | Pass this as cursor for the next page. null at the end. |
| personalized | boolean | Whether the feed is shaped by the caller’s own taste. Always false without credentials. |
| coldStart | boolean | Whether this is the general community ranking rather than a feed shaped by who the caller follows. |
Error#
Every error except rate limiting.
| Field | Type | Description |
|---|---|---|
| erroralways | object | |
| codealways | string | A stable, machine-readable reason. Branch on this. |
| messagealways | string | A readable explanation. Its wording can change, so do not parse it. |
RateLimitError#
The rate limiter answers before the API does, so this body is shaped differently from other errors.
| Field | Type | Description |
|---|---|---|
| erroralways | string | Always rate limited.One of: rate limited |
ApiInfo#
| Field | Type | Description |
|---|---|---|
| namealways | string | The API’s name. |
| versionalways | integer | The API version. |
| documentation | string | A pointer to Rankd’s internal notes. Use this site instead. |
Health#
| Field | Type | Description |
|---|---|---|
| databasealways | string | Whether the API could query its database. One of: ok, error |
MusicRef#
A piece of music as Rankd stores it: a catalogue reference plus the title and artwork it had when it was saved.
| Field | Type | Description |
|---|---|---|
| provideralways | string | The catalogue the id belongs to. One of: apple_music |
| typealways | string | What kind of item. One of: album, song, artist, music_video |
| idalways | string | The catalogue id. |
| title | string or null | The title when Rankd stored it. |
| artistName | string or null | The artist when Rankd stored it. Empty for artists. |
| artworkUrl | string or null | Artwork at 600×600 on Apple’s image servers. |
| albumId | string or null | For songs: the album it is from. |
| albumTitle | string or null | For songs: that album’s title. |
MusicSummary#
A catalogue item as it appears in results, charts and tracklists. Which fields are present depends on where it appears.
| Field | Type | Description |
|---|---|---|
| provider | string | The catalogue the id belongs to. One of: apple_music |
| typealways | string | What kind of item. One of: album, song, artist, music_video |
| idalways | string | The catalogue id. |
| title | string or null | Title. |
| artistName | string or null | Artist. Empty or null for artists. |
| artworkUrl | string or null | Artwork at 600×600. |
| artworkTemplate | string or null | Artwork with {w}x{h} in place of the size, so you can ask for exactly the size you draw. |
| releaseYear | integer or null | Year of release, where known. |
| albumId | string or null | For songs: their album’s id. |
| albumTitle | string or null | For songs: their album. |
| trackNumber | integer or null | For tracks: position on the disc. |
| discNumber | integer or null | For tracks: which disc. |
| durationSeconds | integer or null | For tracks: length in seconds. |
| isExplicit | boolean | For tracks: marked explicit. |
| previewUrl | string or null | For tracks: Apple’s 30-second preview. |
| isSingle | boolean | For albums: Apple lists it as a single or EP. |
| genre | string or null | Primary genre. |
MusicSearchResults#
One key for each type you asked for.
| Field | Type | Description |
|---|---|---|
| album | array of MusicSummary | |
| artist | array of MusicSummary | |
| song | array of MusicSummary |
Community#
What the Rankd community makes of an item. Private ratings never count.
| Field | Type | Description |
|---|---|---|
| ratingCountalways | integer | How many people rated it publicly. |
| averageRating | number or null | Average rating, 0–100. null with no ratings. |
| distributionalways | array of integer | How many ratings fall in each fifth of the scale, lowest first. |
| reviewCountalways | integer | How many public reviews it has. |
| myRating | object or null | The caller’s own rating. Always null without credentials. |
| myReview | object or null | The caller’s own review. Always null without credentials. |
| snapshot | object or null | The title and artwork Rankd stored, for when the catalogue has nothing. |
MusicItem#
| Field | Type | Description |
|---|---|---|
| musicalways | MusicRef | |
| artworkTemplate | string or null | Artwork with {w}x{h} in place of the size. |
| releaseDate | string or null | Release date, YYYY-MM-DD. |
| releaseYear | integer or null | Release year. |
| genreNames | array of string | Apple’s genres. |
| trackCount | integer or null | For albums: how many tracks. |
| tracks | array of MusicSummary | For albums: the tracklist. |
| artistId | string or null | For albums and songs: the lead artist’s id. |
| albums | array of MusicSummary | For artists: their albums. |
| singles | array of MusicSummary | For artists: their singles and EPs. |
| topSongs | array of MusicSummary | For artists: their most popular songs. |
| similarArtists | array of MusicSummary | For artists: artists like them. |
| album | MusicSummary or null | For songs: the album they are from. |
| about | string or null | Apple’s editorial notes, as plain text. |
| recordLabel | string or null | For albums: the label. |
| copyright | string or null | For albums: the copyright line. |
| durationSeconds | integer or null | Length in seconds. |
| previewUrl | string or null | For songs: Apple’s 30-second preview. |
| motion | object or null | Where Rankd’s apps look for the album’s animated cover. |
| storefront | string | Apple Music storefront. |
| albumId | string | Album id. |
| catalogueAvailablealways | boolean | Whether Apple Music answered. When false, only the details Rankd stored are shown. |
| communityalways | Community |
FoundingMember#
Set when the person is one of Rankd’s Founding Members.
| Field | Type | Description |
|---|---|---|
| number | integer | Their Founding Member number. |
| grantedAt | string (date-time) | When it was granted. |
User#
| Field | Type | Description |
|---|---|---|
| idalways | string | The user’s id. |
| usernamealways | string | Their username. |
| displayName | string or null | The name they show. |
| bio | string or null | Their bio. |
| foundingMember | FoundingMember | |
| avatarAssetId | string or null | Their profile picture, as an asset id. |
| avatarUrl | string or null | Their profile picture’s URL. |
| isDiscoverable | boolean | Whether people who are not signed in can find them. |
| createdAt | string (date-time) or null | When they joined. |
| updatedAt | string (date-time) or null | When their profile last changed. |
UserProfile#
User, plus the rest of the profile.
| Field | Type | Description |
|---|---|---|
| idalways | string | The user’s id. |
| usernamealways | string | Their username. |
| displayName | string or null | The name they show. |
| bio | string or null | Their bio. |
| foundingMember | FoundingMember | |
| avatarAssetId | string or null | Their profile picture, as an asset id. |
| avatarUrl | string or null | Their profile picture’s URL. |
| isDiscoverable | boolean | Whether people who are not signed in can find them. |
| createdAt | string (date-time) or null | When they joined. |
| updatedAt | string (date-time) or null | When their profile last changed. |
| stats | object | Public counts. |
| ratings | integer | Ratings. |
| reviews | integer | Reviews. |
| lists | integer | Lists. |
| followers | integer | Followers. |
| following | integer | Following. |
| pins | array of object | Music pinned to their profile. |
| slot | string | Which favourite slot. One of: album, artist, song |
| position | integer | Order within the slot. |
| music | MusicRef | |
| artworkTemplate | string or null | Artwork with {w}x{h}. |
| achievements | array of object | Achievements they have unlocked. |
| id | string | Which achievement. |
| unlockedAt | string (date-time) or null | When it was unlocked. |
Rating#
| Field | Type | Description |
|---|---|---|
| idalways | string | The rating’s id. |
| musicalways | MusicRef | |
| valuealways | integer | The rating, 0–100. Rankd’s apps show it as stars (value ÷ 20) or as a score out of 100. |
| visibility | string or null | public, or null for ratings made before Rankd had visibility settings (those are public too).One of: public |
| createdAt | string (date-time) or null | When it was made. |
| createdAtPrecision | string | approximate for ratings imported without an exact time.One of: exact, approximate |
| updatedAt | string (date-time) or null | When it last changed. |
Review#
| Field | Type | Description |
|---|---|---|
| idalways | string | The review’s id. |
| userId | string | Who wrote it. |
| usernamealways | string | Their username. |
| music | MusicRef | |
| bodyalways | string | The review. |
| containsSpoilers | boolean | The author marked it as containing spoilers. |
| ratingValue | integer or null | The rating given with it, 0–100. |
| visibility | string | Always public without credentials. |
| createdAt | string (date-time) or null | When it was written. |
| updatedAt | string (date-time) or null | When it last changed. |
ReviewCard#
A review with its author, as music pages and Discover show it.
| Field | Type | Description |
|---|---|---|
| idalways | string | The review’s id. |
| usernamealways | string | The author. |
| displayName | string or null | The author’s display name. |
| avatarUrl | string or null | The author’s profile picture. |
| music | MusicRef | |
| artworkTemplate | string or null | Artwork with {w}x{h}. |
| bodyalways | string | The review. |
| containsSpoilers | boolean | Marked as containing spoilers. |
| ratingValue | integer or null | The rating given with it, 0–100. |
| createdAt | string (date-time) or null | When it was written. |
ListSummary#
| Field | Type | Description |
|---|---|---|
| idalways | string | The list’s id. |
| titlealways | string | Title. |
| kind | string | ranked lists are in order, collections are not, smart lists fill themselves.One of: ranked, collection, smart, collaborative |
| visibility | string | Always public without credentials. |
| emoji | string or null | Its emoji. May be empty. |
| entryCount | integer | How many entries. |
| updatedAt | string (date-time) or null | When it last changed. |
ListResult#
| Field | Type | Description |
|---|---|---|
| idalways | string | The list’s id. |
| ownerUsername | string | Who made it. |
| ownerName | string or null | Their display name. |
| titlealways | string | Title. |
| kind | string | ranked, collection, smart or collaborative. |
| emoji | string or null | Its emoji. May be empty. |
| entryCount | integer | How many entries. |
| covers | array of string | Artwork templates ({w}x{h}) of its first entries. |
| updatedAt | string (date-time) or null | When it last changed. |
List#
| Field | Type | Description |
|---|---|---|
| idalways | string | The list’s id. |
| clientId | string or null | The id the app gave it. Usually the same as id. |
| ownerUserId | string | Who made it. |
| ownerUsername | string | Their username. |
| titlealways | string | Title. |
| description | string or null | Description. |
| kind | string | ranked, collection, smart or collaborative.One of: ranked, collection, smart, collaborative |
| visibility | string | Always public without credentials. |
| emoji | string or null | Emoji. May be empty. |
| icon | string or null | The SF Symbol name Rankd’s apps draw for it. |
| theme | string or null | The colour theme Rankd’s apps draw it in. |
| category | string or null | Category. May be empty. |
| tags | array of string | |
| createdAt | string (date-time) or null | Created. |
| updatedAt | string (date-time) or null | Last changed. |
| entriesalways | array of object | In order. |
| position | integer | Position, from 0. |
| note | string or null | The owner’s note on this entry. |
| music | MusicRef |
PersonResult#
| Field | Type | Description |
|---|---|---|
| usernamealways | string | Username. |
| displayName | string | Display name, or the username when they have none. |
| avatarUrl | string or null | Profile picture. |
| ratingCount | integer | How many ratings they have made. |
Chart#
| Field | Type | Description |
|---|---|---|
| typealways | string | What is charted. One of: album, song, artist, music_video |
| windowalways | string | The period ranked. One of: week |
| generatedAt | string (date-time) | When the chart was worked out. |
| entriesalways | array of object | |
| rank | integer | This week’s position. |
| previousRank | integer or null | Last week’s position. null when new. |
| movement | string | Which way it moved. One of: up, down, same, new |
| change | integer or null | How many places it moved. |
| music | MusicSummary | |
| community | object | |
| average | number | Average rating, 0–100. |
| count | integer | How many ratings. |
| rankedThisWeek | integer | Ratings made this week. |
Discover#
| Field | Type | Description |
|---|---|---|
| trendingAlbums | array of object | |
| music | MusicRef | |
| artworkTemplate | string or null | Artwork with {w}x{h}. |
| ratingCount | integer | Ratings. |
| averageRating | number or null | Average, 0–100. |
| recentReviews | array of ReviewCard | |
| recentLists | array of object | |
| id | string | List id. |
| ownerUsername | string | Owner. |
| ownerDisplayName | string or null | Owner’s display name. |
| title | string | Title. |
| description | string or null | Description. |
| emoji | string or null | Emoji. May be empty. |
| entryCount | integer | Entries. |
| updatedAt | string (date-time) or null | Last changed. |
| activeMembers | array of object | |
| id | string | User id. |
| username | string | Username. |
| displayName | string or null | Display name. |
| avatarUrl | string or null | Profile picture. |
| foundingMember | object or null | |
| number | integer | Founding Member number. |
| ratingCount | integer | Ratings. |
FeedCard#
One card in the feed. type says what it is and which other fields it has. Skip types you do not recognise.
| Field | Type | Description |
|---|---|---|
| idalways | string | The card’s stable id. |
| typealways | string | What kind of card. Today: rating, review, list, trending, new_release, insight and suggested_users. More can be added. |
| createdAt | string (date-time) or null | When the thing it shows happened. |
| reason | string or null | Why it is in the feed, for display. |
| actor | object | Who did it, on cards about someone’s activity. |
| id | string | User id. |
| username | string | Username. |
| displayName | string or null | Display name. |
| avatarUrl | string or null | Profile picture. |
| music | MusicSummary | |
| value | integer or null | On rating and review cards: the rating, 0–100. null for a review given without one. |
| review | object | On review cards: the review. |
| session | object or null | On rating cards: other ratings made at the same sitting. |
| users | array of object | On suggested_users cards: the people suggested. |
| insight | object | On insight cards: the insight. |
| list | object | On list cards: the list. |
| stats | object | On trending and new_release cards: its numbers. |
| period | string | On trending and new_release cards: the period it covers. |
| activityId | string or null | The activity the card shows, when it shows one. |
| engagement | object | Counts of reactions and comments. |