{ "openapi": "3.1.0", "info": { "title": "Нишка – открити данни (Nishka open data)", "version": "0.1.0", "summary": "Checked Bulgarian public-service facts, legal deadlines and official documents.", "description": "No account and no key. All answers are JSON (Основа also offers CSV). Any site may call these APIs (CORS *).\n\nFor AI agents the same data is an MCP server at https://nishka.app/mcp. Guide in Bulgarian: https://nishka.app/razrabotchitsi.\n\nCite the official source URL of every fact or document, with its check or publication date. Основа is CC BY 4.0 („Основа, проверени данни на Нишка (nishka.app), CC BY 4.0“); Извор and Срок point to official records, whose text is authoritative.", "contact": { "url": "https://nishka.app/razrabotchitsi" }, "license": { "name": "CC BY 4.0 (Основа data)", "url": "https://creativecommons.org/licenses/by/4.0/deed.bg" } }, "servers": [ { "url": "https://nishka.app" } ], "tags": [ { "name": "Основа", "description": "Checked facts about institutions, services and procedures in Plovdiv, Sofia, Varna and Burgas." }, { "name": "Срок", "description": "Bulgarian working days and legal deadline counting (ГПК чл. 60)." }, { "name": "Извор", "description": "An index of Bulgarian primary official sources: the State Gazette, council decisions, public procurement." } ], "paths": { "/osnova/v0/entries": { "get": { "tags": [ "Основа" ], "operationId": "searchOsnova", "summary": "Entries matching a query, best first", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Words to find, in Bulgarian, e.g. „лична карта“. Without q, entries in id order.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Limit to one city.", "schema": { "type": "string", "enum": [ "plovdiv", "sofia", "varna", "burgas" ] } }, { "name": "kind", "in": "query", "required": false, "description": "service: an institution or office; rule: a procedure.", "schema": { "type": "string", "enum": [ "service", "rule" ] } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many entries.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "attribution": { "type": "string" }, "licence": { "type": "string" }, "contentHash": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/OsnovaEntry" } } }, "required": [ "attribution", "licence", "contentHash", "entries" ] } } } } } } }, "/osnova/v0/entries/{city}/{kind}/{slug}": { "get": { "tags": [ "Основа" ], "operationId": "getOsnovaEntry", "summary": "One entry with all its facts", "parameters": [ { "name": "city", "in": "path", "required": true, "description": "e.g. plovdiv", "schema": { "type": "string" } }, { "name": "kind", "in": "path", "required": true, "description": "service or rule", "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "description": "e.g. op-chistota", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "attribution": { "type": "string" }, "licence": { "type": "string" }, "contentHash": { "type": "string" }, "entry": { "$ref": "#/components/schemas/OsnovaEntry" } }, "required": [ "attribution", "licence", "contentHash", "entry" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/osnova/v0/manifest.json": { "get": { "tags": [ "Основа" ], "operationId": "osnovaManifest", "summary": "Version, licence, counts and the date of the latest check", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OsnovaManifest" } } } } } } }, "/osnova/v0/osnova.json": { "get": { "tags": [ "Основа" ], "operationId": "osnovaDownload", "summary": "The whole dataset", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest": { "$ref": "#/components/schemas/OsnovaManifest" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/OsnovaEntry" } } }, "required": [ "manifest", "entries" ] } } } } } } }, "/osnova/v0/facts.csv": { "get": { "tags": [ "Основа" ], "operationId": "osnovaCsv", "summary": "Every fact, one per row (UTF-8 with BOM)", "responses": { "200": { "description": "Columns: entry_id, city, district, kind, name_bg, key, value, source_url, source_title, checked_on, expires_at, review", "content": { "text/csv": { "schema": { "type": "string" } } } } } } }, "/srok/v0/deadline": { "get": { "tags": [ "Срок" ], "operationId": "srokDeadline", "summary": "The last day of a deadline and each step of the count", "description": "Counts as the Civil Procedure Code does (ГПК чл. 60). Other laws can have their own rules; every result names the rule it used.", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "The day of the event the deadline runs from, e.g. the day a letter was received.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] } }, { "name": "amount", "in": "query", "required": true, "description": "How many units.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "unit", "in": "query", "required": false, "description": "The unit of the period.", "schema": { "type": "string", "enum": [ "days", "weeks", "months", "years", "working_days" ], "default": "days" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/srok/v0/day/{date}": { "get": { "tags": [ "Срок" ], "operationId": "srokDay", "summary": "Whether a day is a working day in Bulgaria, and why not", "parameters": [ { "name": "date", "in": "path", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DayInfo" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/srok/v0/year/{year}": { "get": { "tags": [ "Срок" ], "operationId": "srokYear", "summary": "Every non-working weekday and working weekend day of a year", "parameters": [ { "name": "year", "in": "path", "required": true, "description": "2020–2099", "schema": { "type": "integer", "minimum": 2020, "maximum": 2099 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YearCalendar" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/izvor/v0/search": { "get": { "tags": [ "Извор" ], "operationId": "searchIzvor", "summary": "Records from primary sources, best first", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Words to find, in Bulgarian, e.g. „бюджет 2027“.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "One source id (see /izvor/v0/status).", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "One kind of record.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Earliest publication date.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] } }, { "name": "to", "in": "query", "required": false, "description": "Latest publication date.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many records.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/IzvorDocument" } } }, "required": [ "documents" ] } } } }, "503": { "description": "Извор's database cannot be read right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/izvor/v0/documents/{id}": { "get": { "tags": [ "Извор" ], "operationId": "getIzvorDocument", "summary": "One record", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "source:id as search returns it, URL-encoded, e.g. dv%3A12345", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/IzvorDocument" } }, "required": [ "document" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Извор's database cannot be read right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/izvor/v0/status": { "get": { "tags": [ "Извор" ], "operationId": "izvorStatus", "summary": "The sources, their record counts and their last collection", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "titleBg": { "type": "string" }, "homepage": { "type": "string" } } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "documents": { "type": "integer" }, "latestPublishedOn": { "type": [ "string", "null" ] }, "lastRunAt": { "type": [ "string", "null" ] }, "lastRunFailure": { "type": [ "string", "null" ] } } } } }, "required": [ "sources", "status" ] } } } }, "503": { "description": "Извор's database cannot be read right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Source": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } }, "required": [ "url", "title" ] }, "OsnovaFact": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "source": { "$ref": "#/components/schemas/Source" }, "checkedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ], "description": "The day the fact was checked against its source (Bulgarian calendar)." }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this moment the fact must be checked again." }, "volatility": { "type": "string" }, "review": { "type": "string", "enum": [ "approved", "approved_pending_second_check" ] } }, "required": [ "key", "value", "source", "checkedOn", "expiresAt", "review" ] }, "OsnovaEntry": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "plovdiv/service/op-chistota" ] }, "city": { "type": "string" }, "district": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "names": { "type": "object", "properties": { "bg": { "type": "string" }, "en": { "type": "string" } }, "required": [ "bg", "en" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "related": { "type": "array", "items": { "type": "string" } }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/OsnovaFact" } } }, "required": [ "id", "city", "kind", "names", "facts" ] }, "OsnovaManifest": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "licence": { "type": "string" }, "licenceUrl": { "type": "string", "format": "uri" }, "attribution": { "type": "string" }, "home": { "type": "string", "format": "uri" }, "contentHash": { "type": "string", "description": "Changes whenever any fact changes; cite it with the date." }, "lastCheckedOn": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] }, "counts": { "type": "object", "properties": { "entries": { "type": "integer" }, "facts": { "type": "integer" }, "cities": { "type": "object", "additionalProperties": { "type": "integer" } } } } }, "required": [ "name", "version", "licence", "attribution", "contentHash", "counts" ] }, "DayInfo": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] }, "working": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "holiday", "carry_over", "decided_non_working", "decided_working", "weekend", "working" ] }, "reasonBg": { "type": [ "string", "null" ] }, "basis": { "type": [ "string", "null" ] }, "source": { "oneOf": [ { "$ref": "#/components/schemas/Source" }, { "type": "null" } ] } }, "required": [ "date", "working", "kind", "reasonBg", "basis", "source" ] }, "YearCalendar": { "type": "object", "properties": { "year": { "type": "integer" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/DayInfo" } }, "decisionsChecked": { "type": "boolean", "description": "False when the Council of Ministers' decisions for this year have not been checked." } }, "required": [ "year", "days", "decisionsChecked" ] }, "DeadlineResult": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "countedEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ], "description": "Where the count lands before the non-working-day rule." }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ], "description": "The last day to act." }, "movedOver": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ] }, "reasonBg": { "type": "string" } } } }, "rule": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "gpk-60", "working-days" ] }, "titleBg": { "type": "string" }, "source": { "oneOf": [ { "$ref": "#/components/schemas/Source" }, { "type": "null" } ] } } }, "calendarChecked": { "type": "boolean" }, "stepsBg": { "type": "array", "items": { "type": "string" }, "description": "The count in plain Bulgarian, one step per line." } }, "required": [ "from", "amount", "unit", "countedEnd", "end", "movedOver", "rule", "calendarChecked", "stepsBg" ] }, "IzvorDocument": { "type": "object", "properties": { "id": { "type": "string", "description": "source:externalId" }, "source": { "type": "string" }, "externalId": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "issuer": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "publishedOn": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-10-27" ], "description": "The date the source gives the document." }, "url": { "type": "string", "format": "uri", "description": "The official record. Cite this." }, "documentUrl": { "type": [ "string", "null" ], "format": "uri" }, "excerpt": { "type": "string", "description": "The start of the text, for search and orientation only." }, "firstSeenAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "changedAt": { "type": "string", "format": "date-time", "description": "When Извор last saw the source change this record." } }, "required": [ "id", "source", "title", "url", "publishedOn" ] } } } }