OpenMercantil Datasets API

Bulk exports (CSV / JSON / aggregated stats)

Documentation GitHub OpenAPI

Operations 13

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v1/datasets/public List the public company dataset downloads · List generation-bound public company downloads #

Ask an LLM

“Which bulk company datasets can I download for free?”

“Where do I find the public company download files and their checksums?”

Tell an agent

List the public company dataset downloads.

Show me the downloadable company data files currently published.

GET /api/v1/ccaa/stats.json Get company totals by autonomous community · Aggregates by autonomous community (CCAA) #

Ask an LLM

“How many companies are registered in each Spanish autonomous community?”

“Can I get per-CCAA aggregates as JSON from the stats.json route?”

Tell an agent

Get the aggregates by autonomous community from ccaa stats.json.

Show company and award-procedure totals for every CCAA.

GET /api/v1/ccaa/stats Get CCAA aggregates via the legacy alias · Get CCAA aggregates through the suffix-less legacy alias #

Ask an LLM

“Does the old suffix-less /ccaa/stats route still work?”

“Which route replaced the deprecated CCAA stats alias?”

Tell an agent

Fetch CCAA aggregates through the legacy suffix-less stats alias.

Call the deprecated ccaa stats route without .json.

GET /api/v1/sectores/stats.json Get company totals by CNAE sector as JSON · Aggregates by CNAE sector #

Ask an LLM

“How many companies are there in each CNAE sector section?”

“Can I get per-sector totals as JSON from sectores stats.json?”

Tell an agent

Get the CNAE sector aggregates from sectores stats.json.

Show company and procurement totals per CNAE section in JSON.

GET /api/v1/sectores/stats Get sector aggregates via the legacy alias · Get CNAE-sector aggregates through the suffix-less legacy alias #

Ask an LLM

“Does the deprecated suffix-less /sectores/stats route still return data?”

“Which route should I use instead of the old sector stats alias?”

Tell an agent

Fetch sector aggregates through the legacy suffix-less sectores stats alias.

Call the deprecated sectores stats route without an extension.

GET /api/v1/sectores/stats.csv Download CNAE sector aggregates as CSV · Aggregates by CNAE sector (CSV) #

Ask an LLM

“Can I download the per-sector statistics as a CSV file?”

“Which columns are in the sector stats CSV?”

Tell an agent

Download the CNAE sector aggregates as CSV.

Export per-sector totals to a spreadsheet file.

GET /api/v1/contracts/top-companies Rank corporate suppliers via top-companies route · Corporate suppliers ranked by PLACSP award procedures #

Ask an LLM

“Which companies top the contracts top-companies ranking by award procedures?”

“Does the top-companies ranking include money totals or only award counts?”

Tell an agent

Get the top {limit} companies by PLACSP award procedures.

Show the top-companies contracts ranking.

GET /api/v1/contracts/top-persons Rank persons by procurement-signing companies · Top persons by PLACSP-signatory companies #

Ask an LLM

“Is there a ranking of people linked to companies that win public contracts?”

“Why does the top-persons contracts ranking always return 503?”

Tell an agent

Get the top persons contracts ranking.

Show which people rank highest by PLACSP-signatory companies.

GET /api/v1/contracts/top-companies.csv Download the top-companies ranking as CSV · Corporate suppliers by award procedures (CSV) #

Ask an LLM

“Can I download the ranking of top procurement suppliers as a CSV?”

“How many rows can the top-companies CSV contain?”

Tell an agent

Download the top {limit} companies by award procedures as CSV.

Export the top-companies contracts ranking to CSV.

GET /api/v1/contracts/top-persons.csv Download the top-persons ranking as CSV · Top persons by PLACSP-signatory companies (CSV) #

Ask an LLM

“Is there a CSV export of the top persons by public contracts?”

“Why does the top-persons CSV download fail with 503?”

Tell an agent

Download the top persons contracts ranking as CSV.

Export the persons-by-PLACSP-signatory ranking to a CSV file.

GET /api/v1/export/events Request the bulk BORME events export · Bulk BORME export (offline artifact required) #

Ask an LLM

