Referencia completa v1

Documentacion API

REST + JSON. Sin autenticacion. CORS abierto. Base URL: https://openborme.es

Empezar en 30 segundos

Copia cualquiera de estos comandos. No necesitas clave de API.

1. Buscar una empresa

curl "https://openborme.es/api/v1/search?q=mercadona&limit=5"

2. Obtener ficha completa de empresa

curl "https://openborme.es/api/v1/company/mercadona-sa-a46103834"

3. Estado del sistema

curl "https://openborme.es/api/v1/health"

Rate limiting

El servidor permite 60 peticiones por minuto por IP y rafagas de hasta 10 req/s. Las respuestas incluyen las siguientes cabeceras:

CabeceraDescripcion
X-RateLimit-LimitLimite maximo de peticiones por ventana (60).
X-RateLimit-RemainingPeticiones restantes en la ventana actual.
X-RateLimit-ResetTimestamp Unix en que se reinicia el contador.
Retry-AfterSegundos a esperar (solo en respuestas 429).

Para cargas masivas usa los datasets descargables en lugar de recorrer la API en bucle.

Errores

CodigoSignificadoCausa habitual
200 OKExitoPeticion correcta con resultados.
400 Bad RequestParametro invalidoFalta q, formato de fecha incorrecto, etc.
404 Not FoundRecurso inexistenteSlug de empresa o persona desconocido.
429 Too Many RequestsRate limit superadoMas de 60 req/min desde la misma IP.
500 Internal Server ErrorError internoArtefacto corrupto o fallo de proceso.

Ejemplo de respuesta de error:

{
  "error": "not_found",
  "message": "Company slug not found",
  "status": 404
}

Paginacion

La API usa dos esquemas segun el endpoint:

EndpointParametrosNotas
Busqueda (/search)limit + offsetDesplazamiento clasico. Max limit=100.
Eventos empresa (/events)page + page_sizePaginacion por numero de pagina. Default page_size=50.

La respuesta siempre incluye total o count para calcular el numero de paginas.

Bulk downloads

Si necesitas miles de registros, descarga los datasets completos desde /descargas en lugar de llamar la API en bucle. Estan disponibles:

  • Indice de empresas en JSON (comprimido .gz)
  • Indice de personas en JSON
  • Dataset completo de eventos en CSV por ano
  • Snapshots mensuales de cargos vigentes

Usa la API para consultas puntuales y los datasets para analisis masivo, ETL o entrenamiento de modelos.

GET

Ficha completa de empresa

/api/v1/company/{slug}

Devuelve el informe completo de una empresa: datos registrales, KPIs, timeline de actividad, cargos y lista de actos.

Parametros

NombreTipoRequeridoDefaultDescripcion
slugstringsiIdentificador slug de la empresa (nombre-cif). Ej: inditex-sa-a15075062.

Respuesta

CampoTipoDescripcion
company.namestringNombre oficial.
company.cifstringCIF/NIF registral.
company.statusstringEstado actual: ACTIVA, EXTINGUIDA, DISOLUCION, etc.
company.company_typestringTipo societario (SA, SL, etc.).
company.aliasesarrayNombres anteriores o variaciones.
company.addressstringDomicilio social.
company.capitalstringCapital social declarado.
company.websitestringSitio web si consta en BORME.
company.workersintNum. de trabajadores si consta.
company.date_creationstringFecha de constitucion.
kpis.acts_countintTotal de actos registrados.
kpis.first_seenstringPrimera fecha en el sistema.
kpis.last_seenstringUltima fecha en el sistema.
timelinearrayArray {period, count} mensual.
top_event_typesarrayTipos de acto mas frecuentes.
top_provincesarrayProvincias de actividad.
eventsarrayActos recientes (max 50 por defecto).
officers.currentarrayCargos vigentes.
officers.historicalarrayCargos anteriores.
summary_textstringResumen en lenguaje natural.
curl "https://openborme.es/api/v1/company/inditex-sa-a15075062"
import requests
slug = "inditex-sa-a15075062"
r = requests.get(f"https://openborme.es/api/v1/company/{slug}")
data = r.json()
print(data["kpis"]["acts_count"])
const slug = "inditex-sa-a15075062";
const res = await fetch(`https://openborme.es/api/v1/company/${slug}`);
const { company, kpis } = await res.json();
console.log(company.name, kpis.last_seen);
GET

Eventos paginados de empresa

/api/v1/company/{slug}/events

