GrooveGauge API examples

Pick an example, add your key and start building. No SDK required.

Attribution is required. Whenever you display, share or reuse API content, include a visible GrooveGauge credit linked to the matching original page. Copyright in our original editorial content remains with GrooveGauge. Read the attribution and AI integration guidance.

Base URL: https://groovegauge.com/en/api/v1

Jump to an example

Your first working request

Need an API key? Start here.

Create a free account and an API key. Confirm your email, choose your first name, username and password, then create a named key for your project.
Replace YOUR_API_KEY in the example below. The key is shown only once when you create it.
Run the example on your server or in your terminal. The next request gets a real review.

Terminal examples use Bash and cURL. Other options: Node.js with built-in fetch, PHP with cURL enabled, or Python 3 using its standard library.

Set GROOVEGAUGE_API_KEY in your server environment. The cURL example includes the export command.

export GROOVEGAUGE_API_KEY='YOUR_API_KEY'

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/en/api/v1/reviews/103'

// quickstart.mjs: run on your server with node quickstart.mjs
const key = process.env.GROOVEGAUGE_API_KEY;
if (!key) throw new Error('Set GROOVEGAUGE_API_KEY first');

const response = await fetch('https://groovegauge.com/en/api/v1/reviews/103', {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(15000),
});
const body = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${body.error?.message ?? 'Request failed'}`);
}

const review = body.data;
console.log(review.title, review.score, 'Source: GrooveGauge', review.url);
console.log('Original editorial text © GrooveGauge');

<?php
// quickstart.php: run on your server with php quickstart.php
$key = getenv('GROOVEGAUGE_API_KEY');
if (!$key) throw new RuntimeException('Set GROOVEGAUGE_API_KEY first');

$request = curl_init('https://groovegauge.com/en/api/v1/reviews/103');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key],
]);
$raw = curl_exec($request);
if ($raw === false) throw new RuntimeException(curl_error($request));
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
curl_close($request);
$body = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException($status . ': ' . ($body['error']['message'] ?? 'Request failed'));
}

$review = $body['data'];
echo $review['title'] . ' | ' . ($review['score'] ?? 'No rating') . ' | Source: GrooveGauge | ' . $review['url'];
echo PHP_EOL . 'Original editorial text © GrooveGauge';

# quickstart.py: run on your server with python3 quickstart.py
import json
import os
import urllib.error
import urllib.request

key = os.environ['GROOVEGAUGE_API_KEY']
request = urllib.request.Request(
    'https://groovegauge.com/en/api/v1/reviews/103',
    headers={'Authorization': f'Bearer {key}'},
)
try:
    with urllib.request.urlopen(request, timeout=15) as response:
        body = json.load(response)
except urllib.error.HTTPError as error:
    detail = json.loads(error.read())
    raise RuntimeError(f"{error.code}: {detail['error']['message']}") from error

review = body['data']
print(review['title'], review['score'], 'Source: GrooveGauge', review['url'])
print('Original editorial text © GrooveGauge')

Keep your key on your server. A website or mobile app should call your own backend; these examples are not for public browser JavaScript.

Shortened response from the API. Expand for the complete snapshot.

{
  "data": {
    "id": 103,
    "title": "The Autumn Effect",
    "type": "album",
    "score": 8.6,
    "score_scale": 10,
    "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
    "api_url": "https://groovegauge.com/en/api/v1/reviews/103"
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Full response

{
  "data": {
    "id": 103,
    "title": "The Autumn Effect",
    "type": "album",
    "score": 8.6,
    "score_scale": 10,
    "excerpt": "The Autumn Effect makes a strong case for atmosphere inside a fairly direct rock song. 10 Years have the heavy guitars and large choruses, but the quieter passages often carry as much interest. A repeating guitar line, a little space around the drums and Jesse Hasek's voice can create tension well before the band increase the volume. Waking Up introduces that balance immediately. The vocal has a…",
    "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
    "api_url": "https://groovegauge.com/en/api/v1/reviews/103",
    "published_at": "2026-01-02T10:00:00+01:00",
    "spotify": {
      "type": "album",
      "id": "1VlMcoG1aI4E4kBIVoH5cp",
      "url": "https://open.spotify.com/album/1VlMcoG1aI4E4kBIVoH5cp"
    },
    "artists": [
      {
        "id": 20,
        "name": "10 Years",
        "url": "https://groovegauge.com/en/artist/bio/10-years",
        "api_url": "https://groovegauge.com/en/api/v1/artists/20",
        "spotify_id": "0REMf7H0VP6DwfZ9MbuWph",
        "spotify_url": "https://open.spotify.com/artist/0REMf7H0VP6DwfZ9MbuWph"
      }
    ],
    "genres": [
      {
        "id": 30,
        "name": "Alternative Metal",
        "slug": "alternative-metal"
      },
      {
        "id": 4,
        "name": "Metal",
        "slug": "metal"
      },
      {
        "id": 23,
        "name": "Post-Grunge",
        "slug": "post-grunge"
      },
      {
        "id": 2,
        "name": "Rock",
        "slug": "rock"
      }
    ],
    "release": {
      "id": 87,
      "title": "The Autumn Effect",
      "type": "album",
      "release_date": "2005-08-16",
      "date_precision": "day",
      "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
      "api_url": "https://groovegauge.com/en/api/v1/releases/87"
    }
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Copy a recipe

All cURL examples use the GROOVEGAUGE_API_KEY environment variable from the first example.

Get the latest album reviews

Use type=single for single reviews. Leave type out to include both.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'type=album' \
  --data-urlencode 'per_page=4' \
  'https://groovegauge.com/en/api/v1/reviews'

Find an artist by name

Start with 10 Years. Use the returned GrooveGauge ID, or follow reviews_url and releases_url.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'q=10 Years' \
  --data-urlencode 'per_page=1' \
  'https://groovegauge.com/en/api/v1/artists'

Shortened response from the API. Expand for the complete snapshot.

{
  "data": [
    {
      "id": 20,
      "name": "10 Years",
      "url": "https://groovegauge.com/en/artist/bio/10-years",
      "api_url": "https://groovegauge.com/en/api/v1/artists/20",
      "spotify_id": "0REMf7H0VP6DwfZ9MbuWph",
      "spotify_url": "https://open.spotify.com/artist/0REMf7H0VP6DwfZ9MbuWph",
      "reviews_url": "https://groovegauge.com/en/api/v1/reviews?artist_id=20",
      "releases_url": "https://groovegauge.com/en/api/v1/releases?artist_id=20"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 1,
    "pages": 1
  },
  "links": {
    "self": "https://groovegauge.com/en/api/v1/artists?page=1&per_page=1&q=10%20Years",
    "next": null,
    "previous": null
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Full response

{
  "data": [
    {
      "id": 20,
      "name": "10 Years",
      "url": "https://groovegauge.com/en/artist/bio/10-years",
      "api_url": "https://groovegauge.com/en/api/v1/artists/20",
      "spotify_id": "0REMf7H0VP6DwfZ9MbuWph",
      "spotify_url": "https://open.spotify.com/artist/0REMf7H0VP6DwfZ9MbuWph",
      "reviews_url": "https://groovegauge.com/en/api/v1/reviews?artist_id=20",
      "releases_url": "https://groovegauge.com/en/api/v1/releases?artist_id=20"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 1,
    "pages": 1
  },
  "links": {
    "self": "https://groovegauge.com/en/api/v1/artists?page=1&per_page=1&q=10%20Years",
    "next": null,
    "previous": null
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Get all reviews and releases for that artist

The previous response gives artist ID 20. These are two separate lists.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'artist_id=20' \
  --data-urlencode 'per_page=4' \
  'https://groovegauge.com/en/api/v1/reviews'

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'artist_id=20' \
  --data-urlencode 'per_page=4' \
  'https://groovegauge.com/en/api/v1/releases'

Look up a Spotify artist, album or track

Use the 22-character ID from the Spotify URL. A Spotify album ID also works for EPs. Only verified matches appear.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'spotify_id=0REMf7H0VP6DwfZ9MbuWph' \
  --data-urlencode 'spotify_type=artist' \
  --data-urlencode 'per_page=3' \
  'https://groovegauge.com/en/api/v1/search'

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'spotify_id=1VlMcoG1aI4E4kBIVoH5cp' \
  --data-urlencode 'spotify_type=album' \
  'https://groovegauge.com/en/api/v1/releases'

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'spotify_id=6pxbcXuvW2GoEjPZP1c84Q' \
  --data-urlencode 'spotify_type=track' \
  'https://groovegauge.com/en/api/v1/releases'

Get an album and its review

The Autumn Effect is release 87. A release has reviews[].score; only review objects have a top-level score. Follow reviews_url for every review.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/en/api/v1/releases/87'

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'release_id=87' \
  'https://groovegauge.com/en/api/v1/reviews'

Shortened response from the API. Expand for the complete snapshot.

{
  "data": {
    "id": 87,
    "title": "The Autumn Effect",
    "type": "album",
    "release_date": "2005-08-16",
    "date_precision": "day",
    "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
    "reviews_url": "https://groovegauge.com/en/api/v1/reviews?release_id=87",
    "spotify": [
      {
        "type": "album",
        "id": "1VlMcoG1aI4E4kBIVoH5cp",
        "url": "https://open.spotify.com/album/1VlMcoG1aI4E4kBIVoH5cp"
      }
    ],
    "reviews": [
      {
        "id": 103,
        "title": "The Autumn Effect",
        "score": 8.6,
        "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect"
      }
    ]
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Full response

{
  "data": {
    "id": 87,
    "title": "The Autumn Effect",
    "type": "album",
    "release_date": "2005-08-16",
    "date_precision": "day",
    "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
    "api_url": "https://groovegauge.com/en/api/v1/releases/87",
    "artists": [
      {
        "id": 20,
        "name": "10 Years",
        "url": "https://groovegauge.com/en/artist/bio/10-years",
        "api_url": "https://groovegauge.com/en/api/v1/artists/20",
        "spotify_id": "0REMf7H0VP6DwfZ9MbuWph",
        "spotify_url": "https://open.spotify.com/artist/0REMf7H0VP6DwfZ9MbuWph"
      }
    ],
    "genres": [
      {
        "id": 30,
        "name": "Alternative Metal",
        "slug": "alternative-metal"
      },
      {
        "id": 4,
        "name": "Metal",
        "slug": "metal"
      },
      {
        "id": 23,
        "name": "Post-Grunge",
        "slug": "post-grunge"
      },
      {
        "id": 2,
        "name": "Rock",
        "slug": "rock"
      }
    ],
    "reviews": [
      {
        "id": 103,
        "title": "The Autumn Effect",
        "score": 8.6,
        "excerpt": "The Autumn Effect makes a strong case for atmosphere inside a fairly direct rock song. 10 Years have the heavy guitars and large choruses, but the quieter passages often carry as much interest. A repeating guitar line, a little space around the drums and Jesse Hasek's voice can create tension well before the band increase the volume. Waking Up introduces that balance immediately. The vocal has a…",
        "url": "https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect",
        "api_url": "https://groovegauge.com/en/api/v1/reviews/103"
      }
    ],
    "reviews_url": "https://groovegauge.com/en/api/v1/reviews?release_id=87",
    "spotify": [
      {
        "type": "album",
        "id": "1VlMcoG1aI4E4kBIVoH5cp",
        "url": "https://open.spotify.com/album/1VlMcoG1aI4E4kBIVoH5cp"
      }
    ]
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Search artists, releases and reviews at once

Search returns three result groups. Each group has its own data, meta and links. Follow a group’s next URL to continue that group.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'q=Haken' \
  --data-urlencode 'per_page=3' \
  'https://groovegauge.com/en/api/v1/search'

const body = await response.json();
const artists = body.data.artists.data;
const releases = body.data.releases.data;
const reviews = body.data.reviews.data;
const nextReviewsPage = body.data.reviews.links.next;

Find genres and filter reviews

Genre 30 is Alternative Metal. Use numeric genre IDs, not translated names. This example selects album reviews.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'per_page=50' \
  'https://groovegauge.com/en/api/v1/genres'

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --data-urlencode 'genre_id=30' \
  --data-urlencode 'type=album' \
  --data-urlencode 'per_page=4' \
  'https://groovegauge.com/en/api/v1/reviews'

Switch between English and Dutch

IDs, artist names, titles and scores are shared. Switch the base URL to choose the language of excerpts and page links. A missing Dutch publication returns no list match or 404 for its detail URL.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/en/api/v1/reviews/103'

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/nl/api/v1/reviews/103'

Read the next page

Follow links.next until it is null. To reuse the loop for /artists, /releases or /genres, change the starting URL and use the filters that endpoint accepts. Remove artist_id=20 to walk the full review index. Fetch one page at a time.

// paginate.mjs: server-side, using the same environment variable
import { setTimeout as sleep } from 'node:timers/promises';
const key = process.env.GROOVEGAUGE_API_KEY;
if (!key) throw new Error('Set GROOVEGAUGE_API_KEY first');

async function getPage(url) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${key}` },
      signal: AbortSignal.timeout(15000),
    });
    if (response.status === 429 && attempt < 2) {
      const seconds = Number(response.headers.get('Retry-After') ?? '5');
      if (!Number.isFinite(seconds) || seconds > 60) {
        throw new Error('Quota reached. Try again later.');
      }
      await sleep(Math.max(1, seconds) * 1000);
      continue;
    }
    const body = await response.json();
    if (!response.ok) throw new Error(`${response.status}: ${body.error?.message}`);
    return body;
  }
}

