Документація API
Інтегруйте прогнози якості заходу сонця у свої додатки
Отримайте API ключ для відстеження використанняШвидкий старт
Отримайте прогноз заходу сонця за секунди
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Замініть $SUNSET_API_KEY на ключ з вашої панелі. Запити без авторизації працюють для швидких демо, але мають жорсткіші ліміти й не повертають заголовки rate-limit.
Приклад відповіді
{
"score": 78,
"label": "High",
"explanation": "Scattered clouds and clean air should produce vivid colors near the horizon.",
"confidence": "high",
"location": "Paris, FR",
"predictionType": "sunset",
"sunsetTime": "2026-05-26T19:42:00Z",
"sunriseTime": "2026-05-26T04:51:00Z",
"timezone": "Europe/Paris",
"targetDate": "2026-05-26",
"rawFactors": {
"cloudCover": 15,
"humidity": 55,
"visibility": 18200,
"windSpeed": 5.2,
"windDegree": 180,
"rainProb": 0,
"condition": "clouds",
"temperature": 19.4,
"dewPoint": 10.2,
"pressure": 1015,
"aqi": 2
}
}Автентифікація
Зовнішні запити автентифікуються через заголовок x-api-key. Створіть ключ у своїй панелі керування — необроблений ключ показується рівно один раз.
Заголовок
x-api-key: sp_live_YOUR_API_KEY_HEREНадсилайте свій API-ключ у заголовку запиту x-api-key з кожним викликом.
Області дії
| Область дії | Опис |
|---|---|
| predict:read | Читати прогнози заходу сонця (потрібно для /api/predict) |
| usage:read | Читати статистику використання цього ключа (потрібно для /api/usage) |
Обмеження
Безкоштовний тариф — 100 запитів на день на кожен ключ, скидання опівночі за UTC.
Заголовки відповіді з обмеженням частоти запитів
Кожна успішна автентифікована відповідь містить ці заголовки, щоб ви могли відстежувати квоту в реальному часі:
| X-RateLimit-Limit | Максимальна кількість запитів, дозволена в поточному вікні |
| X-RateLimit-Remaining | Запитів, що залишилися сьогодні |
| X-RateLimit-Reset | Мітка часу у форматі ISO 8601, коли квота скидається |
| Retry-After | Кількість секунд очікування перед повторною спробою (лише для 429) |
Приклад автентифікованого запиту
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Довідник ендпоінтів
Пісочниця API
Тестуйте API прямо з браузера
Починається з sp_live_ і має довжину 40 символів
Зберігається лише в цій вкладці браузера (sessionStorage). Очищається, коли ви закриваєте вкладку.
Сьогодні — на 5 днів уперед. Залиште порожнім для сьогодні.
URL запиту
Приклади коду
Готові приклади популярними мовами
# Set your API key once (mint from /dashboard/api-keys)
export SUNSET_API_KEY="sp_live_YOUR_API_KEY_HERE"
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Приклади оновлюються в реальному часі за параметрами playground.
Відповіді з помилками
Поширені помилки та їх значення
Невірний запит
Відсутні або невірні параметри. Вкажіть місто або lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Не авторизовано
Відсутній, неправильно сформований або відкликаний API-ключ. Надішліть дійсний ключ у заголовку x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Заборонено
Ключ дійсний, але не має області дії predict:read, потрібної для цієї кінцевої точки.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Не знайдено
Вказане місто не знайдено.
{
"error": "City not found",
"code": "cityNotFound"
}Забагато запитів
Перевищено денну квоту (100 запитів/день на безкоштовному тарифі). Скидання опівночі за UTC; перевірте заголовок Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Помилка сервера
Виникла внутрішня помилка сервера. Спробуйте пізніше.
{
"error": "Internal server error"
}Помилковий шлюз
Збій вищого провайдера геокодування. Повторіть спробу з невеликою затримкою; розгляньте можливість надсилання lat/lon, щоб пропустити геокодування.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Найкращі практики
Кешуйте відповіді
Прогнози кешуються на 30 хвилин. Уникайте частіших запитів.
Діапазон дат
Прогнози доступні на сьогодні та до 5 днів наперед. Далекі дати менш точні.
Надавайте перевагу координатам
Використання lat/lon точніше та дозволяє уникнути неоднозначності назв міст.
Обробляйте помилки
Завжди перевіряйте HTTP-код стану та обробляйте відповіді 400/404/500 відповідно.
Дотримуйтеся обмежень частоти запитів
Читайте X-RateLimit-Remaining у кожній відповіді. У разі 429 зачекайте до завершення вікна Retry-After (скидання опівночі за UTC), перш ніж повторювати спробу.
Тримайте ключі на стороні сервера
Ніколи не вбудовуйте API-ключ у публічний клієнтський бандл, мобільний застосунок або репозиторій. Проксіюйте через свій бекенд і зберігайте ключі у змінних середовища чи менеджері секретів.
Використання та ліцензування
Коли достатньо безкоштовного тарифу — і коли потрібен платний план.
Безкоштовний тариф
Безкоштовно для особистого, хобі, розумного дому та тестування.
- •Особисті проєкти та прототипи
- •Хобі та навчання
- •Панелі розумного дому (напр. Home Assistant) для особистого використання
- •Тестування та оцінювання
100 запитів на день на ключ API.
Тариф Plus
Вищі особисті ліміти та сайт без реклами. Лише особисте використання — для комерційних проєктів потрібен Pro.
200 запитів на день на кожен API-ключ, 2 API-ключі.
Комерційне використання
Комерційне використання потребує платного плану — Pro або Business.
Платні тарифи мають вищі денні ліміти й дозволяють більше ключів API.
Переглянути тарифиHome Assistant та інші інтеграції розумного дому залишаються дозволеними на безкоштовному тарифі для особистого, некомерційного використання.
Тримайте ключ API у секреті. Використовуйте його на сервері й ніколи не вбудовуйте в публічний клієнтський код і не комітьте в репозиторій.
Робите комерційний проєкт або застрягли на ліміті? Зв'язатися з підтримкою