BDNS Fetch

🇬🇧 English version

Cliente Python y CLI para la API REST de la BDNS. Cubre los 29 endpoints disponibles con soporte completo de parámetros, paginación automática y reintentos configurables.

Instalación

pip install bdns-fetch

o desde el repositorio:

git clone https://github.com/cruzlorite/bdns-fetch.git
cd bdns-fetch
pip install .

Uso

Cliente Python

from bdns.fetch.client import BDNSClient

client = BDNSClient()

for org in client.fetch_organos(idAdmon="C"):
    print(org["codigo"], "-", org["descripcion"])

Búsqueda paginada:

resultados = client.fetch_ayudasestado_busqueda(
    descripcion="investigación",
    pageSize=1000,
    num_pages=5,
    from_page=0,
)
for item in resultados:
    print(item)

Descarga de documentos binarios:

pdf_bytes = client.fetch_convocatorias_pdf(id=608268, vpd="A07")
with open("convocatoria.pdf", "wb") as f:
    f.write(pdf_bytes)

Configuración del cliente:

client = BDNSClient(
    max_retries=5,    # reintentos por petición fallida
    wait_time=2,      # segundos entre reintentos
    max_workers=10,   # hilos concurrentes para paginación
    return_raw=False, # True devuelve objetos de página completos
)

CLI

# Ver ayuda
bdns-fetch --help
bdns-fetch <comando> --help

# Guardar a fichero
bdns-fetch --output-file organos.jsonl organos --idAdmon C

# Búsqueda con filtros
bdns-fetch --output-file resultado.jsonl ayudasestado-busqueda \
    --descripcion "innovación" --fechaDesde "2023-01-01" --fechaHasta "2024-12-31"

# Paginación
bdns-fetch concesiones-busqueda --num-pages 0 --pageSize 10000

# Salida a stdout (por defecto)
bdns-fetch convocatorias-ultimas | jq .

Opciones globales:

Comandos disponibles

Buenas prácticas (oficiales)

Según el documento oficial "Buenas prácticas API SNPSAP":

• Límite de peticiones: máximo 10 peticiones GET/segundo por IP. bdns-fetch lo aplica internamente con un limitador tipo token-bucket compartido entre todas las peticiones HTTP, independientemente de --max-workers.
• Sincronización incremental: usa fechaRegInicio/fechaRegFin (fecha de registro) para detectar altas/cambios, no fechaConcesion/fechaDesde/fechaHasta (fecha de concesión) — son filtros independientes. Disponible en concesiones-busqueda, ayudasestado-busqueda, minimis-busqueda, partidospoliticos-busqueda.
• terceros: el documento señala este endpoint como redundante — concesiones-busqueda ya devuelve toda la información del beneficiario. Usa concesiones-busqueda y evita terceros.

Limitaciones

• No implementa los endpoints de exportación (CSV/XLSX) ni los de configuración del portal.
• Los resultados de paginación concurrente no están ordenados por número de página.

Licencia y enlaces

• Licencia: GNU General Public License v3.0
• API oficial: https://www.infosubvenciones.es/bdnstrans/api
• Portal BDNS: https://www.infosubvenciones.es
• PyPI: https://pypi.org/project/bdns-fetch

Para más información sobre los datos disponibles, consulta el portal oficial.

bdns-fetch es software libre. ¡Las contribuciones son bienvenidas!