Metadata-Version: 2.4
Name: licitapilot
Version: 0.1.0
Summary: Cliente oficial de la API de LicitaPilot: licitaciones públicas de España (PLACSP y autonómicas), baja temeraria, radar de vencimientos y rankings de adjudicatarios.
Project-URL: Homepage, https://licitapilot.com
Project-URL: Documentation, https://github.com/jmcodero/licitapilot-python#readme
Project-URL: Source, https://github.com/jmcodero/licitapilot-python
Project-URL: Issues, https://github.com/jmcodero/licitapilot-python/issues
Author-email: LicitaPilot <hola@licitapilot.com>
License: MIT
License-File: LICENSE
Keywords: api-client,contratacion-publica,government-tenders,licitaciones,open-data,placsp,public-procurement,spain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# licitapilot-python

Cliente oficial de Python para la API de **[LicitaPilot](https://licitapilot.com)** — licitaciones públicas de España (PLACSP y boletines autonómicos), estadísticas de **baja temeraria**, **radar de vencimientos** y **rankings de adjudicatarios**.

[![PyPI](https://img.shields.io/pypi/v/licitapilot.svg)](https://pypi.org/project/licitapilot/)
[![Python](https://img.shields.io/pypi/pyversions/licitapilot.svg)](https://pypi.org/project/licitapilot/)
[![CI](https://github.com/jmcodero/licitapilot-python/actions/workflows/ci.yml/badge.svg)](https://github.com/jmcodero/licitapilot-python/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> Datos de contratación pública española, listos para tu código en 10 segundos. **La capa pública no necesita registro ni clave.**

```python
from licitapilot import LicitaPilot

lp = LicitaPilot()                       # sin clave
radar = lp.vencimientos(sector="45")     # contratos de construcción que van a re-licitarse
print(radar["total"], "vencimientos próximos")
for v in radar["items"][:5]:
    print(v["title"], "→ vence", v.get("contract_end_date"))
```

---

## Instalación

```bash
pip install licitapilot
```

## Dos capas

| Capa | Necesita clave | Qué te da |
|------|:---:|-----------|
| **Pública** | ❌ | Radar de vencimientos, baja temeraria, rankings de adjudicatarios, ficha de empresa y de licitación por id — los mismos datos abiertos que ya publica la web |
| **Empresa** | ✅ `lp_live_…` | `/v1`: listado masivo de licitaciones (histórico + filtros) y tus *matches* personalizados por perfil |

Consigue tu clave en **[licitapilot.com](https://licitapilot.com)** (plan Empresa).

## Uso

### "El foso": vencimientos, baja temeraria y rankings (público, sin clave)

```python
lp = LicitaPilot()

lp.vencimientos()                  # hub global de contratos que caducan y volverán a salir
lp.vencimientos(sector="45")       # detalle de un sector (división CPV)
lp.baja_temeraria("45")            # cuánto se baja de media en construcción
lp.ranking_adjudicatarios("obras") # quién gana más en un sector
lp.empresa("acme-construcciones")  # ficha pública de una adjudicataria
lp.tender(123)                     # ficha pública de una licitación por id
```

### Licitaciones y matches (plan Empresa, con clave)

El listado masivo y tus coincidencias personalizadas viven en `/v1` y requieren clave:

```python
lp = LicitaPilot(api_key="lp_live_…")   # o export LICITAPILOT_API_KEY=…

# Listado con filtros e histórico
page = lp.tenders(cpv="72", province="Madrid", state="open", limit=50)
for t in lp.iter_tenders(cpv="45", state="all", max_items=1000):
    print(t.id, t.title, t.url)

# Tus matches por perfil (scoring de relevancia + IA)
for m in lp.matches(limit=50):
    print(m.relevance_score, m.tender.title, m.status)
```

Sin clave, `tenders()` y `matches()` lanzan `AuthRequiredError` a propósito: son la
parte de pago y la capa gratis no compite con ellas.

## CLI

Instalar el paquete te da el comando `licitapilot`:

```bash
licitapilot tenders --cpv 45 --province Madrid
licitapilot vencimientos --sector 45
licitapilot baja --cpv 45
licitapilot ranking obras
licitapilot matches            # usa LICITAPILOT_API_KEY

licitapilot tenders --cpv 72 --json   # salida JSON para pipes
```

## Ejemplos

Recetas listas para copiar en [`examples/`](examples/):

- [`export_csv.py`](examples/export_csv.py) — vuelca a CSV el radar de vencimientos de un sector (sin clave).
- [`vencimientos_telegram.py`](examples/vencimientos_telegram.py) — bot de Telegram que te avisa de contratos que van a re-licitarse (sin clave).
- [`streamlit_foso.py`](examples/streamlit_foso.py) — dashboard de baja temeraria por sector (sin clave).

## Manejo de errores

```python
from licitapilot import LicitaPilot, APIError, AuthRequiredError

try:
    LicitaPilot().matches()          # sin clave
except AuthRequiredError:
    ...                              # esta operación es de plan Empresa
except APIError as e:
    print(e.status_code, e.payload)  # la API devolvió 4xx/5xx
```

## Desarrollo

```bash
pip install -e ".[dev]"
ruff check src tests
pytest -q            # tests con HTTP simulado, sin red
```

## Sobre LicitaPilot

[LicitaPilot](https://licitapilot.com) es el copiloto de licitaciones públicas para empresas y autónomos en España: alertas por perfil, análisis con IA, radar de vencimientos, grafo de competidores y escritos jurídicos asistidos. Este SDK expone parte de esos datos de forma programática.

## Licencia

MIT © LicitaPilot
