PLANTNET_SETUP.md

# PlantNet API Setup Guide

## Getting Your PlantNet API Key

PlantNet is a powerful plant identification API that uses millions of plant observations.

### Step 1: Register for API Access

1. Go to [PlantNet API Portal](https://my.plantnet.org/)

2. Click on **"Sign Up"** or **"Create an Account"**

3. Fill in your registration details:
   - Email address
   - Password
   - Name
   - Organization (can be personal/student)
   - Purpose (educational, research, commercial)

4. Verify your email address through the confirmation link

### Step 2: Get Your API Key

1. Log in to [PlantNet My Account](https://my.plantnet.org/)

2. Navigate to the **"API Keys"** section

3. Click **"Create New API Key"** or **"Generate API Key"**

4. Choose your plan:
   - **Free Plan**: 500 requests per day
   - **Paid Plans**: Higher limits for commercial use

5. Copy your API key (format: `2a10xxxxxxxxxxxxxxxxxxxxxxxx`)

### Step 3: Configure Your Project

1. Create a `.env` file in the `greenai/` directory (if it doesn't exist):

```bash
# OpenRouter API Key (existing)
OPENROUTER_API_KEY=your_openrouter_key_here

# PlantNet API Key (new)
PLANTNET_API_KEY=your_plantnet_api_key_here
```

2. **IMPORTANT**: Never commit your `.env` file to version control!

Add to `.gitignore`:
```
.env
*.env
```

### Step 4: Test Your API Key

You can test your PlantNet API key using curl:

```bash
curl -X GET "https://my-api.plantnet.org/v2/identify/all?api-key=YOUR_API_KEY&images=https://bs.plantnet.org/image/o/12345.jpg"
```

Or use our built-in test endpoint (after integration):

```bash
curl -X GET "http://localhost:8000/test/plantnet"
```

## PlantNet API Features

### Available Projects (Flora)

For MCC Campus (India), the most relevant projects are:
- `k-indian-subcontinent` - Indian Subcontinent flora (7,469 species) **[Currently used]**
- `k-world-flora` - World flora (82,920 species) - Broadest coverage
- `useful` - Useful plants (5,519 species)
- `k-western-indian-ocean` - Western Indian Ocean (10,453 species)

Other popular projects:
- `weurope` - Western Europe
- `k-northern-africa` - Northern Africa
- `k-eastern-asia` - Eastern Asia
- `k-china` - China
- `k-australia` - Australia
- Plus 70+ more regional projects

To change the project, edit line 180 in `api.py`:
```python
api_url = f"https://my-api.plantnet.org/v2/identify/k-indian-subcontinent"
```

### Request Limits
- **Free Tier**: 500 requests/day
- **Rate Limit**: ~1 request per second
- **Image Format**: JPEG, PNG
- **Max File Size**: 5MB per image

### API Response Structure
```json
{
  "query": {
    "project": "all",
    "images": ["image1_url"]
  },
  "results": [
    {
      "score": 0.95467,
      "species": {
        "scientificNameWithoutAuthor": "Rosa canina",
        "scientificName": "Rosa canina L.",
        "genus": "Rosa",
        "family": "Rosaceae",
        "commonNames": ["Dog Rose", "Briar Rose"]
      },
      "images": [...]
    }
  ]
}
```

## Integration Benefits

PlantNet API adds:
- ✅ Access to 77M+ plant observations
- ✅ Worldwide plant database
- ✅ Multiple image analysis
- ✅ Common names in multiple languages
- ✅ Family and genus classification
- ✅ Geographic distribution data

## Troubleshooting

### Common Issues

**Error: "Invalid API Key"**
- Check your API key is correctly copied
- Ensure no extra spaces in the .env file
- Verify the key is active in PlantNet dashboard

**Error: "Quota Exceeded"**
- Free tier limit reached (500/day)
- Wait 24 hours or upgrade to paid plan

**Error: "Image too large"**
- Resize images to under 5MB
- Compress JPEG quality

**Error: "No result found"**
- Plant may not be in database
- Try different image angles
- Use fallback to BioCLIP model

## Support

- PlantNet Documentation: https://my.plantnet.org/doc
- API Support: contact@plantnet.org
- Project Issues: GitHub Issues

## Cost Estimates

| Plan | Requests/Day | Monthly Cost |
|------|--------------|--------------|
| Free | 500 | $0 |
| Basic | 5,000 | ~€10 |
| Pro | 50,000 | ~€50 |
| Enterprise | Custom | Contact |

_Last updated: February 2026_