Documentacion API

Rate limiting

Free: 60 req/min y 200 req/día por IP. Planes superiores (Profesional 5.000 req/día, MAX 50.000 req/día, Enterprise 500.000+ req/día) según cuenta y API key.

Las respuestas incluyen estas cabeceras (RFC draft-ietf-httpapi-ratelimit-headers):

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

Errores

Ejemplo de respuesta de error:

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

Paginacion

La API usa dos esquemas según el endpoint:

La respuesta siempre incluye total o count para calcular el número 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.

/api/v1/search

Busca empresas (y opcionalmente personas) por nombre o CIF usando un indice por prefijos. Devuelve resultados ordenados por relevancia.

Parametros

Respuesta

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

import requests
r = requests.get("https://openmercantil.es/api/v1/search", params={"q":"inditex","limit":5})
print(r.json())

const res = await fetch("https://openmercantil.es/api/v1/search?q=inditex&limit=5");
const data = await res.json();
console.log(data.items);

/api/v1/company/{slug}

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

Parametros

Respuesta

curl "https://openmercantil.es/api/v1/company/inditex-sa-a15075062"

import requests
slug = "inditex-sa-a15075062"
r = requests.get(f"https://openmercantil.es/api/v1/company/{slug}")
data = r.json()
print(data["kpis"]["acts_count"])

const slug = "inditex-sa-a15075062";
const res = await fetch(`https://openmercantil.es/api/v1/company/${slug}`);
const { company, kpis } = await res.json();
console.log(company.name, kpis.last_seen);

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

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

Parametros

Respuesta

curl "https://openmercantil.es/api/v1/company/inditex-sa-a15075062/events?year=2025&page=1&page_size=20"

import requests
r = requests.get("https://openmercantil.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://openmercantil.es/api/v1/company/inditex-sa-a15075062/events?year=2025&page=1"
);
const { events, total } = await res.json();

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

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

Parametros

Respuesta

curl "https://openmercantil.es/api/v1/company/inditex-sa-a15075062/officers"

import requests
r = requests.get("https://openmercantil.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://openmercantil.es/api/v1/company/inditex-sa-a15075062/officers");
const { officers } = await res.json();
officers.current.forEach(c => console.log(c.name, c.role));

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

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

Parametros

Respuesta

curl -O -J "https://openmercantil.es/api/v1/company/inditex-sa-a15075062/export?format=json"

