IELTS Writing Checker API

IELTS Writing Checker API is a small open-source web application for checking IELTS Academic Writing Task 2 essays.

The user enters a Task 2 question on the left side and writes an essay on the right side. After pressing the Check Writing button, the app sends the essay to the backend and returns AI-based IELTS feedback.

This project is built with Python, FastAPI, HTML, CSS, JavaScript, and OpenAI API.

Features

• IELTS Writing Task 2 checker
• Simple local web interface
• OpenAI API integration
• Estimated IELTS band score
• Feedback based on IELTS criteria
• Grammar correction suggestions
• Vocabulary improvement suggestions
• Improved introduction example
• Demo mode when API key is not added
• Swagger API documentation
• Docker support
• Basic tests with pytest

Tech Stack

• Python
• FastAPI
• OpenAI API
• HTML
• CSS
• JavaScript
• Pytest
• Docker

Project Structure

ielts-writing-checker-api/
│
├── app/
│   ├── main.py          # FastAPI app and routes
│   ├── checker.py       # OpenAI checking logic
│   └── config.py        # Environment settings
│
├── templates/
│   └── index.html       # Main web page
│
├── static/
│   ├── style.css        # Page styling
│   └── script.js        # Frontend logic
│
├── tests/
│   └── test_app.py      # Basic API tests
│
├── .env.example
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── README.md
└── LICENSE

How to Install

Clone the repository:

git clone https://github.com/your-username/ielts-writing-checker-api.git
cd ielts-writing-checker-api

Create a virtual environment:

python -m venv venv

Activate it:

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Environment Variables

Create a .env file from .env.example:

cp .env.example .env

Add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

If you do not add an API key, the app will still run in demo mode.

How to Run

Start the server:

uvicorn app.main:app --reload

Open the app in your browser:

http://127.0.0.1:8000

Swagger API docs:

http://127.0.0.1:8000/docs

API Usage

Endpoint:

POST /api/check

Example request:

{
  "question": "Some people believe that technology has made people less social. To what extent do you agree or disagree?",
  "essay": "Nowadays, technology is used everywhere. I believe that it has both advantages and disadvantages..."
}

Example response:

{
  "overall_band": "6.5",
  "task_response": "6.5",
  "coherence_and_cohesion": "6.0",
  "lexical_resource": "6.5",
  "grammar_range_and_accuracy": "6.0",
  "summary": "The essay answers the question, but examples and grammar need improvement."
}

Run with Docker

Create your .env file first, then run:

docker compose up --build

Open:

http://127.0.0.1:8000

Run Tests

pytest

Important Notes

• Do not upload your real .env file to GitHub.
• Keep your OpenAI API key private.
• The band score is an AI-based estimate, not an official IELTS score.
• This project is created for learning, practice, and portfolio use.

Future Improvements

• Save essay history
• Add user accounts
• Add PDF report export
• Add Writing Task 1 checker
• Add teacher mode
• Add essay timer
• Add more detailed band descriptor feedback

Author

alproger

License

This project is licensed under the MIT License.