How to Integrate the Exercises Dataset into a Fitness Application: A Complete Technical Guide

You can integrate the hasaneyldrm/exercises-dataset into any fitness application by loading the JSON file directly, importing records into a SQL database, or consuming a REST API that serves the 1,324 exercise records with their associated media assets.

The hasaneyldrm/exercises-dataset repository provides a framework-agnostic collection of fitness exercises complete with multilingual instructions, thumbnail images, and animated GIFs. Whether you are building a React Native workout tracker, a Flutter fitness coach, or a Python-based backend service, the dataset’s three-layer architecture allows you to choose between static file integration or full database-backed API deployment.

Understanding the Dataset Architecture

The repository organizes data into three logical layers that work independently or together depending on your application's needs.

Data Layer: JSON and Schema Validation

The core data resides in data/exercises.json, which contains a JSON array of 1,324 exercise objects. Each record includes fields for name, category, body_part, equipment, target, and multilingual instruction fields (e.g., instructions_en, instructions_es). The accompanying data/exercises.schema.json file provides a formal JSON-Schema definition that validates record shape, ensuring your application can safely map fields to internal models without encountering unexpected data types.

Media Layer: Static Image and Video Assets

Visual content is stored in the images/ and videos/ directories, containing 1,324 JPG thumbnails and 1,324 animated GIFs respectively. Each exercise record references these assets via relative paths in the image and gif_url fields (e.g., images/0001-2gPfomN.jpg). To use these in your application, serve these folders as static assets from a CDN, cloud storage bucket, or local web server, then prepend your base URL when constructing full media paths in the client.

Access Layer: Browser Explorer and API Templates

The index.html file provides a client-side exercise explorer that requires no backend server, offering live search and filtering capabilities. For backend integration, the setup.html file contains production-ready code snippets for calling REST APIs in cURL, JavaScript, Python, C#, Java, PHP, and Go, plus SQL templates for database schema creation and an LLM prompt generator that can scaffold complete APIs for Express, FastAPI, ASP.NET Core, Spring Boot, Laravel, or Gin.

Step-by-Step Integration Workflow

Follow this systematic approach to incorporate the dataset into your fitness application infrastructure.

1. Choose Your Storage Strategy

Static File Approach: Ship data/exercises.json directly with your application bundle and load it at runtime using fetch or json.load. This works best for offline-first mobile apps or client-side rendered web applications where you want to minimize backend dependencies.

Database Approach: Import the records into a relational database using the CREATE TABLE statements provided in setup.html. Click the Generate INSERT SQL button in the setup wizard to produce SQL insert statements compatible with PostgreSQL, MySQL, SQL Server, or SQLite. This approach supports complex querying, user-specific favorites, and progress tracking.

2. Configure Media Asset Serving

Copy the images/ and videos/ folders to a public directory on your server or upload them to object storage (AWS S3, Google Cloud Storage, Azure Blob). Ensure your web server serves these with appropriate caching headers. In your application code, concatenate your base URL with the relative paths stored in the image and gif_url fields to construct fully qualified media URLs.

3. Implement the API Layer (Optional)

If you choose the database approach, expose three core endpoints: GET /exercises/:id for single record retrieval, GET /exercises for paginated listing (supporting page and limit parameters), and GET /exercises?filters for filtered queries by category, body_part, equipment, or target. Use the LLM prompt in setup.html to generate a complete REST API scaffold, or implement these endpoints manually ensuring the JSON response shape matches the original schema.

4. Consume Data in Your Application

Integrate the data into your workout planner, recommendation engine, or exercise detail views. Bind the gif_url to image components for animated demonstrations, and use the instructions.* fields to display step-by-step guidance in the user's preferred language. Because the dataset is framework-agnostic, you can consume it via HTTP from native mobile apps (Swift/Kotlin), React Native, Flutter, or any JavaScript frontend.

Code Implementation Examples

Loading JSON Directly in JavaScript

For static integration, fetch the dataset directly from your public assets folder:

const DATA_URL = '/data/exercises.json';

