Identify a Song from an Audio File with One API Call

What identify does

POST /v1/tracks/identifytakes an audio fingerprint (or a raw audio file) and returns the catalogue tracks it matches, best match first. It's the request-response, one-shot counterpart to a live stream monitor: give it a few seconds of a recording and it tells you what the recording is. Under the hood it matches against a Beatport catalogue and AcoustID; it's a single fingerprint lookup with a tight error-tolerance ceiling, so a returned match is a confident one.

It's a paid-tier endpoint; the free tier gets a 403. The response is deliberately minimal (id, title, artists, confidence); you hydrate the full metadata in a cheap second call once you know which track matched.

Two ways to call it

There are two modes, chosen by Content-Type. They resolve to the same matcher and return the same shape:

• Fingerprint mode (JSON): you run Chromaprint locally, then POST the resulting integer array. Roughly 1 KB on the wire, a flat 10 credits. This is the mode to prefer.
• Raw-audio mode: POST the file bytes (up to 100 MB) with Content-Type: application/octet-stream and the server fingerprints it for you. Zero client-side setup, but it ships the whole file and costs 10 + ceil(MB).

# Chromaprint's CLI - one static binary, no service to run
$ fpcalc -raw track.mp3
DURATION=270
FINGERPRINT=1809491111,1809487015,1810011303, … ,1739372152

import { execSync } from "node:child_process";

// Decode + fingerprint locally, then post ~1 KB of integers.
const raw = execSync("fpcalc -raw track.mp3", { encoding: "utf8" });
const line = raw.split("\n").find(l => l.startsWith("FINGERPRINT="))!;
const fingerprint = line.slice("FINGERPRINT=".length).split(",").map(Number);

const res = await fetch(`${BASE}/v1/tracks/identify`, {
  method:  "POST",
  headers: { "content-type": "application/json", "x-api-key": API_KEY },
  body:    JSON.stringify({ fingerprint, fingerprint_duration: 270 }),
});
const out = await res.json();

{
  "matched": true,
  "results": [
    {
      "id": "315587019",
      "title": "Digital Love",
      "artists": [
        { "id": 1925615, "name": "Daft Punk", "is_primary": true, "is_remixer": false }
      ],
      "confidence": 0.97
    }
  ],
  "credits_charged": 10
}

// The identify response is slim - pull the full record by id.
const id = out.results[0].id;

const track = await fetch(`${BASE}/v1/tracks/${id}`, {
  headers: { "x-api-key": API_KEY },
}).then(r => r.json());

// track.isrc          → the representative ISRC (may be null)
// track.genre         → ["House", …]
// track.duration      → seconds
// track.releases[0]   → { title, label: { name }, release_date }

The zero-setup alternative

If you can't run Chromaprint where the audio lives (a serverless function, a locked-down mobile runtime), skip step 1 and POST the bytes directly:

// No Chromaprint on your side? Post the bytes and let the server fingerprint.
await fetch(`${BASE}/v1/tracks/identify`, {
  method:  "POST",
  headers: { "content-type": "application/octet-stream", "x-api-key": API_KEY },
  body:    await readFile("clip.mp3"),  // ≤ 100 MB · costs 10 + ceil(MB)
});

Same response, same hydration path. On a miss the server quietly retries deeper 30-second windows of your clip before giving up, so a recording that only becomes recognisable a minute in still resolves.

Handling misses and errors

• No match. matched is false and resultsis empty. The recording isn't in the catalogue, or the clip was too short / too noisy to fingerprint.
• 429.The request would cost more credits than you have left this month. It's rejected before any matcher work, so a denied identify never burns credits.
• 503 with Retry-After.The matcher is briefly unreachable (e.g. mid-deploy). Wait the header's seconds and retry the same request; it's idempotent.
• 413. The upload exceeded 100 MB. Send a shorter clip, or fingerprint it client-side and use the JSON mode instead.