How to Query Exercises by Category and Equipment Using the Exercises‑Dataset API

The Exercises‑Dataset API enables server‑side filtering of its 1,324 exercise records via the GET /exercises endpoint using category and equipment query parameters, returning paginated JSON responses.

The hasaneyldrm/exercises-dataset repository ships with a lightweight API contract that makes it straightforward to query exercises by category and equipment without building complex backend infrastructure. The dataset stores all records in data/exercises.json, where each exercise object includes standardized category and equipment fields that support precise filtering for fitness applications and research tools.

API Endpoint and Query Parameters

All filtering operations target the GET /exercises endpoint. You can narrow results by appending the following query parameters to the URL:

• category – Filters by primary muscle group or body part (e.g., Strength, Chest, Upper Arms)
• equipment – Filters by required equipment type (e.g., Barbell, Dumbbell, Body Weight)
• page and limit – Controls pagination (defaults typically page 1, limit 20)

When both filters are applied, the API returns only exercises matching both criteria. The response payload includes the filtered data array alongside pagination metadata (total, page, limit, totalPages).

According to the source code in setup.html (lines 58–69), the cURL template demonstrates combining category and equipment parameters for precise filtering.

Implementation Examples

The repository provides reference implementations in multiple languages. The contract definitions in setup.html (lines 10–24) include JavaScript templates, while the cURL examples (lines 58–69) show the raw HTTP pattern.

cURL Request

Use this command to fetch strength exercises requiring a barbell:

curl -s "https://api.yourapp.com/exercises?category=Strength&equipment=Barbell&page=1&limit=20"

This matches the filter template found in setup.html and returns a JSON object containing the data array and pagination details.

JavaScript Fetch Implementation

The setup.html file (lines 10–24) contains the reference JavaScript implementation. Here is the complete async function for filtering:

const BASE_URL = 'https://api.yourapp.com';

async function getExercisesFiltered({ category, equipment, page = 1, limit = 20 }) {
  const params = new URLSearchParams({ page, limit });
  if (category)  params.set('category', category);
  if (equipment) params.set('equipment', equipment);

  const res = await fetch(`${BASE_URL}/exercises?${params}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Example usage
getExercisesFiltered({ category: 'Strength', equipment: 'Barbell' })
  .then(data => console.log(data.data))
  .catch(err => console.error(err));

This function constructs the query string dynamically, omitting undefined parameters to avoid empty filters.

Python Requests Implementation

For Python applications using the requests library:

import requests

BASE_URL = "https://api.yourapp.com"

def get_exercises_filtered(category=None, equipment=None, page=1, limit=20):
    params = {"page": page, "limit": limit}
    if category:  params["category"] = category
    if equipment: params["equipment"] = equipment

    resp = requests.get(f"{BASE_URL}/exercises", params=params)
    resp.raise_for_status()
    return resp.json()

# Example usage

result = get_exercises_filtered(category="Strength", equipment="Barbell")
print(result["data"])

This implementation follows the same logic as the JavaScript version, conditionally adding parameters only when values are provided.

Dataset Structure and Source Files

The filtering capabilities rely on standardized fields defined in the dataset schema. Each exercise record in data/exercises.json contains:

• category: String defining the muscle group or exercise classification
• equipment: String indicating required tools (e.g., Body Weight, Cable)

The JSON Schema in data/exercises.schema.json formally defines these fields, ensuring validation consistency across implementations. For interactive testing, the index.html file provides a browser-based explorer that demonstrates live filtering using the same query parameters against the dataset.

Summary

• Endpoint: Use GET /exercises with category and equipment query parameters to filter the 1,324‑record dataset.
• Source references: Filter templates reside in setup.html (lines 58–69 for cURL, lines 10–24 for JavaScript), while data lives in data/exercises.json.
• Implementation: All major languages follow the same pattern—conditionally append parameters to the URL, then parse the paginated JSON response.
• Schema validation: Reference data/exercises.schema.json to ensure your queries match valid field values.

Frequently Asked Questions

Can I combine category and equipment filters in a single API request?

Yes. The API supports simultaneous filtering by both parameters. When you include category=Strength&equipment=Barbell in the query string, the endpoint returns only exercises that match both criteria, as demonstrated in the setup.html curl template (lines 58–69).

What are the valid values for category and equipment parameters?

Valid values correspond to the fields defined in data/exercises.json and formally specified in data/exercises.schema.json. Common categories include Strength, Cardio, and body‑part specific values like Chest or Upper Arms, while equipment values range from Barbell and Dumbbell to Body Weight.

How does pagination work when filtering results?

The API returns paginated responses controlled by page and limit parameters. The JSON response includes total (total matching records), page (current page), limit (items per page), and totalPages (calculated pages), allowing you to navigate large filtered result sets efficiently.

Is there a way to test queries without implementing a backend server?

Yes. The repository includes index.html, an interactive client‑side explorer that loads data/exercises.json directly and demonstrates the filtering behavior using the same parameter structure (category, equipment, pagination) without requiring a separate API server.

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