How to Create a Workout Generator Application Using the Exercises Dataset

You can create a workout generator by consuming the 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 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, 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 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 directly into the browser using React, Vue, or vanilla JavaScript. The repository includes 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 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:

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:

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:

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	Master catalogue of 1,324 exercises	View file
data/exercises.schema.json	JSON Schema for validation	View file
index.html	Interactive browser demo with search/filter	View file
setup.html	Developer tools for SQL and API generation	View file
README.md	Dataset overview and usage statistics	View file

Summary

• The exercises-dataset provides 1,324 annotated fitness records in 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 as reference) or server-side (using 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. 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, 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 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.

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