GrooveGauge / Developers

Public Music API

Use GrooveGauge reviews and music links in your own projects. Create your free GrooveGauge account and use an API key to request data. Responses contain compact metadata, scores and short review previews, with links to the full pages.

Attribution is required: display “GrooveGauge” with a clickable link to the original review or artist page next to the data you use. Keep the original score scale of 10. Full reviews, biographies, research and contact details are outside this API.

Base URL: https://groovegauge.com/en/api/v1. Download the OpenAPI specification.

Account and API key

Create your account or sign in to manage API keys. Verify the email link, then create a named key for your project. Your secret key is shown once. Keep it on your server and never put it in URLs or public JavaScript. Revoke a key immediately if it is exposed.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://groovegauge.com/en/api/v1/reviews?per_page=4"

All data endpoints, including the JSON API index, require the Authorization header. This documentation, the OpenAPI file and OPTIONS preflight requests remain public.

Language

The API now uses language subdirectories. Set your project’s base URL to https://groovegauge.com/en/api/v1 for English or https://groovegauge.com/nl/api/v1 for Dutch. Call these URLs directly instead of relying on the legacy domain redirects.

Use groovegauge.com/en/ for English review previews and page links, or groovegauge.com/nl/ for Dutch. The two versions share IDs, names, titles and scores. Dutch lists contain published Dutch versions only, with no English review-text fallback. Related artist links can point to English until a Dutch bio is published. Content-Language identifies the response language. Rate limits are shared across both language versions.

Resources

Search and pagination

List endpoints accept page (default 1) and per_page (default 20, maximum 50). Follow the absolute links.next URL until it is null. Search defaults to 10 results per group, maximum 20. IDs are GrooveGauge IDs, unless a parameter explicitly says Spotify.

Use q for an artist name or title (2–120 characters). Matching is a literal, case-insensitive substring. Spotify search uses spotify_id, optionally with spotify_type=artist, album or track. Unverified or held Spotify IDs never appear or match. An empty result can therefore mean that we have not verified the connection yet.

Reviews and releases also accept artist_id, genre_id and type. Reviews additionally accept release_id; review types are album and single. Release types also include ep, live and compilation. Artists accept genre_id. Detail resources accept no query parameters. Unknown parameters return 400.

A release keeps its own stable ID and API URL. Its public url points directly to our published review when one is available, or to the release guide otherwise. Review publication and original release dates are separate.

Content limits

A review excerpt is always the same opening fragment, in plain text, with at most 400 Unicode characters including the ellipsis. Short reviews return at most 60% of their visible text; texts shorter than 40 characters return an empty excerpt. There is no full-text, length, offset, export or expansion parameter. Catalogue entries without a review have no invented score. Dates respect their known precision: a year can be 2015, rather than a made-up exact day.

Examples

curl -H "Authorization: Bearer YOUR_API_KEY" 'https://groovegauge.com/en/api/v1/artists?q=10%20Years'
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://groovegauge.com/en/api/v1/search?spotify_id=0REMf7H0VP6DwfZ9MbuWph&spotify_type=artist'
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://groovegauge.com/en/api/v1/reviews?type=album&per_page=20&page=1'

const response = await fetch(
  'https://groovegauge.com/en/api/v1/reviews?q=Anathema'
);
if (!response.ok) throw new Error(`GrooveGauge: ${response.status}`);
const { data, links } = await response.json();
for (const review of data) {
  const link = document.createElement('a');
  link.href = review.url;
  link.textContent = `${review.title} · ${review.score}/10 · GrooveGauge`;
  document.body.append(link);
  const excerpt = document.createElement('p');
  excerpt.textContent = review.excerpt;
  document.body.append(excerpt);
}

Limits and errors

Default limits are 60 requests per UTC minute, 10 per five-second UTC window and 5,000 per UTC day, shared by all keys on an account and both sites. Keys also have the same limits individually. Network protection allows 1200 requests per rolling minute and 200 per five seconds per IP; unauthenticated failures are limited to 60 per minute and 10 per five seconds. A limit returns 429 and Retry-After in seconds. Read RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Day-Limit and X-RateLimit-Day-Remaining. Your dashboard shows your actual account limits. Data may be served from a shared 30-second server cache, but authentication is checked on every request, including ETag requests. Client responses use Cache-Control: private, no-store.

GET and HEAD read data. OPTIONS describes allowed methods. CORS supports the Authorization header; browser cookies are not used for API authentication. Errors use JSON {"error":{"code":"…","message":"…"}}: 400 for invalid parameters, 401 for missing, invalid or revoked API keys, 403 for blocked API access, 404 for missing or unpublished resources, 405 for unsupported methods, 429 for rate limits, and 503 for temporary unavailability. IDs and canonical URLs remain the integration reference; do not assume that the order or total number of records stays fixed during publication.

Usage and privacy

Your API dashboard shows daily requests, endpoints, HTTP results, rate-limit errors, response times and cache hits. Request details are retained for 30 days and daily totals for 366 days. API logs never store authorization headers, raw keys or search text. IP addresses are recorded only as a keyed hash. Existing anonymous usage cannot be reconstructed; statistics start when this system is enabled.