let url = 'https://groovegauge.com/en/api/v1/reviews?artist_id=20&per_page=50';
while (url) {
  const page = await getPage(url);
  for (const review of page.data) console.log(review.title, 'Source: GrooveGauge', review.url);
  url = page.links.next;
  if (url) await sleep(1100);
}

The pause avoids hammering the API. Limits are shared with your other keys and both languages, so a busy account can still return 429. This example waits briefly, then stops rather than waiting all day for a daily quota reset.

Show a small review card

Use the review’s url for the public link. Escape titles and excerpts as text. The visible GrooveGauge source credit is required, including in apps built with AI. Keep the credit and original score scale beside the content.

The Autumn Effect

8.6/10 · Source: GrooveGauge

The Autumn Effect makes a strong case for atmosphere inside a fairly direct rock song. 10 Years have the heavy guitars and large choruses, but the quieter passages often carry as much interest. A repeating guitar line, a little space around the drums and Jesse Hasek's voice can create tension well before the band increase the volume. Waking Up introduces that balance immediately. The vocal has a…

Original editorial text © GrooveGauge

Read the full review on GrooveGauge

<?php
// review-card.php: serve this file from your PHP backend
$key = getenv('GROOVEGAUGE_API_KEY');
if (!$key) throw new RuntimeException('Set GROOVEGAUGE_API_KEY first');

$request = curl_init('https://groovegauge.com/en/api/v1/reviews/103');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key],
]);
$raw = curl_exec($request);
if ($raw === false) throw new RuntimeException(curl_error($request));
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
curl_close($request);
$body = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException($status . ': ' . ($body['error']['message'] ?? 'Request failed'));
}

$review = $body['data'];

// Render the fetched review as HTML.
function escape_html($value): string {
    return htmlspecialchars((string)$value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
}
$score = $review['score'] === null
    ? 'Not rated'
    : $review['score'] . '/' . $review['score_scale'];
?>
<article>
  <h2><a href="<?= escape_html($review['url']) ?>"><?= escape_html($review['title']) ?></a></h2>
  <p><?= escape_html($score) ?> · Source: <a href="<?= escape_html($review['url']) ?>">GrooveGauge</a></p>
  <p><?= escape_html($review['excerpt']) ?></p>
  <p>Original editorial text © GrooveGauge</p>
  <a href="<?= escape_html($review['url']) ?>">Read the full review on GrooveGauge</a>
</article>

Handle empty results and errors

An empty list is a successful response, not an error. It can mean that the artist is not in the catalogue yet, a filter has no matches, or a Spotify link has not been verified.

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 0,
    "pages": 0
  },
  "links": {
    "self": "https://groovegauge.com/en/api/v1/reviews?page=1&per_page=1&q=NoSuchAlbumExampleQZX",
    "next": null,
    "previous": null
  },
  "attribution": {
    "name": "GrooveGauge",
    "url": "https://groovegauge.com/en/",
    "required": true,
    "instructions": "Whenever you use API content, visibly credit \"Source: GrooveGauge\" beside it and link to the original review, artist or release page in the item's url field. If no item URL is provided, link to GrooveGauge. In plain text, include the full source URL.",
    "copyright": "© GrooveGauge. Copyright in our original editorial content remains with GrooveGauge. API access does not transfer ownership.",
    "ai_instructions": "AI-built integrations and summaries, translations or rewrites must keep the same visible GrooveGauge credit and original-page link. Do not present our editorial content as your own work.",
    "third_party_rights": "Artwork, photographs and third-party provider material remain subject to their respective owners' rights.",
    "terms_url": "https://groovegauge.com/en/api/v1/docs#usage"
  }
}

