MeloData API

curl -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  https://melodata.voltenworks.com/api/v1/tracks/USRC17607839/features

melo_sk_{64 hex characters}    # 72 characters total

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "features": { ... }
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "quota": {
      "used": 4521,
      "limit": 25000,
      "resets_at": "2026-05-01T00:00:00Z"
    }
  }
}

{
  "error": {
    "message": "Invalid API key",
    "status": 401
  },
  "meta": {
    "request_id": "req_f6e5d4c3b2a1"
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "artist": "Queen",
    "features": {
      "bpm": 143.8,
      "key": "Bb",
      "key_confidence": 0.87,
      "energy": 0.72,
      "danceability": 0.39,
      "valence": 0.23,
      "acousticness": 0.28,
      "loudness": -7.2,
      "instrumentalness": 0.01,
      "speechiness": 0.05,
      "liveness": 0.24,
      "time_signature": 4
    }
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "quota": { "used": 4521, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" }
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "status": "analyzing",
    "estimated_seconds": 30
  },
  "meta": {
    "request_id": "req_c3d4e5f6a1b2"
  }
}

{
  "data": {
    "isrc": "XX1234567890",
    "status": "unavailable",
    "reason": "No audio source found for analysis. This track may be unreleased, region-locked, or have an incorrect ISRC."
  }
}

{
  "data": {
    "isrc": "USRC17607839",
    "title": "Bohemian Rhapsody",
    "artist": "Queen",
    "artist_id": "0383dadf-2a4e-4d10-a46a-e9e041da8eb3",
    "album": "A Night at the Opera",
    "release_date": "1975-10-31",
    "duration_ms": 354320,
    "genres": ["rock", "classic rock", "progressive rock"]
  },
  "meta": {
    "request_id": "req_d4e5f6a1b2c3",
    "quota": { "used": 4522, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" }
  }
}

{
  "data": {
    "results": [
      {
        "isrc": "USRC17607839",
        "title": "Bohemian Rhapsody",
        "artist": "Queen",
        "album": "A Night at the Opera",
        "release_date": "1975-10-31"
      },
      {
        "isrc": "GBARL9300135",
        "title": "Bohemian Rhapsody (Live)",
        "artist": "Queen",
        "album": "Live at Wembley",
        "release_date": "1992-05-25"
      }
    ],
    "pagination": {
      "offset": 0,
      "limit": 20,
      "count": 2
    }
  },
  "meta": { "request_id": "req_e5f6a1b2c3d4", "quota": { "used": 4523, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

curl -G https://melodata.voltenworks.com/api/v1/tracks/resolve \
  -H "Authorization: Bearer melo_sk_your_key_here" \
  --data-urlencode "title=Bohemian Rhapsody" \
  --data-urlencode "artist=Queen"

{
  "data": {
    "query": { "title": "Bohemian Rhapsody", "artist": "Queen" },
    "isrc": "GBUM71029604",
    "matched": {
      "title": "Bohemian Rhapsody",
      "artist": "Queen",
      "album": "A Night at the Opera",
      "release_date": "1975-10-31"
    },
    "confidence": 1,
    "confidence_level": "exact",
    "warning": null,
    "source": "catalog",
    "cached": false,
    "providers": { "deezer": "not_tried", "itunes": "not_tried" },
    "analysis_queued": false
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6", "quota": { "used": 4524, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

{
  "data": {
    "id": "0383dadf-2a4e-4d10-a46a-e9e041da8eb3",
    "name": "Queen",
    "sort_name": "Queen",
    "country": "GB",
    "genres": ["rock", "classic rock", "glam rock"],
    "track_count": 187
  },
  "meta": { "request_id": "req_f6a1b2c3d4e5", "quota": { "used": 4524, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

curl -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/recommendations?seed=USRC17607839&seed=GBAYE0601498&target_energy=0.8&limit=5"

{
  "data": {
    "recommendations": [
      {
        "isrc": "GBAYE0601498",
        "title": "Don't Stop Me Now",
        "artist": "Queen",
        "match_score": 0.91,
        "features": { "bpm": 156.2, "energy": 0.84, "danceability": 0.55, "valence": 0.68 }
      },
      {
        "isrc": "USIR10211015",
        "title": "Mr. Brightside",
        "artist": "The Killers",
        "match_score": 0.86,
        "features": { "bpm": 148.1, "energy": 0.78, "danceability": 0.42, "valence": 0.31 }
      }
    ],
    "seed_count": 2
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6", "quota": { "used": 4525, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

{
  "isrcs": ["USRC17607839", "GBAYE0601498", "XX0000000000"]
}

{
  "data": {
    "tracks": [
      {
        "isrc": "USRC17607839",
        "title": "Bohemian Rhapsody",
        "artist": "Queen",
        "features": { "bpm": 143.8, "key": "Bb", "energy": 0.72, "danceability": 0.39, ... }
      },
      {
        "isrc": "GBAYE0601498",
        "title": "Don't Stop Me Now",
        "artist": "Queen",
        "features": { "bpm": 156.2, "key": "F", "energy": 0.84, "danceability": 0.55, ... }
      },
      {
        "isrc": "XX0000000000",
        "status": "not_found"
      }
    ]
  },
  "meta": { "request_id": "req_b2c3d4e5f6a1", "quota": { "used": 4528, "limit": 25000, "resets_at": "2026-05-01T00:00:00Z" } }
}

{
  "isrcs": ["ISRC1", "ISRC2", "ISRC3", "ISRC4", "ISRC5"]
}

{
  "data": {
    "queued": 3,
    "already_analyzed": 1,
    "already_queued": 1,
    "total": 5
  },
  "meta": { "request_id": "req_c3d4e5f6a1b2" }
}

{
  "data": {
    "isrc": "XX1234567890",
    "status": "queued_for_reanalysis",
    "estimated_seconds": 30
  }
}

async function getFeatures(isrc) {
  const res = await fetch(
    `https://melodata.voltenworks.com/api/v1/tracks/${isrc}/features`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  if (res.status === 202) {
    const retryAfter = res.headers.get("Retry-After") || 30;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return getFeatures(isrc); // retry, will be a cache hit
  }

  return res.json();
}

// POST https://your-app.com/webhooks/melodata
{
  "event": "track.analyzed",
  "data": {
    "isrc": "USRC17607839",
    "features": {
      "bpm": 143.8,
      "key": "Bb",
      "energy": 0.72,
      "danceability": 0.39,
      "valence": 0.23,
      ...
    }
  }
}

// Step 1: Pre-warm the cache (free, no billed lookups)
await fetch("https://melodata.voltenworks.com/api/v1/tracks/batch/analyze", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    isrcs: ["ISRC1", "ISRC2", "ISRC3", "ISRC4", "ISRC5"],
  }),
});

// Step 2: Wait for analysis (30-60 seconds)
await new Promise((r) => setTimeout(r, 60000));

// Step 3: Query features, most will be instant cache hits
for (const isrc of isrcs) {
  const res = await fetch(
    `https://melodata.voltenworks.com/api/v1/tracks/${isrc}/features`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const data = await res.json();
  // process features...
}

const API_KEY = process.env.MELODATA_API_KEY;
const BASE = "https://melodata.voltenworks.com/api/v1";

// Basic feature lookup with 202 handling
async function getFeatures(isrc) {
  const res = await fetch(`${BASE}/tracks/${isrc}/features`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (res.status === 202) {
    const wait = Number(res.headers.get("Retry-After") || 30);
    console.log(`Track ${isrc} is being analyzed. Retrying in ${wait}s...`);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return getFeatures(isrc);
  }

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${res.status}: ${err.error.message}`);
  }

  return res.json();
}

// Batch lookup
async function batchFeatures(isrcs) {
  const res = await fetch(`${BASE}/tracks/batch/features`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ isrcs }),
  });

  return res.json();
}

// Usage
const { data } = await getFeatures("USRC17607839");
console.log(`BPM: ${data.features.bpm}, Key: ${data.features.key}`);

import os
import time
import requests

API_KEY = os.environ["MELODATA_API_KEY"]
BASE = "https://melodata.voltenworks.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def get_features(isrc: str) -> dict:
    """Get audio features for a track. Handles 202 retry automatically."""
    res = requests.get(f"{BASE}/tracks/{isrc}/features", headers=HEADERS)

    if res.status_code == 202:
        wait = int(res.headers.get("Retry-After", 30))
        print(f"Track {isrc} analyzing. Retrying in {wait}s...")
        time.sleep(wait)
        return get_features(isrc)

    res.raise_for_status()
    return res.json()


def batch_features(isrcs: list[str]) -> dict:
    """Batch lookup for up to 50 ISRCs."""
    res = requests.post(
        f"{BASE}/tracks/batch/features",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"isrcs": isrcs},
    )
    res.raise_for_status()
    return res.json()


# Usage
data = get_features("USRC17607839")
print(f"BPM: {data['data']['features']['bpm']}")
print(f"Key: {data['data']['features']['key']}")

# Get features for a single track
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  https://melodata.voltenworks.com/api/v1/tracks/USRC17607839/features | jq .

# Search for tracks
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/tracks/search?q=bohemian+rhapsody&limit=5" | jq .

# Batch feature lookup
curl -s -X POST \
  -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isrcs":["USRC17607839","GBAYE0601498"]}' \
  https://melodata.voltenworks.com/api/v1/tracks/batch/features | jq .

# Get recommendations from seed tracks
curl -s -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  "https://melodata.voltenworks.com/api/v1/recommendations?seed=USRC17607839&seed=GBAYE0601498&limit=10" | jq .

# Pre-analyze a batch (free)
curl -s -X POST \
  -H "Authorization: Bearer melo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isrcs":["ISRC1","ISRC2","ISRC3"]}' \
  https://melodata.voltenworks.com/api/v1/tracks/batch/analyze | jq .

// 401 Unauthorized
{
  "error": {
    "message": "Missing or invalid Authorization header",
    "status": 401
  },
  "meta": {
    "request_id": "req_f6a1b2c3d4e5"
  }
}

// 429 Rate Limited
{
  "error": {
    "message": "Rate limit exceeded",
    "status": 429
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6"
  }
}
// Headers: X-RateLimit-Reset: 1711234567

// 429 Quota Exceeded
{
  "error": {
    "message": "Monthly quota exceeded. Upgrade your plan or enable overage billing.",
    "status": 429
  },
  "meta": {
    "request_id": "req_b2c3d4e5f6a1"
  }
}
// Headers: X-Quota-Used: 25000, X-Quota-Limit: 25000