Rippl3 Music Similarity API

Ranked similar songs, pairwise similarity scores, and search — from audio embeddings.

Getting Started

The Rippl3 music similarity API returns nearest-neighbor tracks and pairwise similarity scores from audio embeddings. Endpoints are public with tiered rate limits. Authentication is optional but unlocks higher limits and premium features.

Base URL

https://api.rippl3.net/v1/public/

Authentication

Optional — required for higher rate limits and premium features.

Authorization: Bearer <your_api_key>

Permanent API key (recommended): Never expires — ideal for scripts and apps.
Short-lived JWT tokens also work but expire in ~15 minutes.

Logged-in users can generate and manage their permanent API key in the next section.

Rate Limits & API Keys

Rate Limits

  • Anonymous: 20 requests per hour(your current tier)
  • Registered (Free): 1,000 requests per day
  • Premium: Unlimited(upgrade)

Endpoints

Get Similar Songs

GET/recommendations/similar/{song_id}/

Retrieve songs similar to the given song ID using cosine similarity on audio embeddings.

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoMax songs to return (default: 10; max 10 for free/anon, max 1000 for premium)
min_similarityfloatNoMinimum similarity threshold (default: 0.0; only premium users can set > 0)

Response

{
  "recommended_songs": [
    {
      "id": 123,
      "title": "Song Title",
      "artist": "Artist Name",
      "cover_art": "https://...",
      "permalink_url": "https://soundcloud.com/..."
    }
  ]
}

Examples

Basic (no auth)

curl "https://api.rippl3.net/api/v1/public/recommendations/similar/123/"

Authenticated (higher limits + premium filters)

curl -H "Authorization: Bearer <your_api_key>" \
  "https://api.rippl3.net/api/v1/public/recommendations/similar/123/?limit=500&min_similarity=0.8"

Pairwise Similarity

GET/similarity-pair/

Compute cosine similarity (0–1) between any two songs — by ID or search string.

Query Parameters

ParameterTypeRequiredDescription
song1stringYesSong ID or search query
song2stringYesSong ID or search query

Examples

By ID

curl "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=123&song2=456"

By search string

curl "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=Never+Gonna+Give+You+Up&song2=Careless+Whisper"

Authenticated

curl -H "Authorization: Bearer <your_api_key>" \
  "https://api.rippl3.net/api/v1/public/similarity-pair/?song1=123&song2=456"

Submit Similarity Rating (Help Improve the Model)

POST/rate-pair/

Submit a human similarity rating (1–10) for any song pair. This data helps train and improve the recommendation model.

Request Body (JSON)

{
  "song1_id": 123,
  "song2_id": 456,
  "rating": 8   // integer 1–10
}

Example

curl -X POST "https://api.rippl3.net/api/v1/public/rate-pair/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{"song1_id": 123, "song2_id": 456, "rating": 8}'

Authentication optional (same rate limits apply). Higher-rated pairs influence future recommendations.