How to Get a Specific Exercise by ID from the Exercises Dataset API

To retrieve a specific exercise by ID from the hasaneyldrm/exercises-dataset API, send a GET request to {BASE_URL}/exercises/{id} where {id} matches the unique string identifier stored in the id field of data/exercises.json.

The hasaneyldrm/exercises-dataset repository delivers exercise data as a static JSON file containing 1,324 records. When exposed through a REST-style wrapper (as documented in setup.html), the API follows standard resource-based routing. Each exercise entry includes a unique string identifier and comprehensive metadata including multilingual instructions, equipment requirements, and media assets.

Understanding the Exercise ID Structure

Data Model in exercises.json

The canonical data source resides in data/exercises.json, where every exercise object contains a unique id field formatted as a zero-padded string. A typical record includes fields for name, category, body_part, equipment, muscle_group, and nested instructions supporting multiple languages.

{
  "id": "0001",
  "name": "3/4 sit-up",
  "category": "waist",
  "body_part": "waist",
  "equipment": "body weight",
  "instructions": { "en": "...", "es": "..." },
  "muscle_group": "hip flexors",
  "secondary_muscles": ["hip flexors", "lower back"],
  "target": "abs",
  "media_id": "2gPfomN",
  "image": "images/0001-2gPfomN.jpg",
  "gif_url": "videos/0001-2gPfomN.gif",
  "attribution": "© Gym visual — https://gymvisual.com/",
  "created_at": "2026-03-18T12:31:32.854798+00:00"
}

Schema Validation

For strict validation of response shapes, refer to data/exercises.schema.json. This JSON Schema defines the expected types for all fields, ensuring that id remains a string and instructions maintains its multilingual object structure.

API Endpoint Structure

When the dataset runs behind a web server, the API endpoint follows conventional REST patterns:

GET {BASE_URL}/exercises/{id}

• {BASE_URL}: The root URL of your hosted instance (e.g., https://api.example.com)
• {id}: The exercise identifier string (e.g., "0001", "1234")

A successful request returns HTTP 200 with the full exercise object. If the identifier does not exist, the server returns 404 Not Found.

Implementation Examples

cURL Command

For quick terminal testing or shell scripts:

curl https://api.example.com/exercises/0001 \
  -H "Accept: application/json"

Python with Requests

Use Python's requests library to fetch and parse the exercise data:

import requests

BASE_URL = "https://api.example.com"
exercise_id = "0001"

resp = requests.get(f"{BASE_URL}/exercises/{exercise_id}")

if resp.status_code == 200:
    exercise = resp.json()
    print(f"Name: {exercise['name']}")
    print(f"English instructions: {exercise['instructions']['en']}")
else:
    print(f"Exercise {exercise_id} not found (status {resp.status_code})")

JavaScript with Fetch

For browser or Node.js environments supporting the Fetch API:

const BASE_URL = "https://api.example.com";
const id = "0001";

fetch(`${BASE_URL}/exercises/${id}`)
  .then(r => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  })
  .then(ex => {
    console.log(`Exercise: ${ex.name}`);
    console.log(`Instructions (EN): ${ex.instructions.en}`);
  })
  .catch(err => console.error(err));

Node.js Local Lookup

For serverless or local development without a running API server, require the static JSON directly from data/exercises.json:

const exercises = require("./data/exercises.json");

function getExerciseById(id) {
  return exercises.find(e => e.id === id);
}

console.log(getExerciseById("0001"));

Handling Errors and Edge Cases

When implementing ID lookups, account for these scenarios:

• 404 Not Found: Returns when the requested ID string does not match any record in data/exercises.json
• Type Sensitivity: The id field uses string comparison; ensure client requests do not coerce "0001" to integer 1
• Partial Data: While setup.html and index.html demonstrate the API interface, always validate responses against data/exercises.schema.json for schema compliance

Summary

• The hasaneyldrm/exercises-dataset stores 1,324 exercise records in data/exercises.json, each with a unique string id
• The REST API endpoint pattern is {BASE_URL}/exercises/{id} as implemented in setup.html
• Response objects include multilingual instructions, muscle_group data, and media URLs (image, gif_url)
• Use data/exercises.schema.json to validate response structures
• For local development, import data/exercises.json directly and use Array.prototype.find() to locate records by ID

Frequently Asked Questions

What data format does the exercise ID use?

The exercise ID is a string, not an integer. Values like "0001" or "1234" appear in data/exercises.json as zero-padded strings. Always treat IDs as strings in your API requests to ensure exact matching against the dataset.

Can I use this API without hosting a server?

Yes. Since the dataset is a static JSON file, you can import data/exercises.json directly into your application. The index.html file demonstrates client-side lookup functionality that works without a backend, filtering the local dataset in the browser.

What fields are guaranteed in the API response?

Every exercise object includes id, name, category, body_part, equipment, instructions (multilingual object), target, and timestamps. Optional fields like secondary_muscles and media URLs follow the schema defined in data/exercises.schema.json.

How do I handle exercises that do not exist?

The API returns a standard HTTP 404 Not Found status when requesting an invalid ID. In client-side implementations parsing the static JSON locally, check if find() returns undefined and handle the null case appropriately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}