Engineering notes · Open data
BORME data is open. Reliable company intelligence is the hard part.
Spain publishes incorporations, officer changes, capital operations, insolvencies, dissolutions and other company acts in BORME, the Boletín Oficial del Registro Mercantil. The source is public. The digital archive covers publications from January 2009; the Agencia Estatal Boletín Oficial del Estado launched its current open-data API service on 28 June 2024. It exposes daily summaries and province-level XML documents without authentication.
That is excellent news if you need one document or a research sample. It does not make a production company-data service free. Source acquisition is only the first layer; the recurring cost sits in normalization, provenance, replay, identity, current-state reconstruction and operations.
Choose the layer you actually need
There are three sensible ways to use BORME data.
| Layer | What you receive | What you maintain |
|---|---|---|
| BOE source | Official summaries and documents | Everything downstream |
| Apify Actor | Normalized events for selected publication dates | Storage and state |
| Hosted API | Indexed search, history and monitoring | Your application logic |
Build directly from BOE
Best for research, an occasional document, a one-off dataset, or a team whose parser is itself a strategic asset. You own downloading, format changes, normalization, historical replay, entity resolution, monitoring and the audit trail. The upstream facts are public; the engineering and operational risk are yours.
Run the Apify Actor
Best for a bounded extraction by publication date, province, company-name substring or event type. The Apify Actor downloads and normalizes Section A company events into a fresh dataset, charging only for the run and delivered events. You keep control of storage and downstream logic without maintaining a BORME downloader and parser.
Query the Hosted API
Best when BORME data is part of an application or business process. The Hosted API adds an indexed historical corpus, company search, assembled timelines and profiles, monitoring, webhooks and read-oriented MCP access. This is the layer for onboarding, supplier risk, credit, sales signals and agent workflows that cannot rebuild state from raw daily publications on every request.
Run normalized BORME events on Apify Open the Hosted API docs
What the open-data API actually gives you
The discovery request for a publication day is small:
GET https://www.boe.es/datosabiertos/api/borme/sumario/20260821
Accept: application/json
User-Agent: your-product/1.0 [email protected]The response points to the provincial XML documents for that issue. XML is a much better machine source than scraping PDF layout, and the official summary is the right discovery mechanism. Keep both the summary and original bytes: they are the evidence needed to audit a result or reparse history later.
The BOE open-data page is the source documentation and reuse entry point. BORME API is an independent reuser, not BOE or the Registro Mercantil. The feed does not create full deeds, annual accounts or certified present-day authority.
Reuse is subject to the conditions linked from the BOE BORME open-data FAQ. AEBOE also states that the electronically signed PDF is the only official and authentic edition; XML and normalized output are reusable working formats, not certified replacements for it.
The request is easy. A reliable pipeline must additionally decide what “no
publication” means, reject XML error documents returned with 200 OK, identify
Section A documents, store immutable sources, retry safely, checkpoint every
day and file, and replay derived records without duplicates.
Downloading is the easy part
Moving from PDF to XML removes OCR and page-break failures. It does not turn Spanish legal shorthand into a stable schema. These six archive cases become permanent maintenance obligations.
1. A 404 can contain XML
Weekends and holidays return HTTP 404 with an XML body even when JSON was requested. Publication state must be handled before content negotiation.
2. A missing document can return 200
A province without a source document may answer 200 OK with an XML <error>
element. Status-only ingestion quietly stores an error page as a bulletin.
3. Punctuation can be company data
In DAMI DELUSION S.L. the final dot can belong to the legal form. A broad
rstrip('.') changes the published company name and weakens later matching.
4. One paragraph is an ordered event chain
Ceses/Dimisiones. Adm. Unico: X. Nombramientos. Liquidador: X. Disolución.
Extinción. Datos registrales... is one article containing several linked acts.
Line splitting or one regular expression usually captures the first label and
loses the rest.
5. Provinces and legal forms have dialects
Capitalization, role abbreviations, cooperative bodies and bilingual province names vary. Normalize input without destroying the source spelling needed for audit and identity work.
6. Dates and money cross eras
The archive contains several short and long Spanish date formats. Older text can quote pesetas. A parser must preserve unknown text and remain testable across the 2009, mid-archive and current formats.
These are not one-time fixes. A maintained service detects new variants, adds fixtures, reparses affected history and explains what changed.
The event model is the product decision
BORME is not a current company directory. It is an event source: what changed, when it was published and which document said so. A useful record keeps the published company name, ordered acts, officer roles, registry coordinates, deterministic ID and original text together.
{
"event_id": "sha1:...",
"date": "2026-08-21",
"borme_id": "BORME-A-2026-...",
"province": "MADRID",
"company_name": "EXAMPLE SL.",
"acts": [{
"act_type": "APPOINTMENTS",
"roles": [{"role": "SOLE_DIRECTOR", "names": ["..."]}],
"payload_raw": "..."
}],
"registral": {"hoja": "M 123456", "inscription": "4"},
"raw_text": "...",
"unparsed_spans": []
}Current officers, capital or legal status require an appropriately complete, ordered history plus state-folding and entity-resolution rules. Corrections, renames and ambiguous names make that a different product from downloading a day of XML.
The Actor deliberately returns dated events. The hosted service maintains the indexed history needed for company-oriented queries. Neither should pretend a gazette notice is a certified current registry extract.
Quality needs a visible failure mode
Well-formed JSON does not prove that a parser understood the source. We record unparsed spans and act tails and calculate a per-file character-coverage metric. The documented 30-day measurement was 99.89% in August 2026.
That number is a drift signal, not a universal accuracy claim. Unfamiliar text can remain inside raw payload fields and count as consumed; every decision-relevant result should retain source identifiers and text for review.
A production test suite also needs fixtures across archive eras and provinces, stable event IDs, act-order invariants, idempotent replacement and a proven failure when a new label appears. The cost is not writing the first parser. It is keeping the parser honest after the source changes.
The real build-versus-buy calculation
The archive is large enough to require engineering, yet small enough that “we can download it” sounds deceptively reassuring. We processed about 9.5 million events across roughly 3.3 million company records from 2 January 2009 onward, measured in August 2026. Acquisition is finite. Maintenance is not.
Before building, price the complete system:
- source monitoring, retries, checkpoints and immutable raw storage;
- parser vocabulary, regression fixtures and historical reparses;
- deterministic IDs, provenance and duplicate-safe replacement;
- company identity across spelling changes, renames, NIF and registry sheets;
- ordered state reconstruction and point-in-time queries;
- access control, quotas, exports, webhooks, MCP and operational support.
If you need a few documents, use BOE directly. If you need normalized events for selected dates, run the Actor. If company changes are part of a production workflow, compare the hosted API with the cost of owning every item above—not with the zero acquisition price of the XML.
Extract events with the Apify Actor Build on the Hosted API