# dati.bg

> AI-first access to official Bulgarian public statistics, public registers, geography and validation services.

Machine discovery: https://dati.bg/.well-known/stats-catalog
Service status: https://dati.bg/api/v1/status
Dataset catalogue: https://dati.bg/api/v1/catalog
Public plan and price comparison: https://dati.bg/api/v1/plans
Remote MCP server: https://dati.bg/mcp
OAuth metadata: https://dati.bg/.well-known/oauth-authorization-server

## Capabilities

### Official statistical data (`official-statistics`)

Search datasets and series, inspect dimensions and retrieve provenance-rich observations from BNB, NSI and other Bulgarian institutions.
REST: /api/v1/catalog, /api/v1/catalog/{dataset}, /api/v1/catalog/{dataset}/series, /api/v1/datasets/{dataset}/observations
MCP: search-catalog-tool, describe-dataset-tool, list-statistical-series-tool, get-statistical-data-tool

### BNB exchange rates (`exchange-rates`)

Retrieve current and historical official BNB exchange rates with release provenance.
REST: /api/v1/catalog/bnb-exchange-rates, /api/v1/exchange-rates
MCP: get-exchange-rates-tool

### Public dashboards and reports (`dashboards`)

Interactive visualisations of important indicators with downloadable Excel reports containing both data and charts.
REST: /dashboards, /dashboards/{dashboard}, /dashboards/{dashboard}/excel
MCP: No dedicated tool; use REST or the web interface.

### Financial Supervision Commission data (`fsc`)

Search public FSC registers, regulatory events, securities, reports, relationships and short-position disclosures.
REST: /api/v1/fsc/registers, /api/v1/fsc/events, /api/v1/fsc/securities, /api/v1/fsc/reports, /api/v1/fsc/relationships, /api/v1/fsc/short-positions
MCP: search-fsc-regulatory-events-tool, search-fsc-securities-tool, search-fsc-reports-tool, search-fsc-relationships-tool

### Entity register memberships (`entity-registers`)

Check an exact EIK against imported public BNB registers. Coverage is explicit; absence is not universal proof of non-membership.
REST: /api/v1/entity-registers, /api/v1/entities/{eik}/register-memberships
MCP: lookup-entity-registers-tool

### Professional registers (`professional-registers`)

Discover and search official registers of private enforcement officers, notaries and insolvency practitioners; the public-enforcement-officer source is catalogued with its coverage limitation.
REST: /api/v1/professional-registers, /api/v1/professional-registers/entries
MCP: search-professional-registers-tool

### Insolvency trustee sales (`aistn-insolvency-sales`)

Search structured current and completed sale announcements from the Ministry of Justice AISTN system. Real properties are normalized separately with offered cadastral or old-plan identifiers, address, explicit areas, ownership share and boundaries. Vehicles, machines, shares, receivables and other assets retain rich descriptions and flexible facts. AI fields include confidence and evidence. Detail records preserve official revisions and attachment metadata; archived files and locally extracted attachment text remain private.
REST: /api/v1/aistn-sales/status, /api/v1/aistn-sales, /api/v1/aistn-sales/{official_uuid}
MCP: search-aistn-sales-tool, get-aistn-sale-tool

### Private enforcement officer property sales (`bcpea-property-sales`)

Search current and historical property-sale announcements from the official BCPEA portal by settlement, court, enforcement officer, property type, area, price, sale deadline, cadastral identifier or sold ownership-share percentage. Properties expose both the source wording in ownership_share and the deterministic numeric ownership_share_percent. Evidence-backed AI properties remain scoped to the exact official listing row: multiple properties in one enforcement sale remain separate, while duplicate extraction inside one row is collapsed. A shared PDF is matched to one source row by area, settlement, address, property type and starting price. Evidence can cite its official source URL, file name and OCR page. Full source HTML is revisioned internally. Official attachment metadata remains public; operator-authorized archived originals, OCR text and raw OCR JSON remain private.
REST: /api/v1/bcpea-property-sales/status, /api/v1/bcpea-property-sales, /api/v1/bcpea-property-sales/{official_numeric_id}
MCP: No dedicated tool; use REST or the web interface.

### NRA property sales (`nra-property-sales`)

