クイックスタート
数秒で夕焼け予測を取得
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"$SUNSET_API_KEY をダッシュボードのキーに置き換えてください。認証なしの呼び出しはデモには使えますが、より厳しい制限があり、レート制限ヘッダーは返されません。
レスポンス例
{
"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 に必要） |
制限
無料プラン — キーごとに1日100リクエスト、UTC の午前0時にリセット。
レート制限のレスポンスヘッダー
認証済みの成功レスポンスにはこれらのヘッダーが付与され、クォータをリアルタイムで追跡できます。
| 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をテスト
今日から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"サンプルは上記のプレイグラウンドのパラメータに合わせてリアルタイム更新されます。
エラーレスポンス
一般的なエラーレスポンスとその意味
不正なリクエスト
パラメータが不足しているか無効です。都市または緯度/経度を指定してください。
{
"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"
}リクエストが多すぎます
1日のクォータを超過しました（無料プランは1日100リクエスト）。UTC の午前0時にリセットされます。Retry-After ヘッダーを確認してください。
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}サーバーエラー
内部サーバーエラーが発生しました。後でもう一度お試しください。
{
"error": "Internal server error"
}Bad Gateway
上流のジオコーディングプロバイダーで障害が発生しました。少し間隔を空けて再試行してください。lat/lon を送信してジオコーディングをスキップすることも検討してください。
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}ベストプラクティス
レスポンスのキャッシュ
予測は30分間キャッシュされます。それより頻繁なポーリングは避けてください。
日付範囲
予測は今日から5日先まで利用可能です。より先の日付は精度が低くなります。
座標を推奨
緯度/経度の使用はより正確で、地域間で共有される都市名のあいまいさを回避します。
適切なエラー処理
常にHTTPステータスコードを確認し、400/404/500レスポンスを適切に処理してください。
レート制限を遵守する
すべてのレスポンスで X-RateLimit-Remaining を確認してください。429 の場合は、再試行する前に Retry-After のウィンドウ（UTC の午前0時リセット）を待ってください。
キーはサーバー側で管理する
公開クライアントのバンドル、モバイルアプリ、リポジトリに API キーを埋め込まないでください。自社のバックエンド経由でプロキシし、キーは環境変数やシークレットマネージャーに保存してください。
利用とライセンス
無料プランで十分な場合と、有料プランが必要な場合。
無料プラン
個人・趣味・スマートホーム・テスト用途は無料。
- •個人プロジェクトやプロトタイプ
- •趣味・学習用
- •個人利用のスマートホームダッシュボード（例：Home Assistant）
- •テスト・評価
APIキーごとに1日100リクエスト。
Plusプラン
個人利用の上限が引き上げられ、広告も表示されません。個人利用のみ — 商用プロジェクトにはProが必要です。
APIキーごとに1日200リクエスト、APIキー2個。
Home Assistantなどのスマートホーム連携は、個人・非商用利用であれば無料プランで引き続き利用できます。
APIキーは秘密にしてください。サーバー側で使用し、公開クライアントコードに埋め込んだりリポジトリにコミットしたりしないでください。
商用利用を考えていたり、解決できない上限にぶつかっていますか？ サポートに問い合わせる