Way Tourism API · v1

Документація API

Підключайте курорти, погоду, вебкамери, туристичні місця й послуги до свого продукту через передбачуваний JSON API.

Base URL https://api.way.technology/v1 OpenAPI 3.1 ↗

01 · Початок роботи

Перший запит за кілька хвилин

Створіть обліковий запис, згенеруйте ключ у кабінеті та передайте його як Bearer-токен.

  1. 1
    Створіть акаунт

    Для реєстрації потрібні email і пароль.

  2. 2
    Згенеруйте API-ключ

    Повний ключ відображається тільки один раз.

  3. 3
    Виконайте запит

    Усі захищені ресурси використовують HTTPS та JSON.

Токени запитів. Після реєстрації нараховується 1 000 токенів. Стандартна успішна відповідь списує 1 токен, а нова HLS-сесія на 30 хвилин — 50 токенів. Придбані токени не згорають.
cURLGET /v1/resorts
curl --request GET \
  --url 'https://api.way.technology/v1/resorts?lang=uk&per_page=20' \
  --header 'Authorization: Bearer way_live_YOUR_API_KEY'

02 · Безпека

Авторизація

Передавайте ключ у кожному захищеному запиті. Не додавайте його до URL, клієнтського JavaScript або публічного репозиторію.

Authorization: Bearer way_live_YOUR_API_KEY
Важливо. Якщо ключ втрачено або оприлюднено, відкличте його в кабінеті та створіть новий.

03 · Тарифікація

Як списуються токени

Стандартний успішний захищений запит методом GET або HEAD списує один токен зі спільного балансу акаунта. Створення окремої HLS-сесії коштує 50 токенів. Неважливо, який із ваших API-ключів виконав запит.

ПодіяСписання
Стандартна успішна відповідь захищеного endpoint1 токен
Нова сесія GET /v1/webcams/{id}/hls50 токенів
Повтор HLS-запиту з тим самим Idempotency-Key до expiry0 токенів
Помилка 4xx або 5xx0 токенів
/v1, /v1/health, /v1/openapi.json, OPTIONS0 токенів
Завантаження HLS-сегментів за отриманим stream_url0 додаткових токенів

Баланс зменшується перед відправленням успішної JSON-відповіді. Якщо токенів менше за ціну операції, API повертає 402 insufficient_tokens без списання. Коли баланс досягає нуля, ми надсилаємо лист власнику акаунта; наступні захищені запити повертають 402 quota_exhausted.

04 · Контракт

Формат відповіді

Успішна відповідь містить data і meta. Для списків у meta.pagination повертаються сторінка, розмір, загальна кількість і кількість сторінок.

JSON200 OK
{
  "data": [
    {
      "id": 136,
      "slug": "drahobrat",
      "name": "Драгобрат",
      "elevation": {"bottom_m": 1240, "top_m": 1710}
    }
  ],
  "meta": {
    "language": "uk",
    "pagination": {"page": 1, "per_page": 20, "total": 40, "pages": 2},
    "token_cost": 1,
    "tokens_charged": 1,
    "tokens_remaining": 999,
    "request_id": "…"
  }
}
ПараметрТипЗа замовчуваннямОпис
languk | en | plukМова локалізованих полів
pageinteger1Номер сторінки
per_page1…10020Об’єктів на сторінці

05 · Ресурси

Курорти

Активні туристичні локації з координатами, висотами, інфраструктурою витягів, доступними активностями та поточним станом повʼязаних даних.

GET/v1/resorts

Список курортів

GET/v1/resorts/{slug}

Один курорт

availability одразу показує, чи доступна й чи працює погода та погодна станція, а для камер — скільки зараз online із загальної кількості.