Read an error

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid positive integer parameter."
  }
}

HTTP	What to do
`400`	Check parameter names, positive IDs and limits. Unknown parameters are rejected.
`401`	Send a valid API key in Authorization: Bearer. A website login cookie is not an API key.
`403`	API access for the account is blocked. Check your account dashboard.
`404`	The resource does not exist or is not published in this language.
`405`	Use GET, HEAD or OPTIONS. The API does not accept writes.
`429`	Wait for the seconds in Retry-After. Do not immediately repeat the request.
`503`	Temporary problem. Wait for Retry-After and retry later.

Inspect status and rate headers

curl --include --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/en/api/v1/reviews?per_page=1'

Default limits: 60 requests per UTC minute, 10 per five-second UTC window and 5,000 per UTC day. Your account dashboard and response headers show your actual limits. All your keys and both languages share the account quota.

RateLimit-Reset is a number of seconds, not a Unix timestamp. Keep X-Request-ID when investigating a failed request.

Use conditional requests

Read ETag from a response and send it in If-None-Match for the same URL. A matching resource returns HTTP 304 with no JSON body. Check the status before calling response.json(). Authentication and quota checks still apply to HEAD and 304 requests.

curl --include --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  'https://groovegauge.com/en/api/v1/reviews/103'

# Replace this with the ETag value from the first response, including its quotes.
GROOVEGAUGE_ETAG='"ETAG_FROM_FIRST_RESPONSE"'
curl --include --silent --show-error \
  --header "Authorization: Bearer $GROOVEGAUGE_API_KEY" \
  --header "If-None-Match: $GROOVEGAUGE_ETAG" \
  'https://groovegauge.com/en/api/v1/reviews/103'

