K-pop API

Groups, idols, discographies, album covers, licensed photos, and categories from open data sources. Base URL /api/kpop.

Uncached calls are slow on purpose: MusicBrainz allows 1 request per second and requests are serialized. Repeat calls are served from KV. Watch the cache value in each response below.

Every endpoint below accepts either a name or a MusicBrainz id. Names cost one extra lookup and resolve to the top match, so an ambiguous name can silently return the wrong artist. Ids are exact and faster - prefer them once you have one.

Endpoints

GET /group/:name 24h

Group details, members, external links, and genres. Searches Korean artists by name and returns the best match.

/api/kpop/group/aespa

GET /idol/:idol 24h

Idol details and group membership history. Takes a stage name or an mbid from members[] of a group response. Stage names are reused across groups, so this is the endpoint where a name is most likely to be ambiguous - use the mbid when it matters.

/api/kpop/idol/cb8a4667-...

GET /discography/:artist 12h

Albums, EPs, and singles by an artist, newest first. Takes a group or idol name, or their mbid.

/api/kpop/discography/aespa

GET /album/:album 24h

Release group metadata and tracklist. Takes a release group id, or artist/title - the artist is required because album titles are not unique across the database. When several releases share a title, the one with a real release type wins over Other, then the earliest release date.

/api/kpop/album/aespa/Armageddon

GET /cover/:album 24h

Cover art URLs at 250, 500, and 1200px. Takes the same release group id or artist/title as /album.

/api/kpop/cover/aespa/Armageddon

GET /photos/:artist 24h

Licensed artist photos from Wikimedia Commons, resolved through the artist's Wikidata entity (P18 image and P373 Commons category). Each photo carries credit, license, licenseUrl, and descriptionUrl; you must keep that attribution when you display the image.

Coverage is thin. Many artists have no free image at all, which returns 200 with photos: [] rather than an error. Only bitmap images are returned - Commons categories also hold video and audio, and P154 logos are vector, so both are excluded. Up to 20 photos per artist. Takes a name or an mbid, for a group or an individual member.

/api/kpop/photos/aespa

GET /categories 24h

The category list. Every category is derived from MusicBrainz fields this API already reads - artist type, gender, country, tags, and life-span - and each one exposes the exact filters used to build its query. Gender is never inferred from a name.

Group entities in MusicBrainz carry no gender, so girl and boy groups come from the girl group and boy group tags rather than from gender. That means tag coverage, not chart reality, decides the counts.

/api/kpop/categories

GET /category/:id?q=&limit=&offset= 1h

Artists in one category, always constrained to country:KR. Optional q narrows within the category. limit defaults to 25 and caps at 50; offset pages through total. Unknown id returns 404, a bad limit or offset returns 400.

/api/kpop/category/girl-groups?limit=5

GET /health -

Health check. kv reports whether the KPOP_CACHE namespace binding is present.

/api/kpop/health

Data flow

You can jump straight in with a name:

  1. /group/aespa, /discography/aespa, /photos/aespa.
  2. /album/aespa/Armageddon and /cover/aespa/Armageddon - the artist prefix is required.
  3. Or browse: /categories, then /category/:id.

Or chain ids, which is exact and skips one lookup per call:

  1. Start with /group/:name.
  2. Use mbid from that response for /discography and /photos.
  3. Use members[].mbid for /idol.
  4. Use albums[].id for /album and /cover.

Photo credits

Photos come from Wikimedia Commons under their own individual licences, which differ per file - typically Creative Commons variants, occasionally public domain. This API returns the author, licence name, licence URL, and Commons file page for every photo, and files whose licence cannot be resolved are dropped instead of served unlabelled. Reusing an image means honouring its licence yourself: for CC BY that includes naming the author and the licence. No photos are hosted here.

Notes

Track lengths are in milliseconds (lengthMs). Member names from MusicBrainz may be Hangul while wikidata.members[].name is usually Latin script; both are kept deliberately because each is correct in its own source. Every response allows CORS from any origin, and OPTIONS preflight returns 204. Unknown routes return 404.