API — українські прислів'я

Базовий шлях: https://verbacorpus.org/api/v1. Усі ендпоінти публічні, CORS відкрито (*), без ключа.

Формат відповіді обирається через параметр ?format=json|jsonl|xml|csv|tsv або заголовок Accept (наприклад Accept: application/x-ndjson). За замовчуванням — json. Ендпоінти колекцій повертають заголовок X-Total-Count із загальною кількістю результатів.

application/json application/x-ndjson application/xml text/csv text/tab-separated-values

OpenAPI 3.0.3 специфікація (JSON) →

Пошук

Повнотекстовий і семантичний пошук по корпусу.

GET /api/v1/search Повнотекстовий пошук

Шукає прислів'я за ключовим словом (MiniSearch). Без q повертає весь корпус із пагінацією.

Параметр	Тип	Опис
q	string	Пошуковий запит.
category	string	Ключ теми (напр. `work_labor`).
source	string	Ідентифікатор джерела (напр. `Franko1901`).
limit	integer	Кількість (1–200, за замовч. 50).
offset	integer	Зміщення для пагінації.
format	enum	json · jsonl · xml · csv · tsv

Приклади

curl 'https://verbacorpus.org/api/v1/search?q=гроші&format=csv'

curl 'https://verbacorpus.org/api/v1/search?q=праця&source=Franko1901&limit=10'

curl -H 'Accept: application/x-ndjson' \
  'https://verbacorpus.org/api/v1/search?q=вода'

GET /api/v1/semantic Семантичний пошук

Вбудовує запит через BGE-M3 і знаходить найближчі прислів'я через Vectorize. Результати містять поле score (0–1).

Параметр	Тип	Опис
q *	string	Природномовний запит.
category	string	Фільтр за темою.
source	string	Фільтр за джерелом.
minScore	float	Мінімальний поріг схожості (0–1, за замовч. 0.4).
limit	integer	Кількість результатів.
format	enum	json · jsonl · xml · csv · tsv

Приклад

curl 'https://verbacorpus.org/api/v1/semantic?q=важка+праця+приносить+плоди'

curl 'https://verbacorpus.org/api/v1/semantic?q=дружба&minScore=0.5&format=tsv'

Перегляд

Фільтрація, випадкові записи та масове вивантаження.

GET /api/v1/random Випадкові прислів'я

Повертає одне або кілька випадкових прислів'їв, за потреби з фільтром.

Параметр	Тип	Опис
n	integer	Кількість (1–50, за замовч. 1).
category	string	Фільтр за темою.
source	string	Фільтр за джерелом.
format	enum	json · jsonl · xml · csv · tsv

Приклади

curl 'https://verbacorpus.org/api/v1/random?n=3'

curl 'https://verbacorpus.org/api/v1/random?n=5&category=family&format=xml'

GET /api/v1/query Структурований фільтр

Фільтрує корпус за темою, джерелом, групою варіантів або наявністю пояснення. Без параметрів повертає всі записи з пагінацією.

Параметр	Тип	Опис
category	string	Ключ теми.
source	string	Ідентифікатор джерела.
variant_group	string	Група варіантів.
has_explanation	boolean	`true` — тільки з поясненнями.
limit	integer	Кількість (1–200, за замовч. 50).
offset	integer	Зміщення.
format	enum	json · jsonl · xml · csv · tsv

Приклади

curl 'https://verbacorpus.org/api/v1/query?source=Franko1901&limit=20'

curl 'https://verbacorpus.org/api/v1/query?has_explanation=true&format=tsv'

GET /api/v1/proverb/{id} Отримати прислів'я за ID

Повертає один запис разом із поясненням (якщо є).

Параметр	Тип	Опис
id *	path	Ідентифікатор запису, напр. `p000001`.
format	enum	json · jsonl · xml · csv · tsv

Приклади

curl 'https://verbacorpus.org/api/v1/proverb/p000001'

curl 'https://verbacorpus.org/api/v1/proverb/p000001?format=xml'

GET /api/v1/export Масове вивантаження

Повертає весь корпус (або відфільтровану підмножину) одним запитом. Включає поле explanation. Для великих завантажень рекомендується CSV або TSV.

Параметр	Тип	Опис
category	string	Фільтр за темою.
source	string	Фільтр за джерелом.
format	enum	json · jsonl · xml · csv · tsv

Приклади

curl -H 'Accept: application/x-ndjson' \
  'https://verbacorpus.org/api/v1/export' > proverbs.ndjson

curl 'https://verbacorpus.org/api/v1/export?format=csv' > proverbs.csv

curl 'https://verbacorpus.org/api/v1/export?source=Franko1901&format=tsv'

Метадані

Теми та статистика корпусу.

GET /api/v1/categories Список тем із лічильниками

Повертає масив об'єктів {key, label, count} для всіх тематичних категорій.

Приклад

curl 'https://verbacorpus.org/api/v1/categories'

GET /api/v1/meta Метадані корпусу

Повна статистика: загальна кількість, розбивка за джерелами та темами, дата збірки.

Приклад

curl 'https://verbacorpus.org/api/v1/meta'

Схема запису

Структура об'єкта Proverb у відповідях JSON/JSONL/XML.

Поле	Тип	Опис
id	string	Унікальний ідентифікатор запису (`p000001`).
text	string	Оригінальний текст.
modern_text	string	Сучасне написання.
category	string[]	Масив ключів тем.
sources	string[]	Масив ідентифікаторів джерел.
variant_group	string \| null	Ключ групи варіантів.
explanation	string \| null	Наукове пояснення (де є).

CSV та TSV включають ті ж поля як рядки; масиви подаються через кому. explanation з'являється тільки в /export та /proverb/{id}.