Devuelve los actos registrales de una empresa para un ano concreto, paginados para respuestas ligeras.

Parametros

NombreTipoRequeridoDefaultDescripcion
slugstringsiSlug de la empresa.
yearintnoAno a filtrar (YYYY). Sin valor, devuelve todos.
pageintno1Numero de pagina (base 1).
page_sizeintno50Resultados por pagina.

Respuesta

CampoTipoDescripcion
slugstringSlug de la empresa.
yearintAno filtrado.
pageintPagina actual.
page_sizeintResultados por pagina.
totalintTotal de eventos para el ano/filtro.
eventsarrayArray de actos: {id, date, type, province, description}.
curl "https://openborme.es/api/v1/company/inditex-sa-a15075062/events?year=2025&page=1&page_size=20"
import requests
r = requests.get("https://openborme.es/api/v1/company/inditex-sa-a15075062/events",
    params={"year":2025,"page":1,"page_size":20})
print(r.json()["total"])
const res = await fetch(
  "https://openborme.es/api/v1/company/inditex-sa-a15075062/events?year=2025&page=1"
);
const { events, total } = await res.json();
GET

Cargos de empresa

/api/v1/company/{slug}/officers

Devuelve administradores, apoderados y otros cargos, separados en vigentes e historicos.

Parametros

NombreTipoRequeridoDefaultDescripcion
slugstringsiSlug de la empresa.

Respuesta

CampoTipoDescripcion
slugstringSlug de la empresa.
officers.currentarrayCargos vigentes: {name, role, person_slug, date_from}.
officers.historicalarrayCargos anteriores: {name, role, person_slug, date_from, date_to}.
curl "https://openborme.es/api/v1/company/inditex-sa-a15075062/officers"
import requests
r = requests.get("https://openborme.es/api/v1/company/inditex-sa-a15075062/officers")
for c in r.json()["officers"]["current"]:
    print(c["name"], c["role"])
const res = await fetch("https://openborme.es/api/v1/company/inditex-sa-a15075062/officers");
const { officers } = await res.json();
officers.current.forEach(c => console.log(c.name, c.role));
GET

Exportar empresa (JSON adjunto)

/api/v1/company/{slug}/export

Devuelve el informe completo como fichero descargable con Content-Disposition: attachment.

Parametros

NombreTipoRequeridoDefaultDescripcion
slugstringsiSlug de la empresa.
formatstringnojsonFormato de exportacion (actualmente solo json).

Respuesta

CampoTipoDescripcion
application/jsonMismo esquema que /company/{slug} pero con cabecera de descarga.
curl -O -J "https://openborme.es/api/v1/company/inditex-sa-a15075062/export?format=json"
import requests
r = requests.get("https://openborme.es/api/v1/company/inditex-sa-a15075062/export?format=json")
with open("informe.json","wb") as f:
    f.write(r.content)
const res = await fetch("https://openborme.es/api/v1/company/inditex-sa-a15075062/export?format=json");
const blob = await res.blob();
const url = URL.createObjectURL(blob);
// asignar a un <a download="informe.json">
GET

Ficha de persona

/api/v1/person/{slug}

Devuelve el perfil completo de una persona: cargos activos, historicos y empresas vinculadas.

Parametros

NombreTipoRequeridoDefaultDescripcion
slugstringsiSlug normalizado de la persona.

Respuesta

CampoTipoDescripcion
slugstringSlug de la persona.
namestringNombre completo.
first_seenstringPrimera aparicion en BORME.
last_seenstringUltima aparicion en BORME.
companies_countintTotal de empresas en las que ha tenido cargo.
active_positionsarrayCargos vigentes: {company_name, slug, role, date_from}.
inactive_positionsarrayCargos anteriores: {company_name, slug, role, date_from, date_to}.
curl "https://openborme.es/api/v1/person/amancio-ortega-gaona"
import requests
r = requests.get("https://openborme.es/api/v1/person/amancio-ortega-gaona")
p = r.json()
print(p["name"], "—", p["companies_count"], "empresas")
const res = await fetch("https://openborme.es/api/v1/person/amancio-ortega-gaona");
const person = await res.json();
console.log(person.active_positions);
GET

Sumario diario BORME

/api/v1/daily/{YYYY-MM-DD}

Devuelve todos los actos publicados en el BORME para una fecha, agrupados por seccion y provincia. Alias: /api/v1/summary/date/{YYYY-MM-DD}.

Parametros

