---
title: HandyHome OCR API
emoji: 🔍
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

# HandyHome OCR Extraction API

Philippine ID and Document OCR Extraction Service using PaddleOCR

## 🎯 Features

### Supported Documents

#### Philippine Government IDs
- **National ID** - 19-digit ID number, full name, birth date
- **Driver's License** - License number, full name, address, birth date
- **UMID** - CRN, full name, birth date
- **SSS ID** - SSS number, full name, birth date
- **PRC ID** - PRC number, profession, full name, validity
- **Postal ID** - PRN, full name, address, birth date
- **PhilHealth ID** - ID number, full name, birth date, sex, address

#### Clearances & Certificates
- **NBI Clearance** - ID number, full name, birth date
- **Police Clearance** - ID number, full name, address, birth date, status
- **TESDA Certificate** - Registry number, full name, qualification, date issued

#### Passport
- **Philippine Passport** - Passport number, surname, given names, birth date, nationality

### Additional Features
- **Document Analysis** - Automatic document type identification
- **Document Tampering Detection** - Analyze multiple documents for tampering using Error Level Analysis (ELA) and metadata inspection

## 🚀 Quick Start

### API Endpoints

All extraction endpoints accept POST requests with the following format:

```json
{
  "document_url": "https://example.com/document.jpg"
}
```

#### Philippine ID Endpoints
- `POST /api/extract-national-id` - Extract National ID
- `POST /api/extract-drivers-license` - Extract Driver's License
- `POST /api/extract-prc` - Extract PRC ID
- `POST /api/extract-umid` - Extract UMID
- `POST /api/extract-sss` - Extract SSS ID
- `POST /api/extract-passport` - Extract Passport
- `POST /api/extract-postal` - Extract Postal ID
- `POST /api/extract-phic` - Extract PhilHealth ID

#### Clearance Endpoints
- `POST /api/extract-nbi` - Extract NBI Clearance
- `POST /api/extract-police-clearance` - Extract Police Clearance
- `POST /api/extract-tesda` - Extract TESDA Certificate

#### Analysis Endpoints
- `POST /api/analyze-document` - Identify document type
- `POST /api/analyze-documents` - Analyze multiple documents for tampering (max 3)

#### Utility Endpoints
- `GET /health` - Health check
- `GET /` - API documentation
- `GET /api/routes` - List all routes

## 📝 Usage Examples

### Python Example

```python
import requests

# Extract National ID
response = requests.post(
    'https://YOUR-SPACE.hf.space/api/extract-national-id',
    json={'document_url': 'https://example.com/national_id.jpg'}
)

result = response.json()
print(result)

# Expected output:
# {
#     "success": true,
#     "id_number": "1234-5678-9012-3456",
#     "full_name": "Juan Dela Cruz",
#     "birth_date": "1990-01-15"
# }

# Analyze multiple documents for tampering
response = requests.post(
    'https://YOUR-SPACE.hf.space/api/analyze-documents',
    json={'image_urls': [
        'https://example.com/id1.jpg',
        'https://example.com/id2.jpg'
    ]}
)

tampering_result = response.json()
print(tampering_result)

# Expected output:
# {
#     "success": true,
#     "total_documents": 2,
#     "results": [
#         {
#             "document_id": "doc_1",
#             "tampering_results": {"tampered": "False", "brightness_ratio": 0.015},
#             "metadata_results": {"result": "success", "message": "..."}
#         },
#         ...
#     ]
# }
```

### cURL Example

```bash
curl -X POST https://YOUR-SPACE.hf.space/api/extract-national-id \
  -H "Content-Type: application/json" \
  -d '{"document_url": "https://example.com/national_id.jpg"}'
```

### JavaScript Example

```javascript
const response = await fetch('https://YOUR-SPACE.hf.space/api/extract-national-id', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    document_url: 'https://example.com/national_id.jpg'
  })
});

const result = await response.json();
console.log(result);
```

## 🛠️ Technical Details

### Technology Stack
- **OCR Engine**: PaddleOCR 2.7+
- **Framework**: Flask + Gunicorn
- **Image Processing**: OpenCV, Pillow
- **Runtime**: Python 3.9

### Performance
- Average response time: 2-5 seconds per document
- Supports images up to 10MB
- Concurrent request handling with Gunicorn workers

### Resource Requirements
- RAM: 4GB minimum
- Storage: 2GB (includes PaddleOCR models)
- CPU: 2 cores recommended

## 📦 Deployment to Hugging Face Spaces

### Step 1: Create a New Space

1. Go to [Hugging Face Spaces](https://huggingface.co/new-space)
2. Enter space name: `handyhome-ocr-api` (or your preferred name)
3. Select **Docker** as SDK
4. Choose visibility: Public or Private
5. Click "Create Space"

### Step 2: Upload Files

Upload all files from this directory to your Space:
- `app.py`
- `requirements.txt`
- `Dockerfile`
- `README.md`
- All `extract_*.py` scripts
- `analyze_document.py`

### Step 3: Configure Space Settings

1. In your Space settings, set:
   - **SDK**: Docker
   - **Port**: 7860
   - **Sleep time**: 48 hours (optional)

2. The Space will automatically build and deploy

### Step 4: Wait for Build

- Initial build takes 5-10 minutes
- PaddleOCR models are downloaded during build
- Check build logs for any errors

### Step 5: Test Your API

Once deployed, test the health endpoint:
```bash
curl https://YOUR-USERNAME-handyhome-ocr-api.hf.space/health
```

## 🔧 Local Development

### Setup

```bash
# Install dependencies
pip install -r requirements.txt

# Run Flask development server
python app.py
```

### Testing

```bash
# Test with a document URL
curl -X POST http://localhost:7860/api/extract-national-id \
  -H "Content-Type: application/json" \
  -d '{"document_url": "YOUR_IMAGE_URL"}'
```

## 📊 Response Format

### Successful Response

```json
{
  "success": true,
  "id_number": "1234-5678-9012-3456",
  "full_name": "Juan Dela Cruz",
  "birth_date": "1990-01-15",
  ...additional fields...
}
```

### Error Response

```json
{
  "success": false,
  "error": "Error description",
  "stderr": "Detailed error message"
}
```

## ⚠️ Limitations

- Requires clear, readable document images
- Works best with well-lit, high-resolution scans
- OCR accuracy depends on image quality
- Some fields may be null if not detected
- Processing time varies based on image size

## 🔐 Security Considerations

- Images are processed in memory and not stored permanently
- All processing happens server-side
- Sensitive data should be transmitted over HTTPS
- Consider rate limiting for production use

## 📄 License

MIT License - See LICENSE file for details

## 🤝 Contributing

Contributions welcome! Please submit issues and pull requests.

## 📞 Support

For issues and questions:
- Open an issue on GitHub
- Contact: [Your contact information]

---

Built with ❤️ using PaddleOCR and Flask