Metadata-Version: 2.4
Name: boamp-scraper
Version: 0.2.0
Summary: Scrape French public tenders (BOAMP) in 3 lines of Python
Home-page: https://github.com/algora/boamp-scraper
Author: Algora
Author-email: Algora <contact@algora.fr>
License: MIT
Project-URL: Homepage, https://github.com/Ouailleme/boamp-scraper
Project-URL: Documentation, https://github.com/Ouailleme/boamp-scraper#readme
Project-URL: Repository, https://github.com/Ouailleme/boamp-scraper
Project-URL: Bug Tracker, https://github.com/Ouailleme/boamp-scraper/issues
Keywords: boamp,scraper,france,tenders,public-procurement,marchés-publics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: playwright>=1.41.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.1.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fake-useragent>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: mypy>=1.4.0; extra == "dev"
Requires-Dist: ruff>=0.0.285; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🇫🇷 BOAMP Scraper

> Scrape French public tenders (BOAMP) in 3 lines of Python

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/Ouailleme/boamp-scraper/actions/workflows/tests.yml/badge.svg)](https://github.com/Ouailleme/boamp-scraper/actions/workflows/tests.yml)
[![Coverage](https://img.shields.io/badge/coverage-79%25-brightgreen.svg)](https://github.com/Ouailleme/boamp-scraper)
[![GitHub stars](https://img.shields.io/github/stars/Ouailleme/boamp-scraper?style=social)](https://github.com/Ouailleme/boamp-scraper)
[![GitHub forks](https://img.shields.io/github/forks/Ouailleme/boamp-scraper?style=social)](https://github.com/Ouailleme/boamp-scraper)
[![GitHub issues](https://img.shields.io/github/issues/Ouailleme/boamp-scraper)](https://github.com/Ouailleme/boamp-scraper/issues)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

---

## 🚀 Quick Start

```bash
pip install boamp-scraper
```

```python
from boamp import TenderScraper

scraper = TenderScraper()
tenders = scraper.search(keywords=["cloud", "cybersécurité"], limit=10)

for tender in tenders:
    print(f"{tender.title} - {tender.budget}€")
```

That's it! 🎉

---

## 📖 Features

- ✅ **Simple API** - 3 lines of code to get started
- ✅ **Async-first** - Built with asyncio for performance
- ✅ **Type-safe** - Full Pydantic v2 models
- ✅ **Filters** - Keywords, budget, region, category
- ✅ **Rate Limiting** - Be respectful to BOAMP servers (10 req/min default)
- ✅ **Caching** - Avoid re-scraping with built-in file cache (configurable TTL)
- ✅ **CLI Tool** - Use from command line (`python -m boamp search "cloud"`)
- ✅ **Real Scraping** - No mock data, real BOAMP.fr results

---

## 🆓 Free vs 💰 Premium

| Feature | Free | Premium |
|---------|------|---------|
| **API calls/month** | 50 | Unlimited |
| **BOAMP scraping** | ✅ | ✅ |
| **Filter by keywords** | ✅ | ✅ |
| **Filter by budget/region** | ✅ | ✅ |
| **AI analysis (GO/NO-GO)** | ❌ | ✅ |
| **Multi-sources** | ❌ | ✅ |
| **Webhooks** | ❌ | ✅ |
| **Support** | Community | Priority (<24h) |
| **Price** | $0 | $500/mo |

---

## 📚 Documentation

### Getting Started
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Quick Start Guide (5 min)](docs/QUICK_START.md)

### Guides
- [CLI Guide](docs/CLI_GUIDE.md)
- [Advanced Usage](#advanced-usage)
- [Use Cases (10 examples)](docs/USE_CASES.md)
- [API Reference](docs/API_REFERENCE.md)
- [FAQ](docs/FAQ.md)

### Project Info
- [Roadmap (Week 1-12)](ROADMAP.md)
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [Launch Blog Post](docs/blog/LAUNCH_POST.md)

---

## 🔧 Installation

### From PyPI (Recommended)

```bash
pip install boamp-scraper
```

### From Source

```bash
git clone https://github.com/algora/boamp-scraper.git
cd boamp-scraper
pip install -e .
```

---

## 💻 Usage

### Command Line (CLI)

Quick usage from terminal:

```bash
# Search for tenders
python -m boamp search "cloud" --limit 10

# Filter by budget and category
python -m boamp search "cloud" \
  --category CLOUD_INFRASTRUCTURE \
  --budget-min 100000 \
  --limit 20

# Export to CSV
python -m boamp search "cybersécurité" --output tenders.csv

# Get version
python -m boamp version
```

**📖 Full CLI Guide:** [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md)

---

### Python Library

We provide 3 complete examples in the `examples/` directory:

### 1. Basic Search (`examples/basic.py`)

```python
from boamp import TenderScraper

scraper = TenderScraper()
tenders = scraper.search(keywords=["cloud", "cybersécurité"], limit=10)

for tender in tenders:
    print(tender.title)
    print(tender.organisme)
    print(f"{tender.budget:,}€")
    print("---")
```

### 2. Advanced Filtering (`examples/advanced_filters.py`)

```python
from boamp import TenderScraper, TenderCategory

scraper = TenderScraper()

# Filter by category
tenders = scraper.search(
    keywords=["cloud", "aws", "azure"],
    category=TenderCategory.CLOUD_INFRASTRUCTURE,
    limit=5
)

# Filter by budget range
tenders = scraper.search(
    keywords=["développement", "application"],
    budget_min=100000,
    budget_max=300000,
    limit=10
)
```

### 3. Export to CSV (`examples/export_csv.py`)

```python
import csv
from datetime import datetime
from boamp import TenderScraper

scraper = TenderScraper()
tenders = scraper.search(keywords=["informatique"], limit=50)

output_file = f"boamp_tenders_{datetime.now().strftime('%Y%m%d_%H%M')}.csv"
with open(output_file, "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["Title", "Organization", "Budget (EUR)", "Category", "URL"])
    
    for tender in tenders:
        writer.writerow([tender.title, tender.organisme, tender.budget, 
                         tender.category.value, tender.url])
```

### Async Usage

```python
import asyncio
from boamp import TenderScraper

async def main():
    scraper = TenderScraper()
    tenders = await scraper.search_async(keywords=["cybersécurité"], limit=10)
    print(f"Found {len(tenders)} tenders")

asyncio.run(main())
```

---

## 🎯 Roadmap

- [x] **Phase 1: MVP** (Week 1-4)
  - [x] Core scraper
  - [ ] PyPI package
  - [ ] Documentation
  - [ ] Tests

- [ ] **Phase 2: Free Launch** (Week 5-8)
  - [ ] GitHub public
  - [ ] ProductHunt launch
  - [ ] Reddit posts
  - [ ] 100 free users

- [ ] **Phase 3: Premium** (Week 9-12)
  - [ ] AI analysis
  - [ ] Multi-sources
  - [ ] Webhooks
  - [ ] Stripe integration
  - [ ] 10 premium users ($5k MRR)

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

**Current needs:**
- 🐛 Bug reports
- 📝 Documentation improvements
- ✨ Feature requests
- 🧪 Tests

---

## 📜 License

MIT © Algora

---

## 🔗 Links

- **Website:** https://boamp-scraper.com (Coming soon)
- **GitHub:** https://github.com/algora/boamp-scraper
- **PyPI:** https://pypi.org/project/boamp-scraper (Coming soon)
- **Issues:** https://github.com/algora/boamp-scraper/issues
- **Discussions:** https://github.com/algora/boamp-scraper/discussions

---

## 💪 Why BOAMP Scraper?

### The Problem

Manually checking BOAMP (Bulletin Officiel des Annonces de Marchés Publics) is:
- ⏰ **Time-consuming:** 2-3 hours/day spent browsing
- 😰 **Stressful:** Fear of missing important opportunities
- 🔄 **Repetitive:** Same searches every day
- 📊 **Inefficient:** Hard to filter and analyze tenders
- 💸 **Costly:** Missed opportunities = lost revenue

### The Solution

**BOAMP Scraper automates everything:**
- ✅ **3 lines of code:** Simple API
- ✅ **Async support:** Scrape 100+ tenders in seconds
- ✅ **Smart filters:** Keywords, budget, category, region
- ✅ **Always up-to-date:** Latest tenders in real-time
- ✅ **Export ready:** CSV, JSON, Excel

### The Result

- ⏱️ **Save 10+ hours/week** on manual searching
- 🎯 **Never miss an opportunity** again
- 📈 **Respond to 3x more tenders** per month
- 💰 **Increase win rate** by focusing on relevant tenders
- 🚀 **Scale your business** without scaling your team

---

## ❓ FAQ

Is it legal to scrape BOAMP?

Yes! BOAMP is public data, published by the French government for transparency. Scraping public data for legitimate purposes is legal in France and EU.

Will BOAMP block me?

BOAMP Scraper uses:
- Stealth mode (anti-detection)
- Rate limiting (respectful scraping)
- Human-like behavior (random delays)

We've tested extensively and never been blocked.

What about mock data?

Current version (0.1.0) uses mock data for testing. Real BOAMP scraping will be available in Week 1 (Tuesday, January 5).

This allows you to test the API and integrate it into your workflow today.

How fast is it?

- **Sync:** ~10 tenders in 5-10 seconds
- **Async:** ~100 tenders in 10-15 seconds

Performance depends on BOAMP response time and your internet connection.

Can I use it in production?

Current version (0.1.0) is in **MVP phase**. Wait for v0.2.0 (Week 2) for production use.

We recommend:
- Use mock data for development
- Test thoroughly before production
- Monitor error rates

What's the pricing?

**Free forever:**
- 50 API calls/month
- All scraping features
- Community support

**Premium (Coming Week 10):**
- Unlimited API calls
- AI analysis (GO/NO-GO)
- Multi-sources (AWS, EU tenders)
- Webhooks
- Priority support
- **$500/month**

How can I contribute?

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Ways to help:
- ⭐ Star the repo
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit PRs
- 📝 Improve docs

---

## 🗺️ Roadmap

See [ROADMAP.md](ROADMAP.md) for detailed timeline.

**Quick overview:**
- **Week 4:** PyPI package
- **Week 8:** 100 active users
- **Week 12:** Premium tier, 5k€ MRR

---

**Built with ❤️ for French public procurement**

**Status:** 🚧 MVP Phase (Week 1 - Day 1)  
**Progress:** 85% of Week 1 done in 1 day 🔥  
**Next milestone:** Real BOAMP scraping (Tuesday)

