API Documentation

RESTful API powered by PostgREST

Base URL https://data.nimvector.cc

Quick Start

# Get database statistics

curl "https://data.nimvector.cc/api_stats"

# Search for artists

curl "https://data.nimvector.cc/rpc/text_search_artists?query=beatles&lim=10"

# Universal search (artists, albums, tracks)

curl "https://data.nimvector.cc/rpc/text_search_all?query=love&lim=5"

Endpoints

GET /artist_vectors

Get artists with pagination and filtering

Query Parameters:

select Fields to return (e.g., id,name,popularity)
limit Max results (default: 100, max: 1000)
offset Skip N results for pagination
order Sort order (e.g., popularity.desc)
name Filter by name (e.g., name=ilike.*beatles*)

# Example: Top 10 artists by popularity

curl "https://data.nimvector.cc/artist_vectors?select=id,name,followers,popularity&order=popularity.desc&limit=10"

GET /album_vectors

Get albums with pagination and filtering

Available Fields:

id, name, release_date, total_tracks, popularity, album_type, label

# Example: Recent albums

curl "https://data.nimvector.cc/album_vectors?select=id,name,release_date&order=release_date.desc&limit=20"

GET /track_vectors

Get tracks with pagination and filtering

Available Fields:

id, name, album_id, duration_ms, popularity, isrc, explicit, track_number

# Example: Most popular tracks

curl "https://data.nimvector.cc/track_vectors?select=id,name,popularity&order=popularity.desc&limit=50"

GET /audio_features

Get audio analysis features for tracks

Available Fields:

track_id, danceability, energy, key, loudness, mode, speechiness, acousticness, instrumentalness, liveness, valence, tempo, duration_ms, time_signature

# Example: High energy tracks

curl "https://data.nimvector.cc/audio_features?energy=gte.0.9&order=energy.desc&limit=20"

Search Functions (RPC)

RPC /rpc/text_search_all

Search across all entities (artists, albums, tracks)

Parameters:

query Search term (required)
lim Results per category (default: 10)

curl "https://data.nimvector.cc/rpc/text_search_all?query=love&lim=5"

RPC /rpc/text_search_artists

Search artists by name

curl "https://data.nimvector.cc/rpc/text_search_artists?query=taylor&lim=10"

RPC /rpc/text_search_albums

Search albums by name

curl "https://data.nimvector.cc/rpc/text_search_albums?query=greatest%20hits&lim=10"

RPC /rpc/text_search_tracks

Search tracks by name

curl "https://data.nimvector.cc/rpc/text_search_tracks?query=yesterday&lim=20"

Code Examples

Python

import requests

BASE_URL = "https://data.nimvector.cc"

# Search for artists
response = requests.get(f"{BASE_URL}/rpc/text_search_artists", params={
    "query": "beatles",
    "lim": 10
})
artists = response.json()

# Get top tracks
response = requests.get(f"{BASE_URL}/track_vectors", params={
    "select": "id,name,popularity",
    "order": "popularity.desc",
    "limit": 100
})
tracks = response.json()

# Filter by audio features
response = requests.get(f"{BASE_URL}/audio_features", params={
    "danceability": "gte.0.8",
    "energy": "gte.0.8",
    "limit": 50
})
danceable_tracks = response.json()

JavaScript

const BASE_URL = "https://data.nimvector.cc";

// Search for artists
const searchArtists = async (query) => {
    const res = await fetch(`${BASE_URL}/rpc/text_search_artists?query=${query}&lim=10`);
    return res.json();
};

// Get top tracks with pagination
const getTopTracks = async (page = 0, pageSize = 50) => {
    const res = await fetch(
        `${BASE_URL}/track_vectors?select=id,name,popularity` +
        `&order=popularity.desc&limit=${pageSize}&offset=${page * pageSize}`
    );
    return res.json();
};

// Universal search
const searchAll = async (query) => {
    const res = await fetch(`${BASE_URL}/rpc/text_search_all?query=${query}&lim=10`);
    return res.json();
};

Rate Limits & Notes

  • - Maximum 1000 rows per request
  • - Request timeout: 60 seconds
  • - CORS enabled for all origins
  • - Vector similarity search available when embeddings are complete