API ডকুমেন্টেশন
আপনার অ্যাপ্লিকেশনে সূর্যাস্তের মানের পূর্বাভাস যুক্ত করুন
আপনার ব্যবহার ট্র্যাক করতে একটি API কী নিনদ্রুত শুরু
কয়েক সেকেন্ডে সূর্যাস্তের পূর্বাভাস পান
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-এর জন্য আবশ্যক) |
সীমা
ফ্রি টিয়ার — প্রতিটি কী-এর জন্য দিনে 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 পরীক্ষা করুন। প্রমাণীকৃত কল করতে আপনার 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"ওপরের প্লেগ্রাউন্ডের প্যারামিটার পরিবর্তন করলে স্নিপেটগুলো সঙ্গে সঙ্গে আপডেট হয়।
ত্রুটি রেসপন্স
সাধারণ ত্রুটি রেসপন্স ও তাদের অর্থ
ভুল অনুরোধ
প্যারামিটার অনুপস্থিত বা অবৈধ। হয় city, নয়তো 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"
}সেরা অনুশীলন
রেসপন্স ক্যাশ করুন
পূর্বাভাস সার্ভারে প্রতিটি (lat, lon, lang, date)-এর জন্য 20 মিনিট ক্যাশ করা থাকে। এর চেয়ে ঘন ঘন পোলিং এড়িয়ে চলুন।
তারিখের পরিসর
গতকাল থেকে 5 দিন পর পর্যন্ত পূর্বাভাস পাওয়া যায়। আরও দূরের তারিখে ফলাফল কম নির্ভুল হয়।
স্থানাঙ্ক ব্যবহার করুন
lat/lon ব্যবহার বেশি নির্ভুল, বিভিন্ন অঞ্চলে একই নামের শহর নিয়ে বিভ্রান্তি এড়ায় এবং জিওকোডিং এড়িয়ে যায়।
ত্রুটি সঠিকভাবে সামলান
HTTP স্ট্যাটাস কোড ও রেসপন্সের code ফিল্ড যাচাই করুন। 401/403 ব্যবহারকারীকে দেখান এবং 429-এ Retry-After অনুযায়ী অপেক্ষা করুন।
রেট লিমিট মেনে চলুন
প্রতিটি রেসপন্সে X-RateLimit-Remaining পড়ুন। 429 পেলে আবার চেষ্টার আগে Retry-After সময়সীমা (UTC মধ্যরাতে রিসেট) পর্যন্ত অপেক্ষা করুন।
কী সার্ভারে রাখুন
কখনো কোনো পাবলিক ক্লায়েন্ট বান্ডেল, মোবাইল অ্যাপ বা রিপোজিটরিতে API কী রাখবেন না। আপনার ব্যাকএন্ডের মাধ্যমে প্রক্সি করুন এবং কী env ভেরিয়েবল বা সিক্রেট ম্যানেজারে সংরক্ষণ করুন।
ব্যবহার ও লাইসেন্সিং
কখন ফ্রি টিয়ার যথেষ্ট — আর কখন পেইড প্ল্যান দরকার।
ফ্রি টিয়ার
ব্যক্তিগত, শখের, স্মার্ট হোম ও পরীক্ষামূলক ব্যবহারের জন্য বিনামূল্যে।
- •ব্যক্তিগত প্রকল্প ও প্রোটোটাইপ
- •শখ ও শেখা
- •ব্যক্তিগত ব্যবহারের জন্য স্মার্ট হোম ড্যাশবোর্ড (যেমন: Home Assistant)
- •পরীক্ষা ও মূল্যায়ন
প্রতিটি API কী-এর জন্য দিনে 100টি অনুরোধ।
Plus টিয়ার
সমর্থকদের জন্য বেশি ব্যক্তিগত সীমা, সঙ্গে বিজ্ঞাপনমুক্ত সাইট। শুধুমাত্র ব্যক্তিগত ব্যবহারের জন্য — বাণিজ্যিক প্রকল্পের জন্য Pro প্রয়োজন।
প্রতিটি API কী-এর জন্য দিনে 200টি অনুরোধ, 2টি API কী।
বাণিজ্যিক ব্যবহার
বাণিজ্যিক ব্যবহারের জন্য পেইড প্ল্যান প্রয়োজন — Pro বা Business।
পেইড টিয়ারে দৈনিক অনুরোধের সীমা বেশি এবং আরও বেশি API কী ব্যবহার করা যায়।
মূল্য দেখুনব্যক্তিগত, অবাণিজ্যিক ব্যবহারের জন্য Home Assistant ও অন্যান্য স্মার্ট হোম ইন্টিগ্রেশন ফ্রি টিয়ারে অনুমোদিত থাকবে।
আপনার API কী গোপন রাখুন। এটি সার্ভারে ব্যবহার করুন এবং কখনো পাবলিক ক্লায়েন্ট-সাইড কোডে রাখবেন না বা রিপোজিটরিতে কমিট করবেন না।
বাণিজ্যিক কিছু তৈরি করছেন বা এমন কোনো সীমায় আটকে গেছেন যা সমাধান করতে পারছেন না? সাপোর্টে যোগাযোগ করুন