import requests
r = requests.get("https://openmercantil.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://openmercantil.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">

/api/v1/person/search

Busca personas fisicas por nombre en el indice de cargos del BORME.

Parametros

Respuesta

curl "https://openmercantil.es/api/v1/person/search?q=amancio+ortega&limit=5"

import requests
r = requests.get("https://openmercantil.es/api/v1/person/search", params={"q":"amancio ortega"})
print(r.json()["items"])

const res = await fetch("https://openmercantil.es/api/v1/person/search?q=amancio%20ortega");
const { items } = await res.json();

/api/v1/person/{slug}

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

Parametros

Respuesta

curl "https://openmercantil.es/api/v1/person/amancio-ortega-gaona"

import requests
r = requests.get("https://openmercantil.es/api/v1/person/amancio-ortega-gaona")
p = r.json()
print(p["name"], "—", p["companies_count"], "empresas")

const res = await fetch("https://openmercantil.es/api/v1/person/amancio-ortega-gaona");
const person = await res.json();
console.log(person.active_positions);

/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

Respuesta

curl "https://openmercantil.es/api/v1/daily/2026-04-17"

import requests
r = requests.get("https://openmercantil.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://openmercantil.es/api/v1/daily/2026-04-17");
const { date, sections } = await res.json();
const seccion1 = sections["1"];
console.log(Object.keys(seccion1)); // provincias

/api/v1/health

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

Parametros

Respuesta

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

import requests
r = requests.get("https://openmercantil.es/api/v1/health")
h = r.json()
print(h["status"], "—", h["companies_indexed_approx"], "empresas")

const res = await fetch("https://openmercantil.es/api/v1/health");
const health = await res.json();
console.log(health.status, health.latest_borme_processed);

/api/v1/export/events

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

Parametros

Respuesta

curl -O "https://openmercantil.es/api/v1/export/events?year=2025&format=csv"

import requests
r = requests.get("https://openmercantil.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://openmercantil.es/api/v1/export/events?year=2025&format=csv");
const text = await res.text();
// parsear con PapaParse u otro parser CSV

/export

Endpoint legado de exportacion CSV. Acepta empresa, persona o búsqueda libre.

Parametros

Respuesta

# Por empresa
curl -O "https://openmercantil.es/export?format=csv&empresa=inditex-sa-a15075062"

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

# Por búsqueda
curl -O "https://openmercantil.es/export?format=csv&q=mercadona"

import requests
r = requests.get("https://openmercantil.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://openmercantil.es/export?format=csv&empresa=inditex-sa-a15075062");
const blob = await res.blob();
const url = URL.createObjectURL(blob);

Endpoints v1.1 — Sectores, Score, Fuentes externas

Endpoints añadidos en abril 2026 para navegación CNAE, score de actividad, gadgets visuales y datos de fuentes externas.

Ejemplo: empresas TI en Madrid ordenadas por actividad

curl "https://openmercantil.es/api/v1/sector/62/companies?province=madrid&sort=acts&limit=10"

Ejemplo: score + similares de una empresa

curl "https://openmercantil.es/api/v1/company/inditex-sa-a15075062/score" | jq
curl "https://openmercantil.es/api/v1/company/inditex-sa-a15075062/similar?limit=5" | jq

🆕 Endpoints v1.4 (mayo 2026)

Cruce abierto BORME × CNMV × OEPM × PLACSP × BOE × sanciones. Sin API key, rate-limit suave, cache 1h.

Trust Score (educativo)

GET /api/v1/company/{slug}/trust-score

Score 0-100 basado en datos públicos. NO es scoring crediticio. Devuelve {score, band, label, factors[], disclaimer}. Cache 24h.

Sociograma de cargos

GET /api/v1/company/{slug}/network

Bipartite graph: empresa central → admins → otras empresas con admins comunes. Renderizable con vis-network o D3.js. Limit 12 personas × 4 empresas.

Embargos AEAT/TGSS (BOE)

GET /api/v1/company/{slug}/embargoes

Diligencias de embargo + subastas + liberaciones publicadas en BOE Sección V-B. Devuelve {count, summary, items[]} con tipo, importe, expediente, organismo, fecha y URL al anuncio oficial.

Contratos PLACSP (persona)

GET /api/v1/persona/{slug}/contracts

Contratos públicos adjudicados a empresas que esta persona administra(ba). Solo cuenta contratos firmados durante el período del cargo. Devuelve {count, total_eur, by_company[], top[], by_cpv[]}.

Top empresas por licitaciones

GET /api/v1/contracts/top-companies?limit=50&province=madrid&cnae=F
GET /api/v1/contracts/top-companies.csv?limit=100  # Excel-friendly UTF-8 BOM

Filtros opcionales: province (slug), cnae (sección A-U), limit (1-500).

Top personas por licitaciones

GET /api/v1/contracts/top-persons?limit=30
GET /api/v1/contracts/top-persons.csv?limit=100

Personas administradoras con más contratos públicos en empresas que dirigen. Período del cargo se respeta.

Estadísticas sectoriales (CNAE)

GET /api/v1/sectores/stats        # JSON
GET /api/v1/sectores/stats.csv    # Excel

Por sección CNAE: total empresas, activas/extintas/concurso, capital total inscrito, contratos PLACSP. Cache 24h.

Estadísticas por CCAA

GET /api/v1/ccaa/stats            # 18 CCAA + Ceuta + Melilla

Distribución geográfica por Comunidad Autónoma. Cruce automático provincia → CCAA.

Geocode + mapa

GET /api/v1/company/{slug}/geocode[?force=1]

Devuelve {lat, lng, address, source}. Cache hit instantáneo. Cache miss: live Nominatim OSM (rate-limit 1 req/sec). force=1 bypassa cache.

⚠️ Nota legal: Trust Score es educativo (NO scoring crediticio profesional). Embargos pueden no incluir resoluciones posteriores. Contratos PLACSP no incluyen modificaciones contractuales. Para due diligence consulta fuentes oficiales o proveedores acreditados.

Changelog