Search normalized NRA real-property sales. Each AI property is tied to the exact official tender-item row and includes offered cadastral or old-plan identifiers, address, areas, ownership_share, numeric ownership_share_percent, boundaries, evidence and confidence. Search can be bounded by sold ownership-share percentage. Duplicate extraction inside one row is collapsed, but distinct rows in a multi-property tender remain distinct. Archived source files and OCR text stay private.
REST: /api/v1/nra-property-sales/status, /api/v1/nra-property-sales, /api/v1/nra-property-sales/{official_numeric_id}
MCP: No dedicated tool; use REST or the web interface.

### Private enforcement officer vehicle sales (`bcpea-vehicle-sales`)

Search current and historical vehicle-sale announcements from the official BCPEA portal by vehicle type, brand, model, engine, registration number, VIN, settlement, court, officer, price or deadline. Vehicle specifications and full descriptions are retained. Official attachment links are retained, but /upload/ files are not mirrored because the source robots.txt disallows crawling that path.
REST: /api/v1/bcpea-vehicle-sales/status, /api/v1/bcpea-vehicle-sales, /api/v1/bcpea-vehicle-sales/{official_numeric_id}
MCP: No dedicated tool; use REST or the web interface.

### Private enforcement officer movable-asset sales (`bcpea-asset-sales`)

Search current and historical BCPEA sale announcements for machines, equipment, electronics, furniture, valuables, agricultural products, intellectual-property rights and other movable assets. Full descriptions, prices, dates, officer details and discovered identifiers are retained. Official attachment links are retained, but /upload/ files are not mirrored because the source robots.txt disallows crawling that path.
REST: /api/v1/bcpea-asset-sales/status, /api/v1/bcpea-asset-sales, /api/v1/bcpea-asset-sales/{official_numeric_id}
MCP: No dedicated tool; use REST or the web interface.

### IBAN and BIC services (`iban-bic`)

Validate, normalize, mask and parse IBAN; calculate check digits from a complete BBAN; validate BIC and identify Bulgarian issuers from official versioned sources.
REST: /api/v1/iban, /api/v1/iban/validate, /api/v1/iban/calculate, /api/v1/iban/bic/validate
MCP: validate-iban-tool, calculate-iban-tool, validate-bic-tool

### Bulgarian identifier validators (`bulgarian-identifiers`)

Mathematically validate current BULSTAT/EIK, EGN and LNCH formats and checksums without registry lookup or persistence.
REST: /api/v1/bulgarian-identifiers, /api/v1/bulgarian-identifiers/bulstat/validate, /api/v1/bulgarian-identifiers/egn/validate, /api/v1/bulgarian-identifiers/lnch/validate
MCP: validate-bulstat-tool, validate-egn-tool, validate-lnch-tool

### EKATTE registers (`ekatte`)

Discover official EKATTE tables, releases and changes, then query current or historical register records.
REST: /api/v1/ekatte, /api/v1/ekatte/changes, /api/v1/ekatte/{dataset}, /api/v1/ekatte/{dataset}/records
MCP: search-ekatte-register-tool, get-ekatte-records-tool

### Versioned spatial geography (`geography`)

Discover and query official EKATTE/NUTS GeoJSON layers by version, identifier, name, level or bounding box.
REST: /api/v1/geographies, /api/v1/geographies/{layer}, /api/v1/geographies/{layer}/features
MCP: search-geography-layers-tool, get-geography-features-tool

### Cadastre archives and coordinate locator (`cadastre`)

Discover public KAIS geometry archives. Standard and Huge plans can resolve an exact cadastral identifier to WGS84 coordinates, bounds, public address and a direct Google Maps URL. Ownership data is excluded.
REST: /api/v1/cadastre, /api/v1/cadastre/{resource}, /api/v1/cadastre/{resource}/download, /api/v1/cadastre/locate/{identifier}
MCP: search-cadastre-resources-tool, locate-cadastral-identifier-tool

### Data freshness supervision (`freshness`)

Inspect source-release calendars, latest imported periods and ingestion-agent status to identify stale or failed datasets.
REST: /api/v1/supervision/freshness
MCP: No dedicated tool; use REST or the web interface.

### Accounts, plans, usage and billing (`accounts-and-access`)

