# How to Create a Workout Generator Application Using the Exercises Dataset

> Build a workout generator app by using the exercises dataset repository. Filter exercises by equipment, muscle, or category to create personalized workout sessions.

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

---

**You can create a workout generator by consuming the [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) file from the hasaneyldrm/exercises-dataset repository, filtering exercises by equipment, target muscle, or category, and randomly sampling the results to generate personalized workout sessions.**

The **exercises-dataset** repository provides a static JSON catalogue of 1,324 fitness exercises with multilingual instructions, equipment metadata, and visual assets. This dataset enables you to construct personalized workout generators for web, mobile, or CLI applications without requiring a backend database. By treating [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) as your data layer, you can build everything from simple command-line tools to full-stack web applications.

## Understanding the Dataset Structure

The core data resides in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json), which contains an array of exercise objects. Each record includes the exercise `name`, `category`, `equipment` type, `target` muscle group, and multilingual `instructions` supporting languages such as English and German. Visual guidance is available through the `image` field (180×180 thumbnail) and `gif_url` field for animated demonstrations.

### Schema Validation

Reference [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) for the JSON Schema (Draft 2020-12) that validates field types and required properties. This schema ensures your application handles the data structure correctly when parsing the catalogue.

## Architecture Options

You can implement the generator as either a **client-side** JavaScript application or a **server-side** API, depending on your performance and persistence requirements.

### Client-Side Implementation

Load [`exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/exercises.json) directly into the browser using React, Vue, or vanilla JavaScript. The repository includes [`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html), a fully client-side exercise explorer that demonstrates search, filter, and infinite scroll capabilities without server dependencies. This approach works best for static sites or mobile apps where you bundle the dataset with the application.

### Server-Side Implementation

Deploy a REST API using Node.js/Express or Python/FastAPI that reads the JSON file and returns filtered workout plans. The [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) file provides SQL generation snippets for importing the data into a relational database if you need complex queries, user progress tracking, or analytics.

## Implementation Examples

### Python CLI Generator

Use the Python standard library to load and filter the dataset:

```python
import json, random, pathlib

# Load the dataset

DATA_PATH = pathlib.Path("data/exercises.json")
with DATA_PATH.open(encoding="utf-8") as f:
    exercises = json.load(f)

def generate_workout(count=6, equipment=None, target=None, language="en"):
    # Apply filters

    pool = [
        ex for ex in exercises
        if (equipment is None or ex["equipment"] == equipment)
        and (target is None or ex["target"] == target)
    ]
    # Randomly pick

    selected = random.sample(pool, k=min(count, len(pool)))
    # Return only the fields needed for the UI

    return [
        {
            "name": ex["name"],
            "image": ex["image"],
            "gif": ex["gif_url"],
            "instructions": ex["instructions"][language],
        }
        for ex in selected
    ]

# Example: 5 body-weight chest exercises, English instructions

workout = generate_workout(count=5, equipment="body weight", target="chest")
print(workout)

```

### Node.js REST API

Create an Express endpoint that returns filtered workouts:

```javascript
const express = require("express");
const path = require("path");
const exercises = require("./data/exercises.json");

const app = express();
app.use(express.json());

app.post("/workout", (req, res) => {
  const { count = 6, equipment, target, language = "en" } = req.body;

  const pool = exercises.filter(
    ex =>
      (!equipment || ex.equipment === equipment) &&
      (!target || ex.target === target)
  );

  const selected = pool
    .sort(() => 0.5 - Math.random())   // shuffle
    .slice(0, Math.min(count, pool.length));

  const plan = selected.map(ex => ({
    name: ex.name,
    image: ex.image,
    gif: ex.gif_url,
    instructions: ex.instructions[language],
  }));

  res.json(plan);
});

app.listen(3000, () => console.log("Workout API listening on :3000"));

```

### React Client-Side Component

Import the JSON directly and generate workouts in the browser:

```tsx
import React, { useEffect, useState } from "react";
import exercises from "./data/exercises.json";

type Exercise = typeof exercises[0];

function randomWorkout(
  count: number,
  equipment?: string,
  target?: string,
  lang = "en"
): Exercise[] {
  const pool = exercises.filter(
    ex => (!equipment || ex.equipment === equipment) && (!target || ex.target === target)
  );
  const shuffled = [...pool].sort(() => Math.random() - 0.5);
  return shuffled.slice(0, count);
}

export default function WorkoutGenerator() {
  const [plan, setPlan] = useState<Exercise[]>([]);

  useEffect(() => {
    setPlan(randomWorkout(6, "dumbbell"));
  }, []);

  return (
    <div>
      <h2>Your Workout</h2>
      <ul>
        {plan.map(ex => (
          <li key={ex.id}>
            <img src={ex.image} alt={ex.name} width={80} />
            <strong>{ex.name}</strong>
            <p>{ex.instructions.en}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}

```

## Essential Repository Files

| File | Purpose | Link |
|------|---------|------|
| [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) | Master catalogue of 1,324 exercises | [View file](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) |
| [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) | JSON Schema for validation | [View file](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) |
| [`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html) | Interactive browser demo with search/filter | [View file](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html) |
| [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) | Developer tools for SQL and API generation | [View file](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) |
| [`README.md`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md) | Dataset overview and usage statistics | [View file](https://github.com/hasaneyldrm/exercises-dataset/blob/main/README.md) |

## Summary

- The **exercises-dataset** provides 1,324 annotated fitness records in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) suitable for building workout generators.
- Each exercise includes **equipment**, **target muscle**, and **multilingual instructions** that support filtering and localization.
- You can implement the generator **client-side** (using [`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html) as reference) or **server-side** (using [`setup.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) for database integration).
- The dataset supports **random sampling** algorithms to create varied workout sessions based on user constraints.

## Frequently Asked Questions

### What format is the exercise data stored in?

The exercise data is stored as a JSON array in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json). Each object contains fields for `name`, `equipment`, `target`, `instructions` (multilingual), `image`, and `gif_url`.

### Can I use this dataset without a backend server?

Yes. The repository includes [`index.html`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/index.html), which demonstrates a fully client-side implementation that loads the JSON directly in the browser and provides search, filter, and display functionality without any server-side processing.

### How do I validate the exercise data before importing it?

Use the [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) file, which provides a JSON Schema (Draft 2020-12) describing the expected types and structure for each exercise record. You can validate the dataset using standard JSON Schema validators in Python, JavaScript, or other languages.

### Does the dataset include visual instructions for exercises?

Yes. Each exercise record includes an `image` field linking to a 180×180 thumbnail and a `gif_url` field providing an animated GIF demonstration, allowing you to build visually rich user interfaces.