JSONavailability курорту
"availability": {
  "weather": {
    "available": true,
    "working": true,
    "status": "online",
    "source": "meteoblue",
    "endpoint": "/v1/resorts/drahobrat/weather",
    "updated_at": "2026-08-31T04:00:02+03:00",
    "next_update_at": "2026-08-31T12:00:00+03:00",
    "recommended_fetch_at": "2026-08-31T12:15:00+03:00"
  },
  "weather_station": {
    "available": true,
    "working": false,
    "status": "stale",
    "source": "davis_weatherlink",
    "updated_at": "2026-03-30T15:30:01+00:00"
  },
  "photo_archive": {
    "available": true,
    "cameras": 11,
    "endpoint": "/v1/resorts/drahobrat/photo-archive"
  },
  "webcams": {
    "available": true,
    "working": true,
    "status": "partially_online",
    "online": 3,
    "offline": 8,
    "total": 11,
    "endpoint": "/v1/resorts/drahobrat/webcams"
  }
}

Погода

Повний прогноз Meteoblue: поточні умови й погодинні точки на нижній, середній та верхній висотах курорту, денний прогноз, схід і захід сонця та показання погодної станції, якщо вона налаштована.

GET/v1/resorts/{slug}/weather

Погода курорту

hours1…168, стандартно 48 погодинних точок для кожного рівня
Коли забирати оновлення. Читайте update_schedule.recommended_fetch_at. Поточний розклад SNIH — 04:00, 12:00 і 20:00 за Europe/Kyiv; рекомендований час запиту на 15 хвилин пізніше, коли вже мають оновитися всі частини прогнозу. Розклад може змінюватися, тому значення у відповіді є джерелом істини.
JSONСкорочений приклад Драгобрата
{
  "source": "meteoblue",
  "status": "online",
  "working": true,
  "updated_at": "2026-08-31T04:00:02+03:00",
  "timezone": "Europe/Kyiv",
  "update_schedule": {
    "times": ["04:00", "12:00", "20:00"],
    "next_update_at": "2026-08-31T12:00:00+03:00",
    "recommended_fetch_at": "2026-08-31T12:15:00+03:00"
  },
  "default_level": "middle",
  "levels": {
    "bottom": {"elevation_m": 1240, "current": {}, "hourly": []},
    "middle": {"elevation_m": 1475, "current": {}, "hourly": []},
    "top": {"elevation_m": 1710, "current": {}, "hourly": []}
  },
  "daily": [],
  "sunrise_sunset": {
    "status": "online",
    "days": [{"date": "2026-08-31", "sunrise": "06:37", "sunset": "20:08"}],
    "events": [{
      "type": "sunrise",
      "datetime": "2026-08-31T06:37:00+03:00",
      "visibility_score": 95,
      "rating": "excellent"
    }]
  },
  "weather_station": {
    "available": true,
    "working": false,
    "status": "stale",
    "current": null,
    "last_observation": {"observed_at": "2026-03-30T15:30:01+00:00"}
  }
}
СтатусЗначення
onlineДані відповідають поточному розкладу оновлень
staleДжерело є, але останні дані застаріли; перевіряйте updated_at
offlineДжерело налаштоване, але придатних даних зараз немає
unavailableДля цього курорту джерело не підключене

У Meteoblue поле wind вимірюється в км/год, у погодної станції — у м/с. Точні одиниці завжди є в обʼєкті units. weather_station.current містить лише свіже показання; застаріле залишається в last_observation разом із часом вимірювання.

Якщо для курорту немає актуального набору даних, API повертає 404 weather_unavailable.

Вебкамери

Назва, online/offline-статус, координати, актуальне превʼю, poster програвача, наявність звуку та ознака доступності HLS.

GET/v1/resorts/{slug}/webcams

Камери курорту

Список камер не видає внутрішню підписану HLS-адресу. Для online-камери поля hls_available, hls_access_endpoint і hls_token_cost показують, як окремо створити платну сесію. Поле poster_url можна одразу передавати в атрибут poster HTML5-відео.

JSONФрагмент камери
{
  "id": 292,
  "status": "online",
  "stream_url": null,
  "hls_available": true,
  "hls_access_endpoint": "/v1/webcams/292/hls",
  "hls_token_cost": 50,
  "poster_url": "https://i.snih.info/camera/…"
}

