API та відкриті дані для розробників

OpenAPI

openapi.yaml — опис усіх публічних ендпоінтів зі схемами запитів і відповідей. Канонічна адреса https://malin.kiev.ua/openapi.yaml перенаправляє на поточний сервер бекенду, тож зберігайте саме її. Відкрити можна в будь-якому переглядачі OpenAPI (Swagger Editor, Redoc, Stoplight) або згенерувати клієнт.

curl -sL https://malin.kiev.ua/openapi.yaml | head -20

Транспорт Малина

• GTFS Static (/transport/gtfs.zip) — зупинки, маршрути, рейси з часом на кожній зупинці, лінії; feed_version = revision датасету, ETag той самий — зміну розкладу видно умовним запитом без завантаження;
• JSON наживо (/transport/dataset) і знімок збірки (/transport/dataset.json) — повний датасет у форматі сайту: сегменти з тривалістю перегонів, варіанти шляху, опорні часи, тариф і контакти в meta;
• RSS змін розкладу (/transport/changes.rss) — запис на кожну нову версію даних із підсумком, що саме змінилось; те саме машинно — журнал ревізій /transport/revisions (JSON із diff); календар рейсів маршруту — /transport/route/<id>/calendar.ics (підписка за адресою, час у Europe/Kyiv);
• GET /transport/stops/<id> — зупинка за стабільним id (злита → 301 на чинну), /transport/stop-redirects — уся мапа «старий id → чинний»;
• записи з табло — POST /transport/sticker-scans, sticker-returns, arrival-reports: анонімні, сервер дедуплікує; описані в OpenAPI разом із вікнами й кодами відповідей.

curl -sIL https://malin.kiev.ua/transport/gtfs.zip | grep -i etag
curl -sL https://malin.kiev.ua/transport/gtfs/feed_info.txt

Що ми обіцяємо: стабільні id

• id зупинки st_NNNN і номер маршруту (route_id) не змінюються й не перевикористовуються — ті самі в адресах сайту (/transport/stop/st_0019, /transport/route/11), у JSON і в GTFS;
• перейменування зупинки не змінює id; номер, який бачать люди («11/1»), — окреме поле shortName;
• злита або видалена зупинка лишає запис «старий id → чинний» у meta.stopRedirects датасету щонайменше рік;
• revision — ISO-час останньої зміни, монотонний, той самий у датасеті, GTFS і ETag; id рейсів (trip_id) стабільні лише в межах однієї revision.

Попутки й міжміські

GET /trip-points — міста; GET /viber-listings і GET /viber-listings/search?date=&fromCode=&toCode= — активні оголошення без контактів; GET /poputky/search?from=&to=&date= — попутки, розклад маршруток і вільні місця одним запитом. Контакт автора — лише окремим запитом по кліку, як і на сайті; персональні дані в API не віддаються.

Ліцензія й увічливість

Дані — під OwnNet Source License 1.1: вільно для людей, міста й бізнесу з доходом до 100 000 USD на рік, з атрибуцією Дані: malin.kiev.ua — Сергій Меренков / ТОВ «Технології» (technologies.llc); більшим компаніям і платним сервісам — за договором. Перевіряйте зміни умовним запитом (If-None-Match) не частіше ніж раз на 5 хвилин, для розкладу досить разу на добу. Детальніше — відкриті дані транспорту Малина; помилки в даних і питання — контакти.