Quick reference

Endpoint	Accepted filters
`/reviews`	page, per_page, q, artist_id, release_id, genre_id, type, spotify_id, spotify_type
`/artists`	page, per_page, q, genre_id, spotify_id, spotify_type=artist
`/releases`	page, per_page, q, artist_id, genre_id, type, spotify_id, spotify_type
`/genres`	page, per_page
`/search`	page, per_page, q, spotify_id, spotify_type

GET /reviews/103, /artists/20, /releases/87 and /genres/30 return one object in data. Detail URLs accept no query parameters.
Lists return an array in data, with meta, links and attribution. Default per_page=20, maximum 50. Search defaults to 10 per group, maximum 20. page is 1 to 10,000.
q is a literal, case-insensitive substring of 2 to 120 characters. Search requires q or spotify_id. spotify_type requires spotify_id.
Review types: album, single. Release types also include ep, live and compilation.
A GrooveGauge ID is an integer. A Spotify ID is a 22-character string. Keep them separate.
A review score is a number or null, on a scale of 10. A release without a review has reviews: []; never treat that as a zero score.
Review excerpts contain at most 400 Unicode characters including the ellipsis. Short reviews expose at most 60% of their text; under 40 characters the excerpt is empty. Full review text is not available through the API.
Dates use their known precision. release_date can be a year, a month, a full date or null. Check date_precision. published_at is the review publication date.
A release’s url points to its review when one is published, otherwise to its release page. Related artist links may use English while a Dutch bio is unavailable. JSON field names remain English.
Data endpoints and the JSON API index require a Bearer key. These docs, the OpenAPI file and OPTIONS preflight requests are public. Only GET, HEAD and OPTIONS are supported.

