Документация 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 в секрете. Используйте его на стороне сервера и никогда не встраивайте в публичный клиентский код и не коммитьте в репозиторий.
Делаете коммерческий проект или столкнулись с лимитом, который не можете обойти? Связаться с поддержкой