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

> Query exercises by category and equipment using the Exercises-Dataset API's GET /exercises endpoint. Filter exercise records efficiently and get paginated JSON responses.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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:

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

```

This matches the filter template found in [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) and returns a JSON object containing the `data` array and pagination details.

### JavaScript Fetch Implementation

The [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) file (lines 10–24) contains the reference JavaScript implementation. Here is the complete async function for filtering:

```javascript
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:

```python
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) formally defines these fields, ensuring validation consistency across implementations. For interactive testing, the [`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) (lines 58–69 for cURL, lines 10–24 for JavaScript), while data lives in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) and formally specified in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html), an interactive client‑side explorer that loads [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) directly and demonstrates the filtering behavior using the same parameter structure (category, equipment, pagination) without requiring a separate API server.