Genera leads a partir de empresas de nueva creación

1. Introducción

En este mini-tutorial vamos a aprender cómo se puede usar LibreBOR API para consultar las empresas constituidas en la provincia de Madrid un día específico.

Al finalizar tendremos un programa que se ejecuta a diario y hace una llamada a la API para posteriormente guardar los resultados en un archivo CSV.

La implementación está hecha en el lenguaje de programación Python pero se puede hacer con cualquier otro lenguaje. Para más información, consulta el manual de referencia correspondiente.

2. Obtención de credenciales

Lo primero que tenemos que hacer es obtener las credenciales de acceso. Estas se encuentran en tu Panel de Usuario en la sección API > Credenciales.

Anota tu nombre de usuario y contraseña una vez los tengas localizados.

3. Construcción de la URL

A continuación necesitaremos construir la URL correcta para comunicarnos con la API. De la Referencia de API obtenemos los siguientes datos:

  • URL base: https://api.librebor.me/v2 (importante: la API solo funciona con https)
  • Método HTTP: GET
  • Ruta: /summary/new-companies/{year}/{month}/{day}/
  • Parámetros: province, year, month y day (todos son números)

4. Implementación

Para el ejemplo imaginemos que nos interesa conocer las empresas que se han constituido en Madrid el día 1 de febrero de 2022, el parámetro province será 28 (coincidiendo con los dos primeros números del código postal asociado a la provincia).

Por lo tanto los parámetros necesarios son los siguientes:

  • Usuario y Contraseña: (obtenidos en el primer paso)
  • year: 2022
  • month: 2
  • day: 1
  • province: 28

Y la URL final es:

https://api.librebor.me/v2/summary/new-companies/2022/2/1/?province=28

Ahora vamos a implementar esta petición HTTP a la API en Python usando la librería python-requests:

#!/usr/bin/env python3
from pprint import pprint

import requests

# Credentials
AUTHENTICATION = requests.auth.HTTPBasicAuth("USERNAME", "PASSWORD")
# API base url, you can also use https://sandbox-api.librebor.me/v2
URL_BASE = "https://api.librebor.me/v2"


def print_new_companies(year, month, day, province):
    params = {"province": province}
    url = f"{URL_BASE}/summary/new-companies/{year}/{month}/{day}/"
    req = requests.get(url, params=params, auth=AUTHENTICATION)
    result = req.json()
    print(result)


if __name__ == "__main__":
    print_new_companies(2022, 2, 1, 28)

5. Código final

Por último vamos a programar un script en Python más completo que consulte estos datos y los guarde en un archivo CSV.

#!/usr/bin/env python3
import csv
import datetime

import requests

PROVINCE = 28
# Credentials
AUTHENTICATION = requests.auth.HTTPBasicAuth("USERNAME", "PASSWORD")
# Output file
FILENAME = "companies.csv"
# API base url, you can also use https://sandbox-api.librebor.me/v2
URL_BASE = "https://api.librebor.me/v2"


def new_companies(date):
    """Query LibreBOR API for new companies."""
    year, month, day = date.year, date.month, date.day
    params = {"province": PROVINCE}
    url = f"{URL_BASE}/summary/new-companies/{year}/{month}/{day}/"
    req = requests.get(url, params=params, auth=AUTHENTICATION)
    req.raise_for_status()
    return req.json()


def save_companies_csv(companies):
    """Loop over the results and save them to the CSV file."""
    total_saved = 0
    csvfile = open(FILENAME, "w")
    csvwriter = csv.writer(csvfile)
    for summary in companies["summary"]:
        for company in summary["new_companies"]:
            row = [
                company["name"],
                company["slug"],
                company["purpose"],
                company["capital"],
                company["address"],
                company["date_creation"],
            ]
            csvwriter.writerow(row)
            total_saved += 1
    csvfile.close()
    return total_saved


if __name__ == "__main__":
    date = datetime.date.today()
    # You an also define a specific date
    # date = datetime.date(2022, 2, 1)
    companies = new_companies(date)
    total_companies = save_companies_csv(companies)
    print(f"{total_companies} new companies were saved to {FILENAME}")

6. Ejecución periódica

Si nos interesa ejecutar este script cada día para mantener el archivo CSV actualizado podemos utilizar cron, una herramienta que está presente en la mayoría de sistemas Linux.

Primero ejecutamos guardaremos el código del punto anterior en un archivo (en este ejemplo se ha utilizado la ruta /home/user/new_companies.py). Después ejecutamos el comando crontab -e y a continuación añadimos la siguiente línea:

0 11 * * 1-5 /home/user/new_companies.py

De esta forma el script se ejecutará a las 11AM todos los días de lunes a viernes.