NombreTipoRequeridoDefaultDescripcion
YYYY-MM-DDstringsiFecha en formato ISO 8601. Ej: 2026-04-17.

Respuesta

CampoTipoDescripcion
datestringFecha consultada.
sectionsobjectObjeto con secciones BORME (1=SA/SL, 2=otros, 3=concursal). Cada seccion es un objeto provincia → [{id, company, type, slug}].
curl "https://openborme.es/api/v1/daily/2026-04-17"
import requests
r = requests.get("https://openborme.es/api/v1/daily/2026-04-17")
data = r.json()
for prov, actos in data["sections"]["1"].items():
    print(prov, len(actos), "actos")
const res = await fetch("https://openborme.es/api/v1/daily/2026-04-17");
const { date, sections } = await res.json();
const seccion1 = sections["1"];
console.log(Object.keys(seccion1)); // provincias
GET

Health check

/api/v1/health

Devuelve el estado operativo del sistema, la edad de los artefactos y metricas de volumen.

Parametros

NombreTipoRequeridoDefaultDescripcion

Respuesta

CampoTipoDescripcion
statusstringok o degraded.
servicestringNombre del servicio.
versionstringVersion de la API.
artifacts_age_hoursfloatHoras desde la ultima actualizacion de artefactos.
artifacts_last_modifiedstringFecha ISO del ultimo artefacto.
latest_borme_processedstringUltima fecha de BORME procesada.
companies_indexed_approxintEmpresas indexadas aproximadas.
total_persons_approxintPersonas indexadas aproximadas.
total_events_approxintEventos totales aproximados.
csv_size_mbfloatTamano del CSV principal en MB.
timestampstringFecha/hora de la respuesta en ISO 8601.
curl "https://openborme.es/api/v1/health"
import requests
r = requests.get("https://openborme.es/api/v1/health")
h = r.json()
print(h["status"], "—", h["companies_indexed_approx"], "empresas")
const res = await fetch("https://openborme.es/api/v1/health");
const health = await res.json();
console.log(health.status, health.latest_borme_processed);
GET

Export de eventos en CSV

/api/v1/export/events

Streaming CSV de todos los eventos, opcionalmente filtrado por ano. Util para analisis de datos y ETL.

Parametros

NombreTipoRequeridoDefaultDescripcion
yearintnoAno a filtrar (YYYY). Sin valor, devuelve todos.
formatstringnocsvSolo csv por ahora.

Respuesta

CampoTipoDescripcion
text/csvFichero CSV con cabecera: id, date, company_slug, company_name, type, province, description.
curl -O "https://openborme.es/api/v1/export/events?year=2025&format=csv"
import requests
r = requests.get("https://openborme.es/api/v1/export/events", params={"year":2025,"format":"csv"}, stream=True)
with open("eventos_2025.csv","wb") as f:
    for chunk in r.iter_content(chunk_size=8192):
        f.write(chunk)
const res = await fetch("https://openborme.es/api/v1/export/events?year=2025&format=csv");
const text = await res.text();
// parsear con PapaParse u otro parser CSV
GET

Export CSV directo

/export

Endpoint legado de exportacion CSV. Acepta empresa, persona o busqueda libre.

Parametros

NombreTipoRequeridoDefaultDescripcion
formatstringsicsvDebe ser csv.
empresastringnoSlug de empresa.
personastringnoSlug de persona.
qstringnoTexto de busqueda para exportar resultados.

Respuesta

CampoTipoDescripcion
text/csvCSV de los actos de la empresa/persona o resultados de busqueda.
# Por empresa
curl -O "https://openborme.es/export?format=csv&empresa=inditex-sa-a15075062"

# Por persona
curl -O "https://openborme.es/export?format=csv&persona=amancio-ortega-gaona"

# Por busqueda
curl -O "https://openborme.es/export?format=csv&q=mercadona"
import requests
r = requests.get("https://openborme.es/export",
    params={"format":"csv","empresa":"inditex-sa-a15075062"})
with open("empresa.csv","wb") as f:
    f.write(r.content)
const res = await fetch("https://openborme.es/export?format=csv&empresa=inditex-sa-a15075062");
const blob = await res.blob();
const url = URL.createObjectURL(blob);

Changelog

VersionFechaCambios
v1.0 2026-04-17 Release inicial. Endpoints de busqueda, ficha empresa/persona, sumario diario, exportacion CSV, health check y documentacion publica.
Datasets descargables Volver a API Uso intensivo o soporte