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

> Integrate the exercises dataset into your fitness app by loading JSON, importing to SQL, or using a REST API. Access 1324 exercise records and media assets easily.

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

---

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

```javascript
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`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/setup.html) to create the schema and import data:

```sql
-- 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
);

```

```bash

# 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:

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