빠른 시작
몇 초 만에 일몰 예측 받기
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모든 호출에서 x-api-key 요청 헤더에 API 키를 보내세요.
스코프
| 스코프 | 설명 |
|---|---|
| predict:read | 일몰 예측 읽기 (/api/predict에 필요) |
| usage:read | 이 키 자체의 사용 통계 읽기 (/api/usage에 필요) |
한도
무료 요금제 — 키당 하루 100건, UTC 자정에 초기화돼요.
Rate-limit 응답 헤더
인증된 모든 성공 응답에는 다음 헤더가 포함되어 있어 할당량을 실시간으로 확인할 수 있어요.
| 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를 테스트해 보세요. API 키를 붙여넣으면 인증된 호출을 보내며(일일 할당량에서 차감돼요), 비워 두면 인증 없는 시연 호출을 보내요.
오늘부터 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"위의 플레이그라운드 매개변수를 바꾸면 스니펫이 실시간으로 업데이트돼요.
오류 응답
일반적인 오류 응답과 그 의미
Bad Request
매개변수가 없거나 올바르지 않아요. city 또는 lat/lon 중 하나를 입력하세요.
{
"error": "Either lat/lon or city must be provided"
}Unauthorized
API 키가 없거나, 형식이 잘못되었거나, 폐기되었어요. x-api-key 헤더에 유효한 키를 보내세요.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Forbidden
키는 유효하지만 이 엔드포인트에 필요한 predict:read 스코프가 없어요.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Not Found
지정한 도시를 찾을 수 없어요.
{
"error": "City not found",
"code": "cityNotFound"
}Too Many Requests
일일 할당량을 초과했어요(무료 요금제는 하루 100건). UTC 자정에 초기화되며, Retry-After 헤더를 확인하세요.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Server Error
내부 서버 오류가 발생했어요. 잠시 후 다시 시도하세요.
{
"error": "Internal server error"
}Bad Gateway
상위 지오코딩 제공자에서 오류가 발생했어요. 잠시 간격을 두고 다시 시도하거나, lat/lon을 보내 지오코딩을 건너뛰는 방법을 고려하세요.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}모범 사례
응답 캐시하기
예측은 (lat, lon, lang, date)별로 서버에서 20분 동안 캐시돼요. 그보다 자주 폴링하지 마세요.
날짜 범위
예측은 어제부터 5일 후까지 제공돼요. 그보다 먼 날짜는 정확도가 떨어지는 결과가 반환돼요.
좌표 사용 권장
lat/lon을 사용하면 더 정확하고, 여러 지역에 같은 이름이 있는 도시의 모호함을 피할 수 있으며, 지오코딩도 건너뛰어요.
오류를 안전하게 처리하기
HTTP 상태 코드와 응답의 code 필드를 확인하세요. 401/403은 사용자에게 알리고, 429는 Retry-After를 따라 요청을 늦추세요.
Rate limit 지키기
모든 응답에서 X-RateLimit-Remaining을 확인하세요. 429가 오면 Retry-After 시간(UTC 자정 초기화)이 지난 뒤에 다시 시도하세요.
키는 서버에서만 사용하기
공개 클라이언트 번들, 모바일 앱, 저장소에 API 키를 넣지 마세요. 백엔드를 통해 프록시하고 키는 환경 변수나 시크릿 관리자에 보관하세요.
사용 및 라이선스
무료 요금제로 충분한 경우와 유료 요금제가 필요한 경우를 안내해요.
무료 요금제
개인, 취미, 스마트홈, 테스트 용도로 무료예요.
- •개인 프로젝트와 프로토타입
- •취미 및 학습
- •개인용 스마트홈 대시보드 (예: Home Assistant)
- •테스트 및 평가
API 키당 하루 100건 요청.
Plus 요금제
후원자를 위한 더 높은 개인 사용 한도와 광고 없는 사이트를 제공해요. 개인 용도 전용이며, 상업 프로젝트에는 Pro가 필요해요.
API 키당 하루 200건 요청, API 키 2개.
Home Assistant 및 기타 스마트홈 연동은 개인 비상업적 용도라면 무료 요금제에서도 계속 사용할 수 있어요.
API 키는 비밀로 유지하세요. 서버 측에서 사용하고, 공개 클라이언트 코드에 넣거나 저장소에 커밋하지 마세요.
상업용 서비스를 만들고 계신가요, 아니면 해결하기 어려운 한도에 부딪히셨나요? 고객 지원 문의