Register with email verification or social login, issue a bearer token, inspect current quota and plan, and manage paid subscriptions through Stripe.
REST: /api/v1/register, /api/v1/token, /api/v1/auth/providers, /api/v1/plans, /api/v1/usage, /api/v1/billing, /api/v1/billing/checkout, /api/v1/billing/portal
MCP: service-info-tool

## MCP tool inventory

The following list is generated from the tools registered by the MCP server:

- `service-info-tool`: Returns the identity, current status, and public endpoints of this Bulgarian data service.
- `validate-iban-tool`: Validate, normalize, format, mask, and structurally parse an IBAN using ISO 13616 and MOD 97-10. For Bulgarian IBANs, identify the payment service provider and BAE routing unit from the official BNB directory. This proves syntax and checksums, not account existence or ownership. The supplied IBAN is not persisted.
- `calculate-iban-tool`: Calculate ISO 13616 IBAN check digits from a country code and a complete BBAN, then validate the resulting IBAN. This does not invent an account number, prove that an account exists, or convert arbitrary local account fields into a BBAN.
- `validate-bic-tool`: Validate and parse an 8- or 11-character BIC/SWIFT code under ISO 9362. Optionally cross-check its country and institution prefix against an IBAN. A structurally valid BIC is not proof that the institution or SWIFT connection exists.
- `validate-bulstat-tool`: Validate the length and checksum of a current Bulgarian 9- or 13-digit BULSTAT/EIK. A valid checksum is not proof that an entity is registered or active. Legacy 10-digit personal BULSTAT codes are not accepted as current codes. The identifier is processed transiently and is never returned or stored.
- `validate-egn-tool`: Validate the format, encoded birth date, and checksum of a Bulgarian EGN without looking up a person. Checksum validity is not proof of identity, citizenship, life status, or registry existence. The EGN is never returned, stored, or added to usage metadata; birth date and sex are not disclosed.
- `validate-lnch-tool`: Validate the 10-digit format and checksum of a Bulgarian personal number of a foreigner (LNCH) without a registry lookup. Checksum validity is not proof that the number was issued, remains active, or belongs to a person. The LNCH is never returned, stored, or added to usage metadata.
- `search-catalog-tool`: Search the public dataset catalogue by text or topic. Use this first when you do not already know the dataset slug. Catalogue discovery does not consume quota.
- `describe-dataset-tool`: Describe one dataset, including its meaning, source, coverage, SDMX structure, dimensions, allowed codes, license, and the next API/MCP step. Call this before selecting series.
- `list-statistical-series-tool`: List stable series keys from a statistical dataset. Filters use DIMENSION=CODE syntax. Describe the dataset first so you only use valid dimension and code values. Discovery does not consume quota.
- `get-statistical-data-tool`: Return official observations for exact stable series keys, with full source provenance and revision. Use search-catalog, describe-dataset, and list-statistical-series first.
- `get-exchange-rates-tool`: Returns official BNB exchange rates for selected ISO 4217 currencies, including source, effective date, base currency, retrieval time, and revision.
- `lookup-entity-registers-tool`: Look up an exact Bulgarian EIK/BULSTAT in imported public registers maintained by BNB, with transparent coverage metadata for catalogued NRA registers. Returns official source links and never exposes restricted BNB account or credit data.
- `search-professional-registers-tool`: Search official Bulgarian professional registers for private enforcement officers, notaries and assistant notaries, and insolvency practitioners. Search by name, exact professional registration number, register, or status. Returns no personal identifiers, addresses, phone numbers, or email addresses. NRA public enforcement officers are catalogued as unavailable because no central official public list is published.
- `search-aistn-sales-tool`: Huge monthly plan only. Search structured public sale announcements by Bulgarian insolvency trustees from the Ministry of Justice AISTN system. Filter by debtor, EIK, court, trustee, region, asset type, price, offering date, or an exact offered cadastral identifier found deterministically or by evidence-backed AI extraction. AI confidence and evidence are returned when available. Private archived copies are not exposed.
- `get-aistn-sale-tool`: Huge monthly plan only. Get one structured AISTN insolvency-trustee sale by its official UUID, including assets, deterministic identifiers, the latest evidence-backed AI enrichment, attachment metadata, official download links and revision history. AI confidence and evidence must be preserved. Private attachment archive paths are never exposed.
- `search-fsc-regulatory-events-tool`: Search dated FSC regulatory events for corporate register entries: licences, decisions, revocations, compulsory administrative measures, administrative acts, and register status changes.
- `search-fsc-securities-tool`: Search FSC-registered financial instrument issues by issuer, EIK, ISIN, CFI, stock code, security type, or official issue description. Returns structured issue values and prospectus metadata.
- `search-fsc-reports-tool`: Search official FSC periodic report metadata for issuers, collective and national investment funds, insurers, pension funds, and pension insurance companies.
- `search-fsc-relationships-tool`: Trace official FSC institutional relationships between supervised entities, funds, management companies, depositaries, custodian banks, investment intermediaries, and pension companies.
- `search-ekatte-register-tool`: Discover the complete versioned EKATTE register: populated places, districts, municipalities, mayoralties, city districts, settlement formations, NUTS regions, change documents, annual snapshots, and official change notices. Discovery does not consume quota.
- `get-ekatte-records-tool`: Query current or annual EKATTE register records by dataset, code, name, or an exact source field. Use source_identifier when an older official snapshot contains duplicate source keys.
- `search-geography-layers-tool`: Search versioned official Bulgarian geography layers for EKATTE populated places, municipality boundaries, and NUTS classifications. Discovery does not consume quota.
- `get-geography-features-tool`: Return official EKATTE/NUTS GeoJSON features by layer, identifier, name, unit level, or bounding box. Select the classification version explicitly; NUTS 2027 is not valid before 2027-01-01.
- `search-cadastre-resources-tool`: Search public KAIS cadastral geometry packages by district, municipality, EKATTE, or layer type. Ownership workbooks and personal data are never returned by this tool.
- `locate-cadastral-identifier-tool`: Standard and Huge plans only. Locate an exact Bulgarian cadastral identifier using public AGKK KAIS geometry. Returns WGS84 coordinates, bounding box, Google Maps URL and source provenance. Never returns ownership data.