async function loadExercises() {
  const resp = await fetch(DATA_URL);
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const exercises = await resp.json();
  console.log(`Loaded ${exercises.length} exercises`);
  return exercises;
}

// Filter chest exercises client-side
loadExercises().then(list => {
  const chest = list.filter(e => e.category === 'chest');
  console.log('Chest exercises:', chest.length);
});

Importing into PostgreSQL

Use the SQL templates from setup.html to create the schema and import data:

-- Create table (from setup.html)
CREATE TABLE exercises (
  id                VARCHAR(10)  PRIMARY KEY,
  name              VARCHAR(255) NOT NULL,
  category          VARCHAR(100),
  body_part         VARCHAR(100),
  equipment         VARCHAR(100),
  instructions_en   TEXT,
  instructions_es   TEXT,
  instructions_it   TEXT,
  instructions_tr   TEXT,
  instructions_ru   TEXT,
  instructions_zh   TEXT,
  instructions_hi   TEXT,
  instructions_pl   TEXT,
  instructions_ko   TEXT,
  muscle_group      VARCHAR(100),
  secondary_muscles JSONB,
  target            VARCHAR(100),
  image             VARCHAR(500),
  gif_url           VARCHAR(500),
  created_at        TIMESTAMPTZ
);

# Generate INSERT statements via setup.html, save to exercises.sql

psql -U your_user -d your_db -f exercises.sql

Querying via Python API Client

Consume your deployed API using standard HTTP requests:

import requests

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

def get_exercise(ex_id):
    r = requests.get(f"{BASE_URL}/exercises/{ex_id}")
    r.raise_for_status()
    return r.json()

def list_exercises(page=1, limit=20, category=None):
    params = {"page": page, "limit": limit}
    if category:
        params["category"] = category
    r = requests.get(f"{BASE_URL}/exercises", params=params)
    r.raise_for_status()
    return r.json()

# Usage example

ex = get_exercise("0001")
print(ex["name"], ex["gif_url"])

Summary

• hasaneyldrm/exercises-dataset provides 1,324 fitness exercises with multilingual instructions and media assets in data/exercises.json, images/, and videos/.
• You can integrate exercises into a fitness application via static JSON loading, SQL database import, or REST API consumption.
• The setup.html file offers SQL schemas, INSERT generators, and API scaffolding prompts for multiple frameworks.
• Media assets use relative paths requiring only a base URL prefix to serve via CDN or local storage.
• The JSON-Schema in data/exercises.schema.json ensures data consistency across all integration methods.

Frequently Asked Questions

What is the schema structure for exercises.json?

Each exercise object in data/exercises.json contains string fields for id, name, category, body_part, equipment, and target, along with multilingual instruction fields (e.g., instructions_en, instructions_es). The secondary_muscles field stores an array of muscle groups, while image and gif_url contain relative paths to the media folders. Use data/exercises.schema.json to validate incoming data against this structure.

Can I use this dataset in a mobile app?

Yes, the dataset is framework-agnostic and works with native iOS (Swift), native Android (Kotlin), React Native, Flutter, or any mobile platform capable of parsing JSON and displaying images. You can either bundle the JSON file with your app for offline access or host it behind an API endpoint for dynamic updates.

How do I handle the multilingual instruction fields?

Each exercise includes instructions in English, Spanish, Italian, Turkish, Russian, Chinese, Hindi, Polish, and Korean (fields prefixed with instructions_ and the language code). Detect the user's locale in your application and map it to the corresponding field key (e.g., instructions_tr for Turkish) to display localized step-by-step guidance without requiring external translation services.

Is there a ready-made API or do I need to build one?

The repository does not include a running API server, but setup.html provides an "Ask Your LLM" section with prompts that generate complete API implementations for Express.js, FastAPI, ASP.NET Core, Spring Boot, Laravel, or Gin. Alternatively, you can implement the three standard endpoints (GET /exercises, GET /exercises/:id, and filtered search) yourself while maintaining the original JSON response structure.

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