API

API Puls надає доступ лише для читання до словникових статей зі сторінки слів. Відповіді надходять у форматі JSON.

Як отримати ключ

Кожен запит потребує API-ключа. Ключі видають наші API-менеджери, тож зверніться до нас, щоб отримати ключ. Ключ показують лише один раз, під час створення, тому збережіть його в надійному місці. Тримайте ключ на своєму сервері й не вбудовуйте його в код для браузера чи мобільного застосунку.

Автентифікація

Передавайте ключ у заголовку Authorization:

curl -H "Authorization: Bearer YOUR_KEY" https://puls.peremova.org/api/v1/entries

Також можна використати заголовок X-Api-Key.

Список слів

GET https://puls.peremova.org/api/v1/entries

Параметр	Опис
q	Пошук за написанням (без урахування регістру, частковий збіг).
level	Одне або кілька значень: A1, A2, B1, B2, C1
part_of_speech	Одне або кілька значень: noun, adj, pron, numr, verb_imperfective, verb_perfective, adv, prep, conj, part, intj, noninfl
entry_type	Одне або кілька значень: meaning, phrase, idiom, proverb
topic	Один або кілька ідентифікаторів тем.
order_by	Одне зі значень: label, guideword, level, part_of_speech, created_at. Типово: label.
direction	asc або desc. Типово: desc.
page	Номер сторінки, починаючи з 1.
per_page	Кількість слів на сторінці: типово 50, максимум 100.

Фільтри, що приймають кілька значень, приймають або одне значення ?level=B1 або список ?level[]=A1&level[]=A2.

Приклад відповіді

{
  "data": [
    {
      "id": "meaning-42",
      "entry_type": "meaning",
      "label": "яблуко",
      "guideword": "фрукт",
      "level": "A1",
      "part_of_speech": "noun",
      "aspect": null,
      "lexeme_id": 17,
      "url": "https://puls.peremova.org/lexemes/17#meaning_42"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "pages": 12, "count": 583 }
}

id поєднує тип і номер статті, напр. meaning-42 або phrase-7. Використовуйте його для ідентифікації статей.

aspect заповнюється лише для дієслів (perfective або imperfective).

Обмеження частоти запитів

Кожен ключ може надсилати до 60 запитів на хвилину. Якщо ліміт перевищено, API відповідає кодом 429 із заголовком Retry-After, що вказує, скільки секунд зачекати. Запити без ключа або з неправильним ключем також обмежено: до 20 на хвилину з однієї IP-адреси.

Помилки

У разі помилки API повертає JSON, наприклад {"error": "Invalid or missing API key"}.

400	Некоректний параметр, наприклад непідтримуване сортування, неіснуюча сторінка чи нечислове значення per_page.
401	Ключ відсутній, неправильний або відкликаний.
429	Забагато запитів або спроб із неправильним ключем.