## Plans and prices

- Free (free): Безплатно; 3 shared REST/MCP requests/day; introductory 100 requests/day for 7 days; cadastral coordinate locator: not included.
- Basic (basic): €1/месец; 10 shared REST/MCP requests/day; cadastral coordinate locator: not included.
- Standard (standard): €5/месец; 50 shared REST/MCP requests/day; cadastral coordinate locator: included.
- Huge (huge): €100/месец; 1000 shared REST/MCP requests/day; cadastral coordinate locator: included.

## Authentication and privacy

Account registration: POST https://dati.bg/api/v1/register
Email verification is required before token issuance: POST https://dati.bg/api/v1/token
Enabled social login providers: https://dati.bg/api/v1/auth/providers
Ownership workbooks and personal data are private and never exposed through public REST API or MCP.
EGN, LNCH and BULSTAT values are processed transiently, are not echoed or persisted, and are not included in usage metadata.
A successful checksum validation does not prove identity, issuance, ownership, registry existence or current status.

## Complete REST API inventory

This list is generated from the live Laravel v1 route collection. `verified_bearer_token` means both bearer authentication and verified email are required.

- GET `/api/v1/aistn-sales` — verified_bearer_token
- GET `/api/v1/aistn-sales/status` — public
- GET `/api/v1/aistn-sales/{sale}` — verified_bearer_token
- GET `/api/v1/auth/providers` — public
- GET `/api/v1/bcpea-asset-sales` — verified_bearer_token
- GET `/api/v1/bcpea-asset-sales/status` — public
- GET `/api/v1/bcpea-asset-sales/{sale}` — verified_bearer_token
- GET `/api/v1/bcpea-property-sales` — verified_bearer_token
- GET `/api/v1/bcpea-property-sales/status` — public
- GET `/api/v1/bcpea-property-sales/{sale}` — verified_bearer_token
- GET `/api/v1/bcpea-vehicle-sales` — verified_bearer_token
- GET `/api/v1/bcpea-vehicle-sales/status` — public
- GET `/api/v1/bcpea-vehicle-sales/{sale}` — verified_bearer_token
- GET `/api/v1/billing` — verified_bearer_token
- POST `/api/v1/billing/checkout` — verified_bearer_token
- POST `/api/v1/billing/portal` — verified_bearer_token
- GET `/api/v1/bulgarian-identifiers` — public
- POST `/api/v1/bulgarian-identifiers/bulstat/validate` — verified_bearer_token
- POST `/api/v1/bulgarian-identifiers/egn/validate` — verified_bearer_token
- POST `/api/v1/bulgarian-identifiers/lnch/validate` — verified_bearer_token
- GET `/api/v1/cadastre` — public
- GET `/api/v1/cadastre/locate/{identifier}` — verified_bearer_token
- GET `/api/v1/cadastre/{resource}` — public
- GET `/api/v1/cadastre/{resource}/download` — verified_bearer_token
- GET `/api/v1/catalog` — public
- GET `/api/v1/catalog/bnb-exchange-rates` — public
- GET `/api/v1/catalog/{dataset}` — public
- GET `/api/v1/catalog/{dataset}/series` — public
- GET `/api/v1/datasets/{dataset}/observations` — verified_bearer_token
- GET `/api/v1/ekatte` — public
- GET `/api/v1/ekatte/changes` — public
- GET `/api/v1/ekatte/{dataset}` — public
- GET `/api/v1/ekatte/{dataset}/records` — verified_bearer_token
- POST `/api/v1/email/verification-notification` — public
- GET `/api/v1/entities/{eik}/register-memberships` — verified_bearer_token
- GET `/api/v1/entity-registers` — public
- GET `/api/v1/exchange-rates` — verified_bearer_token
- GET `/api/v1/fsc/events` — verified_bearer_token
- GET `/api/v1/fsc/events/status` — public
- GET `/api/v1/fsc/registers` — public
- GET `/api/v1/fsc/registers/{register}/entries` — verified_bearer_token
- GET `/api/v1/fsc/registers/{register}/entries/{entry}/events` — verified_bearer_token
- GET `/api/v1/fsc/registers/{register}/entries/{entry}/relationships` — verified_bearer_token
- GET `/api/v1/fsc/registers/{register}/entries/{entry}/reports` — verified_bearer_token
- GET `/api/v1/fsc/registers/{register}/entries/{entry}/securities` — verified_bearer_token
- GET `/api/v1/fsc/relationships` — verified_bearer_token
- GET `/api/v1/fsc/relationships/status` — public
- GET `/api/v1/fsc/reports` — verified_bearer_token
- GET `/api/v1/fsc/reports/status` — public
- GET `/api/v1/fsc/securities` — verified_bearer_token
- GET `/api/v1/fsc/securities/status` — public
- GET `/api/v1/fsc/short-positions` — verified_bearer_token
- GET `/api/v1/geographies` — public
- GET `/api/v1/geographies/{layer}` — public
- GET `/api/v1/geographies/{layer}/features` — verified_bearer_token
- GET `/api/v1/iban` — public
- POST `/api/v1/iban/bic/validate` — verified_bearer_token
- POST `/api/v1/iban/calculate` — verified_bearer_token
- POST `/api/v1/iban/validate` — verified_bearer_token
- GET `/api/v1/nra-property-sales` — verified_bearer_token
- GET `/api/v1/nra-property-sales/status` — public
- GET `/api/v1/nra-property-sales/{sale}` — verified_bearer_token
- GET `/api/v1/plans` — public
- GET `/api/v1/professional-registers` — public
- GET `/api/v1/professional-registers/entries` — verified_bearer_token
- POST `/api/v1/register` — public
- GET `/api/v1/service-info` — verified_bearer_token
- GET `/api/v1/status` — public
- GET `/api/v1/supervision/freshness` — verified_bearer_token
- POST `/api/v1/token` — public
- GET `/api/v1/usage` — verified_bearer_token
- GET `/api/v1/user` — verified_bearer_token

## Recommended workflow

Read the machine catalogue; choose a capability; discover the relevant dataset or register; inspect metadata and plan limits; authenticate when required; request exact data; retain provenance and revision metadata.
Catalogue discovery, status pages and dashboards are public. Metered data requests share the REST/MCP plan quota.
Every statistical data response should retain publisher, source URL, source SHA-256, retrieval time, source preparation time when available, units, validity and release revision.