Download the OpenAPI specification with request and response examples

Attribution, copyright and AI tools

Every use of content from this API requires attribution to GrooveGauge. Put a visible GrooveGauge credit beside each review excerpt, score, artist description or release item you display, share or reuse. Link it to that item’s original GrooveGauge page using its url. Use the homepage only when no item-specific page is available. A credit hidden in code, JSON, an About page or a general footer does not replace the credit beside the content.

If an output cannot contain clickable links, include the original page URL in plain text. Keep the attribution when exporting or sharing content elsewhere.

Copyright in GrooveGauge’s original editorial texts remains with GrooveGauge. Access to the API does not transfer that copyright or make these texts public domain. Artwork, photographs, artist names and information supplied by other providers remain subject to their own rights; GrooveGauge does not claim ownership of them.

Building with AI

The same source requirement applies to apps built with AI and to AI-generated summaries, translations or rewrites based on our content. Preserve the GrooveGauge credit and original page link when you shorten, reformat, translate or paraphrase. Keep your own adaptations clearly separate from our original text.

Include the following instruction when asking an AI tool to build your integration:

Whenever this integration displays, shares or reuses GrooveGauge API content,
show a visible "Source: GrooveGauge" credit beside each item and link it to
that item's original GrooveGauge page using its url field, not its API URL.
Preserve this credit and link in summaries, translations, rewrites and exports.
Copyright in GrooveGauge's original editorial text remains with GrooveGauge.
If an output cannot contain links, include the original page URL as plain text.

A credit you can copy

This link belongs next to the content it credits. Replace the example URL with the item’s returned url.

<p>
  Source: <a href="https://groovegauge.com/en/album-reviews/10-years-the-autumn-effect">GrooveGauge</a>
  · Original editorial text © GrooveGauge
</p>

Each successful data response includes an attribution object. Pass it through your backend and preserve it in cached or exported responses. Your interface must still render the source credit and original page link for the reader.

Keep scores on their original scale of 10. The API provides compact metadata and review previews, not full articles, biographies or submission/contact details.

Your API dashboard shows usage, errors, rate limits, response times and cache hits. Request details are kept for 30 days and daily totals for 366 days. API logs do not store raw keys, authorization headers or search text; IP addresses are stored only as keyed hashes.

JSON examples are snapshots of published data. Results and totals can change as the catalogue grows.