Коментарі курортів і камер

GET/v1/resorts/{slug}/comments

Дискусія курорту

GET/v1/webcams/{id}/comments

Та сама дискусія за ID камери

Усі камери курорту мають спільні коментарі. Потрібен Bearer API-ключ; успішний запит коштує 1 токен. Ці маршрути підтримують лише читання.

page: 1–100000, типово 1; per_page: 1–100, типово 20. Пагінація рахує верхні коментарі, новіші першими. Кожен містить повне дерево відповідей у children, старіші першими. meta.pagination.total — кількість верхніх коментарів; meta.comments_count — кількість усіх вузлів дискусії, включно з відповідями та прихованими батьківськими заглушками.

Коментар містить id, parent_id, context_id (0), body, rating, created_at (UTC), публічні дані автора в author, votes_up, votes_down, media та children. Текст залишається мовою оригіналу.

Прихований коментар із публічними відповідями повертається з hidden=true, body=null, rating=null, media=[]. Приховані листові та DEV-коментарі не повертаються. Порожня дискусія — HTTP 200 із data=[]; невідомий курорт або камера — HTTP 404.

GET https://api.way.technology/v1/resorts/drahobrat/comments?page=1&per_page=20
Authorization: Bearer YOUR_API_KEY

Фотоархів вебкамер

Архівні знімки курорту з часом зйомки, камерою, чотирма розмірами зображення та температурою, якщо вона була записана разом зі знімком.

GET/v1/resorts/{slug}/photo-archive

Фотоархів курорту або камери

Два режими. Без webcam_id API повертає по одному останньому доступному знімку кожної камери курорту. З webcam_id повертається повний архів вибраної камери, від нового до старого.
ПараметрЗначенняОпис
webcam_idintegerID з endpoint камер; без нього — останній знімок кожної камери
year2010…2100Рік з meta.calendar.years
month1…12Потребує year
day1…31Потребує year і month
hour0…23Година за Europe/Kyiv; потребує повну дату
page, per_page1…100Пагінація результатів

Як побудувати календар, маючи лише API

  1. 1
    Запит без дати

    calendar.range показує весь період, а calendar.years — роки, де є фото.

  2. 2
    Передайте year

    У наступній відповіді calendar.months міститиме лише місяці з архівом.

  3. 3
    Передайте year і month

    calendar.days поверне доступні дні вибраного місяця.

  4. 4
    Передайте повну дату

    calendar.hours поверне години, для яких реально існують знімки.

Календар завжди рахується для поточного scope: для всього курорту або тільки для камери з webcam_id. Так клієнту не потрібно вгадувати дати чи завантажувати порожні сторінки.

cURLКамера, дата і година
curl --request GET \
  --url 'https://api.way.technology/v1/resorts/drahobrat/photo-archive?webcam_id=292&year=2026&month=8&day=30&hour=16' \
  --header 'Authorization: Bearer way_live_YOUR_API_KEY'
JSONСкорочена відповідь
{
  "data": [{
    "id": 361761,
    "captured_at": "2026-08-30T16:00:00+03:00",
    "webcam": {"id": 292, "name": "Готель «Хата Магната»", "status": "online"},
    "image_url": "https://i.snih.info/archive/151/2026/08/30/16/last.jpg",
    "original_url": "https://i.snih.info/archive/151/2026/08/30/16/last1.jpg",
    "thumbnail_url": "https://i.snih.info/archive/151/2026/08/30/16/last_s.jpg",
    "share_url": "https://i.snih.info/archive/151/2026/08/30/16/share.jpg",
    "weather_temperature_c": null
  }],
  "meta": {
    "mode": "webcam_archive",
    "filters": {"year": 2026, "month": 8, "day": 30, "hour": 16},
    "calendar": {
      "timezone": "Europe/Kyiv",
      "range": {"from": "2023-02-18T16:00:00+02:00", "to": "2026-08-30T16:00:00+03:00"},
      "years": [2026, 2025, 2024, 2023],
      "months": [1, 2, 3, 4, 5, 6, 7, 8],
      "days": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30],
      "hours": [10, 13, 16]
    }
  }
}