“Can I bulk download every BORME event in one export?”

“Why is the bulk BORME export unavailable?”

Tell an agent

Request the bulk BORME events export.

Download all BORME events as a single export.

GET /api/v1/export/companies Request a bulk company export · Request an offline company export artifact (currently unavailable) #

Ask an LLM

“Can I export a filtered list of all companies in a province?”

“Which plan and scope do I need for the bulk company export?”

Tell an agent

Export all {tipo} companies in {provincia}.

Request a bulk company export in {formato} format.

GET /api/v1/company/{slug}/export Download a single company report as JSON · Export a single company report #

Ask an LLM

“Can I download one company's report as a JSON file?”

“Is there a size limit on a single company export?”

Tell an agent

Export the company report for {company} as JSON.

Download {company}'s report to a file.

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/openmercantil:openmercantil-datasets-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: OpenMercantil Datasets API
  version: 1.9.3
  summary: Versioned public-read, browser-account, billing, support and provider-callback contracts.
  description: Public JSON API for Spanish company information derived from BORME and other public sources.
  termsOfService: https://openmercantil.es/terminos-de-uso
  contact:
    name: OpenMercantil
    url: https://openmercantil.es/soporte
    email: social@openmercantil.es
  license:
    name: Source-specific upstream terms; see response catalog metadata
    url: https://openmercantil.es/terminos-de-uso
  x-publisher:
    name: OpenMercantil
    url: https://openmercantil.es/
    email: social@openmercantil.es
  x-spatial: http://publications.europa.eu/resource/authority/country/ESP
  x-temporal: 2009-01-01/..
  x-language: es
  x-dcat-catalog: https://openmercantil.es/catalog.rdf
  x-rate-limit:
    free:
      per_min: 60
      per_day: 200
      kind: anonymous-ip
    profesional:
      per_min: 120
      per_day: 5000
      kind: api-key
    max:
      per_min: 600
      per_day: 50000
      kind: api-key
    enterprise:
      per_min: 1200
      per_day: 500000
      kind: contract
  x-methodology: https://openmercantil.es/metodologia
  x-sources: https://openmercantil.es/fuentes
  x-corrections: https://openmercantil.es/correcciones
  x-contract-status: Public read, browser-account and provider-callback surfaces are explicitly separated in this contract. Operator/admin routes are excluded. The public MCP consumes only the allowlisted GET read plane.
  x-account-segment-contract:
    projection: company_public_v2 immutable corporate sidecar
    synchronous_row_cap: 500
    bounded_count_cap: 50001
    count_semantics: The segment run response count is the number of rows returned, never a global total. Dataset preview uses total_is_lower_bound=true and total_lower_bound when the bounded count reaches 50001.
    related_web_dataset_surface:
      preview_path: /mi-cuenta/datasets/preview
      export_path: /mi-cuenta/datasets/export.csv
      synchronous_export_max_rows: 500
      overflow_status: 503
      overflow_error: async_export_required
  x-company-identity-contract:
    version: '1.0'
    projection: company_public_v2 immutable generation-bound corporate sidecar
    applies_to: Every /api/v1/company/{slug}*, /api/v1/empresa/{slug}* and /api/v1/grafo/{slug} read before any report, cache, graph or dataset lookup. /api/v1/companies/compare resolves both requested subjects in one bounded company_public_v2 batch before either row is exposed; MCP company tools inherit these preflights through REST.
    resolution:
      published: canonical corporate slug admitted
      safe_alias: internally canonicalized and Content-Location emitted
      withheld: neutral 404; includes absent, personal and ambiguous/quarantined identities
      unavailable: 503 with no-store; clients must not infer absence
    search: Exact corporate CIF, exact canonical/safe-alias slug, or bounded name_prefix2 pool scored in application code. DNI/NIE and ambiguous CIFs return zero items.
    public_company_count: company_public_projection_state.row_count
servers:
- url: https://openmercantil.es
  description: Production
tags:


# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openmercantil/refs/heads/main/openapi/openmercantil-datasets-api-openapi.yml

OpenMercantil Datasets API

Operations 13

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification