Genderize API

A FastAPI service that classifies names by gender using the Genderize.io API.

---

Setup

1. Clone the repository

git clone <your-repo-url>
cd genderize-api

2. Create and activate a virtual environment

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env

5. Run the server

uvicorn app.main:app --reload

The server will start at http://localhost:8000

---

Endpoint

GET /api/classify?name={name}

Classifies a name by gender.

Query Parameters

Parameter	Type	Required	Description
name	string	Yes	The name to classify

Success Response (200)

{
  "status": "success",
  "data": {
    "name": "john",
    "gender": "male",
    "probability": 0.99,
    "sample_size": 1234,
    "is_confident": true,
    "processed_at": "2026-04-01T12:00:00Z"
  }
}

Error Responses

Status	Reason
400	Missing or empty name parameter
422	name is not a string
500	Internal server error
502	Upstream Genderize API failure

All errors follow this format:

{
  "status": "error",
  "message": "<description>"
}

Edge case — no prediction available:

{
  "status": "error",
  "message": "No prediction available for the provided name"
}

---

Confidence Logic

is_confident is true only when both conditions are met:

• probability >= 0.7
• sample_size >= 100

If either condition fails, is_confident is false.

---

Running Tests

pytest tests/ -v

---

Deployment

Supported platforms: Vercel, Railway, Heroku, AWS, PXXL App

Note: Render is not accepted per submission requirements.

For Railway or Heroku, ensure your start command is:

uvicorn app.main:app --host 0.0.0.0 --port $PORT