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.

Each example below is editable. Change the path and press Enter to send your own request.

Artists

GET /group/:name 24h

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

Each entry in members[] carries both scripts: name is whatever MusicBrainz holds, usually Hangul, and latinName is the Wikidata label, usually Latin. Members are matched to Wikidata by MusicBrainz id (P434), not by name, so a member with no Wikidata entry keeps latinName: null rather than being mismatched.

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.

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.

Add ?members=true to get the group's own photos plus a members[] array, each entry with its own photos, count, mbid, and qid. Members are read from Wikidata P527, so a soloist returns members: []. Measured across 15 groups: 100 of 101 members resolved at least one photo.

Releases

GET /discography/:artist 12h

Albums, EPs, and singles by an artist, newest first. Takes a group or idol name, or their mbid. limit defaults to 25 and caps at 100; offset pages through total.

Check total against count before assuming you have everything - BTS has 101 release groups, so a single page never covers the whole catalogue.

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.

GET /cover/:album 24h

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

Browse

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.

GET /category/:id 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.

Meta

GET /health -

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

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 latinName and wikidata.members[].name are usually Latin script; both are kept deliberately because each is correct in its own source. Paginated endpoints return total, limit, offset, and count - compare total with count to know whether more pages exist. Every response allows CORS from any origin, and OPTIONS preflight returns 204. Unknown routes return 404.