README.md

---
title: Cookie Classifier API
emoji: 🍪
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

# 🍪 Cookie Classifier API

**FREE Serverless API** for classifying web cookies into privacy categories.

## 🎯 What It Does

Classifies cookie names into 4 privacy categories:
- **Strictly Necessary** - Essential for website functionality
- **Functionality** - Enhance user experience
- **Analytics** - Track website usage and performance
- **Advertising/Tracking** - Marketing and ad targeting

## 🚀 API Endpoints

### Base URL
```
https://aqibtahir-cookie-classifier-api.hf.space
```

### 1. Health Check
```http
GET /
```

**Response:**
```json
{
  "status": "online",
  "model": "Cookie Classifier - Linear Regression",
  "categories": ["Strictly Necessary", "Functionality", "Analytics", "Advertising/Tracking"]
}
```

### 2. Single Prediction
```http
POST /predict
Content-Type: application/json

{
  "cookie_name": "_ga"
}
```

**Response:**
```json
{
  "cookie_name": "_ga",
  "category": "Analytics",
  "class_id": 2,
  "confidence": 0.89
}
```

### 3. Batch Prediction
```http
POST /predict/batch
Content-Type: application/json

{
  "cookie_names": ["_ga", "sessionid", "utm_campaign", "doubleclick"]
}
```

**Response:**
```json
{
  "predictions": [
    {
      "cookie_name": "_ga",
      "category": "Analytics",
      "class_id": 2,
      "confidence": 0.89
    },
    {
      "cookie_name": "sessionid",
      "category": "Strictly Necessary",
      "class_id": 0,
      "confidence": 0.95
    },
    ...
  ]
}
```

## 💻 Usage Examples

### JavaScript/Frontend

```javascript
// Single prediction
async function classifyCookie(cookieName) {
  const response = await fetch('https://aqibtahir-cookie-classifier-api.hf.space/predict', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ cookie_name: cookieName })
  });
  
  const data = await response.json();
  console.log(data.category); // "Analytics"
  return data;
}

// Batch prediction
async function classifyManyCookies(cookieNames) {
  const response = await fetch('https://aqibtahir-cookie-classifier-api.hf.space/predict/batch', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ cookie_names: cookieNames })
  });
  
  const data = await response.json();
  return data.predictions;
}

// Usage
classifyCookie('_ga').then(result => {
  console.log(`${result.cookie_name} is ${result.category}`);
});
```

### Python

```python
import requests

# Single prediction
response = requests.post(
    'https://aqibtahir-cookie-classifier-api.hf.space/predict',
    json={'cookie_name': '_ga'}
)
print(response.json())

# Batch prediction
response = requests.post(
    'https://aqibtahir-cookie-classifier-api.hf.space/predict/batch',
    json={'cookie_names': ['_ga', 'sessionid', 'utm_campaign']}
)
print(response.json())
```

### cURL

```bash
# Single prediction
curl -X POST "https://aqibtahir-cookie-classifier-api.hf.space/predict" \
  -H "Content-Type: application/json" \
  -d '{"cookie_name": "_ga"}'

# Batch prediction
curl -X POST "https://aqibtahir-cookie-classifier-api.hf.space/predict/batch" \
  -H "Content-Type: application/json" \
  -d '{"cookie_names": ["_ga", "sessionid", "utm_campaign"]}'
```

## 📊 Model Information

- **Model**: Linear Regression with TF-IDF + Name Features
- **Accuracy**: 90%
- **Training Data**: 28,671 cookie samples
- **Features**: 
  - TF-IDF word n-grams (1-2)
  - TF-IDF char n-grams (3-5)
  - Engineered name features (length, patterns, tracker tokens, etc.)

## 🔒 CORS & Security

- ✅ CORS enabled for all origins (frontend-friendly)
- ✅ No authentication required for public use
- ✅ Rate-limited by Hugging Face Spaces (fair usage)

## 📝 Interactive Documentation

Visit the API documentation at:
```
https://aqibtahir-cookie-classifier-api.hf.space/docs
```

## 🏗️ Deployment

This API is deployed on **Hugging Face Spaces** (FREE tier) and runs 24/7.

### Cold Start
- First request may take 10-30 seconds (model loading)
- Subsequent requests are fast (~100-500ms)

## 🤝 Support

For issues or questions:
- Model Repository: [aqibtahir/cookie-classifier-lr-tfidf](https://huggingface.co/aqibtahir/cookie-classifier-lr-tfidf)
- Create an issue on the Space

## 📄 License

MIT License - Free to use for commercial and non-commercial purposes