Платні HLS-сесії

Endpoint створює підписане 30-хвилинне вікно доступу до однієї online-камери. Вартість нової сесії — 50 токенів. Відлік починається в момент формування відповіді, а не під час першого натискання Play.

Відповідь містить stream_url та old_device_hls_url для старих пристроїв. У другій адресі домен основної трансляції (зокрема CDN у зоні cdn.ua) замінено на hls.snih.info; шлях, параметри підпису та строк дії залишаються тими самими. Обидві адреси належать одній сесії без додаткових списань і повертаються також при повторі з тим самим Idempotency-Key. Якщо основний домен уже hls.snih.info, адреси збігаються.

GET/v1/webcams/{id}/hls

Нова HLS-сесія на 30 хвилин · 50 токенів

Idempotency-Key обовʼязковий. Передайте унікальне значення довжиною 8–128 символів. Повтор із тим самим ключем до завершення сесії поверне той самий URL і спише 0 токенів.
cURLСтворення HLS-сесії
curl --request GET \
  --url 'https://api.way.technology/v1/webcams/292/hls' \
  --header 'Authorization: Bearer way_live_YOUR_API_KEY' \
  --header 'Idempotency-Key: player-drahobrat-20260830-001'
JSON200 OK
{
  "data": {
    "session_id": "hls_…",
    "webcam_id": 292,
    "resort_slug": "drahobrat",
    "stream_url": "https://hls.cdn.ua/…/playlist.m3u8?…",
    "old_device_hls_url": "https://hls.snih.info/…/playlist.m3u8?…",
    "issued_at": "2026-08-30T12:00:00+00:00",
    "expires_at": "2026-08-30T12:30:00+00:00",
    "expires_in_seconds": 1800
  },
  "meta": {
    "token_cost": 50,
    "tokens_charged": 50,
    "tokens_remaining": 950,
    "idempotent_replay": false,
    "request_id": "…"
  }
}
СитуаціяРезультат
Перший запит з новим Idempotency-Key50 токенів, новий URL на 30 хвилин
Повтор того самого запиту до expires_atТой самий URL, tokens_charged: 0
Запит після expires_at зі старим ключем409 idempotency_key_reused
Продовження переглядуНовий Idempotency-Key, нова сесія і ще 50 токенів
HLS playlist і сегменти в межах сесіїБез додаткових списань

Після expires_at медіасервер відхиляє нові запити playlist/сегментів; плеєр може дограти лише вже завантажений короткий буфер. stream_url та old_device_hls_url є тимчасовими секретами: не публікуйте їх та не зберігайте довше строку сесії.

Туристичні місця

Проживання, заклади, розваги, витяги, прокат, SPA, аптеки та інші публічні точки інтересу.

GET/v1/resorts/{slug}/places

Місця курорту

GET/v1/place-types

Довідник типів

Послуги

Опубліковані туристичні послуги: трансфери, інструктори, контакти та базова інформація про ціну.

GET/v1/resorts/{slug}/services

Послуги курорту

06 · Діагностика

Помилки

Помилка завжди містить стабільний машинний code, зрозумілий опис і request_id для пошуку запиту в логах.

JSON401 Unauthorized
{
  "error": {
    "code": "invalid_api_key",
    "message": "API-ключ недійсний, прострочений або відкликаний.",
    "request_id": "…"
  }
}
401unauthorized / invalid_api_key
400invalid_idempotency_key
402quota_exhausted / insufficient_tokens
404not_found / resort_not_found / webcam_not_found / hls_unavailable
409idempotency_key_reused
405method_not_allowed
422invalid_language / invalid_parameter
500internal_error