A Django REST API that classifies names by gender using the Genderize.io API. This application provides an endpoint to determine the likely gender of a person based on their name, with confidence scoring and result caching for optimal performance.
- Gender Classification: Classify names by gender using the Genderize.io API
- Confidence Scoring: Returns confidence metrics including probability and sample size
- Smart Caching: Caches results to reduce API calls and improve response times
- RESTful API: Built with Django REST Framework for easy integration
- Error Handling: Comprehensive error handling with appropriate HTTP status codes
- CORS Support: Enabled for cross-origin requests from any domain
- Input Validation: Validates input to ensure proper query parameters
- Framework: Django 6.0.4
- API Framework: Django REST Framework
- HTTP Client: HTTPX
- Caching: Django Cache Framework
- CORS: Django CORS Headers
- Database: SQLite3
- Python Version: 3.x
.
├── classify/ # Main Django project configuration
│ ├── settings.py # Django settings and configuration
│ ├── urls.py # Main URL routing
│ ├── asgi.py # ASGI configuration
│ ├── wsgi.py # WSGI configuration
│ └── __init__.py
├── classifyname/ # Main application
│ ├── views.py # API views (Query endpoint)
│ ├── urls.py # Application URL routing
│ ├── models.py # Database models
│ ├── admin.py # Django admin configuration
│ ├── apps.py # App configuration
│ ├── tests.py # Unit tests
│ └── migrations/ # Database migrations
├── manage.py # Django management script
├── db.sqlite3 # SQLite database
└── README.md # This file
- Clone the repository:
git clone <repository-url>
cd Classify- Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Run migrations:
python manage.py migrate- Start the development server:
python manage.py runserverThe API will be available at http://localhost:8000/
Endpoint: GET /api/classify
Query Parameters:
name(required): The name to classify (must be a string, not a number)
Request Example:
GET /api/classify?name=John
Success Response (200 OK):
{
"status": "success",
"result": {
"name": "John",
"gender": "male",
"probability": 0.98,
"sample_size": 1250,
"is_confident": true,
"processed_at": "2026-04-14T10:30:45+00:00"
}
}Error Response - Missing Parameter (400 Bad Request):
{
"status": "error",
"message": "Name parameter is required."
}Error Response - Invalid Input (422 Unprocessable Entity):
{
"status": "error",
"message": "Name parameter must be a string."
}Error Response - API Failure (500 Internal Server Error):
{
"status": "error",
"message": "Failed to classify the name."
}- name: The name that was classified
- gender: The predicted gender ("male" or "female")
- probability: Confidence score between 0 and 1 indicating the likelihood of the prediction
- sample_size: Number of samples used in the Genderize.io database for this name
- is_confident: Boolean flag indicating high confidence (probability >= 0.7 and sample_size >= 100)
- processed_at: ISO 8601 timestamp when the API processed the request
Results are cached automatically using Django's cache framework. Cache keys are formatted as classifyname:{name.lower()} to ensure consistent caching regardless of input case. Cached results are returned for the same name within the cache TTL, reducing external API calls.
Key settings in classify/settings.py:
- DEBUG: Set to
Falsein production - SECRET_KEY: Change this to a secure random value in production
- ALLOWED_HOSTS: Configure with your domain names in production
- CORS_ALLOW_ALL_ORIGINS: Set to
Falseand configure specific origins in production
python manage.py testAccess the Django admin panel at http://localhost:8000/admin/ with superuser credentials.
python manage.py createsuperuserBefore deploying to production:
- Set
DEBUG = Falsein settings.py - Generate a new
SECRET_KEYand keep it secure - Configure
ALLOWED_HOSTSwith your domain names - Set up a production-grade database (PostgreSQL recommended)
- Configure appropriate caching backend (Redis recommended instead of default cache)
- Review and restrict
CORS_ALLOW_ALL_ORIGINSto specific trusted origins - Set up HTTPS/SSL certificates
- Use environment variables for sensitive configuration
- Configure proper logging and monitoring
- Set up a production WSGI server (Gunicorn, uWSGI, etc.)
Key Python packages required (see requirements.txt for full list):
- django >= 6.0.4
- djangorestframework
- django-cors-headers
- httpx
Note: Genderize.io has rate limits on their free tier. Monitor your API usage to stay within limits. Consider implementing rate limiting on your Django application if needed.
Issue: "Name parameter is required" error
- Solution: Ensure you're passing the
namequery parameter in your request
Issue: "Name parameter must be a string" error
- Solution: The name parameter cannot be purely numeric. Use a string value instead
Issue: "Failed to classify the name" error
- Solution: Check your internet connection and ensure Genderize.io API is accessible
Issue: Slow responses
- Solution: Check if caching is properly configured. Cached responses should be much faster
This project is provided as-is for educational and development purposes.
To contribute improvements or report issues:
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a pull request
For questions or issues, please reach out through the project repository or contact the maintainers.