ডেভেলপারদের জন্য

একটি বিনামূল্যের টাইম জোন API

যে ইঞ্জিন Hourora চালায়, সেটিই সাধারণ JSON হিসেবে: যেকোনো জায়গার সময়, ডেলাইট সেভিং টাইম বিবেচনায় রূপান্তর, প্রতিটি IANA জোন ও তার ঘড়ি পরিবর্তন। কোনো কি নেই, কোনো সাইন-আপ নেই।

এক নজরে

বেস URL: https://hourora.app/api/v1
ফরম্যাট: JSON (UTF-8), শুধু GET অনুরোধ
প্রমাণীকরণ: নেই: কোনো কি, সাইন-আপ বা কুকি লাগে না
CORS: সব origin-এর জন্য খোলা, তাই ব্রাউজার থেকেই কল করা যায়
রেট লিমিট: প্রতি ক্লায়েন্টে প্রতি মিনিটে 120 অনুরোধ
সময়ের ডেটা: IANA tzdata 2026e, Hourora কর্তৃক কম্পাইল করা
মেশিনে পড়ার উপযোগী বিবরণ: OpenAPI 3.1 ডকুমেন্ট

সরাসরি চেষ্টা করুন

একটি উদাহরণ বেছে নিন বা পাথটি সম্পাদনা করুন, তারপর পাঠান। অনুরোধটি আপনার ব্রাউজার থেকে সরাসরি API-তে যায়।

রেসপন্স

রেসপন্স এখানে দেখা যাবে।

এন্ডপয়েন্টসমূহ

প্রতিটি এন্ডপয়েন্ট GET অনুরোধে JSON দিয়ে উত্তর দেয়। সময় ISO 8601 ফরম্যাটে; অফসেট UTC-এর পূর্বদিকে মিনিটে (শীতে নিউ ইয়র্ক −300) এবং টেক্সট হিসেবেও লেখা (−05:00)।

বর্তমান সময়

GET/api/v1/time

কোনো টাইম জোন বা শহরের বর্তমান সময়: স্থানীয় সময়, UTC অফসেট, সংক্ষিপ্ত রূপ, ডেলাইট সেভিং টাইম এবং পরবর্তী ঘড়ি পরিবর্তন। প্যারামিটার ছাড়া: UTC।

প্যারামিটার

নাম	অর্থ
`tz`ঐচ্ছিক	IANA টাইম জোনের নাম, যেমন Europe/London। Asia/Calcutta-র মতো বিকল্প নামও গ্রহণ করা হয় এবং বর্তমান নাম দিয়ে উত্তর দেওয়া হয়।
`city`ঐচ্ছিক	tz-এর বদলে শহরের স্লাগ, যেমন london (স্লাগ খুঁজতে /cities ব্যবহার করুন)।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/time?tz=Europe/London"

উদাহরণ রেসপন্স

{
  "zone": "Europe/London",
  "local": "2026-10-15T12:42:01",
  "iso": "2026-10-15T12:42:01+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-15T11:42:01.231Z",
  "unixMs": 1792064521231,
  "date": "2026-10-15",
  "time": "12:42:01",
  "weekday": "Thursday",
  "dayOfYear": 288,
  "isoWeek": 42,
  "dstObserved": true,
  "nextTransition": {
    "at": "2026-10-25T01:00:00.000Z",
    "unixMs": 1792890000000,
    "type": "dst-end",
    "fromOffsetMinutes": 60,
    "toOffsetMinutes": 0,
    "shiftMinutes": -60,
    "fromAbbreviation": "BST",
    "toAbbreviation": "GMT",
    "localBefore": "2026-10-25T02:00:00",
    "localAfter": "2026-10-25T01:00:00"
  },
  "tzdata": "2026e"
}

এই সার্ভারের আসল রেসপন্স।

সময় রূপান্তর

GET/api/v1/convert

এক জোনের দেয়ালঘড়ির সময় অন্য জোনে দেখানো। সময়টি ডেলাইট সেভিং টাইমের গ্যাপে (অস্তিত্ব নেই) বা ওভারল্যাপে (দুবার আসে) পড়লে তা জানায়।

প্যারামিটার

নাম	অর্থ
`from`আবশ্যক	যে জোনে (বা শহরের স্লাগে) সময়টি পড়া হয়।
`to`আবশ্যক	যে জোনে (বা শহরের স্লাগে) সময়টি দেখাতে হবে।
`time`ঐচ্ছিক	from জোনের দেয়ালঘড়ির সময়, YYYY-MM-DDTHH:mm (সেকেন্ড ঐচ্ছিক, অফসেট ছাড়া), 1970–2060। ডিফল্ট: এখন।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/convert?from=America/New_York&to=Asia/Kolkata&time=2026-10-16T15:00"

উদাহরণ রেসপন্স

{
  "status": "ok",
  "requested": "2026-10-16T15:00:00",
  "utc": "2026-10-16T19:00:00.000Z",
  "unixMs": 1792177200000,
  "from": {
    "zone": "America/New_York",
    "local": "2026-10-16T15:00:00",
    "iso": "2026-10-16T15:00:00-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true
  },
  "to": {
    "zone": "Asia/Kolkata",
    "local": "2026-10-17T00:30:00",
    "iso": "2026-10-17T00:30:00+05:30",
    "offsetMinutes": 330,
    "offset": "+05:30",
    "utcOffset": "UTC+5:30",
    "abbreviation": "IST",
    "dst": false,
    "dayOffset": 1
  },
  "differenceMinutes": 570,
  "tzdata": "2026e"
}

এই সার্ভারের আসল রেসপন্স।

টাইম জোনের তালিকা

GET/api/v1/zones

প্রতিটি IANA টাইম জোন, তার বর্তমান UTC অফসেট, সংক্ষিপ্ত রূপ, ডেলাইট সেভিং টাইমের অবস্থা, দেশ ও প্রধান শহরসহ।

প্যারামিটার

নাম	অর্থ
`country`ঐচ্ছিক	ISO 3166 দেশের কোড, যেমন GB, শুধু সেই দেশের ফল রাখতে।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/zones?country=GB"

উদাহরণ রেসপন্স

{
  "asOf": "2026-10-15T11:42:01.231Z",
  "count": 1,
  "tzdata": "2026e",
  "zones": [
    {
      "id": "Europe/London",
      "offsetMinutes": 60,
      "offset": "+01:00",
      "utcOffset": "UTC+1",
      "abbreviation": "BST",
      "dst": true,
      "countries": [
        "GB",
        "GG",
        "IM"
      ],
      "mainCity": "London"
    }
  ]
}

এই সার্ভারের আসল রেসপন্স; তালিকাগুলো সংক্ষিপ্ত করে প্রথম 3টি আইটেম রাখা হয়েছে।

একটি টাইম জোন

GET/api/v1/zones/{id}

একটি IANA জোন: তার বিকল্প নাম, দেশ ও শহর, বর্তমান অফসেট, পরবর্তী ঘড়ি পরিবর্তন এবং নির্দিষ্ট বছরের প্রতিটি পরিবর্তন।

প্যারামিটার

নাম	অর্থ
`id`পাথের মধ্যে	IANA জোনের নাম; স্ল্যাশটি রাখুন অথবা %2F হিসেবে এনকোড করুন।
`year`ঐচ্ছিক	যে বছরের ঘড়ি পরিবর্তনগুলোর তালিকা চাই, 1970–2060। ডিফল্ট: এই বছর।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/zones/America%2FNew_York?year=2027"

উদাহরণ রেসপন্স

{
  "id": "America/New_York",
  "aliases": [
    "US/Eastern"
  ],
  "countries": [
    {
      "code": "US",
      "name": "United States"
    }
  ],
  "cities": [
    {
      "slug": "new-york",
      "name": "New York"
    },
    {
      "slug": "philadelphia",
      "name": "Philadelphia"
    },
    {
      "slug": "miami",
      "name": "Miami"
    }
  ],
  "now": {
    "zone": "America/New_York",
    "local": "2026-10-15T07:42:01",
    "iso": "2026-10-15T07:42:01-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-15T11:42:01.231Z",
    "standardOffsetMinutes": -300,
    "dstObserved": true
  },
  "nextTransition": {
    "at": "2026-11-01T06:00:00.000Z",
    "unixMs": 1793512800000,
    "type": "dst-end",
    "fromOffsetMinutes": -240,
    "toOffsetMinutes": -300,
    "shiftMinutes": -60,
    "fromAbbreviation": "EDT",
    "toAbbreviation": "EST",
    "localBefore": "2026-11-01T02:00:00",
    "localAfter": "2026-11-01T01:00:00"
  },
  "year": 2027,
  "dstObservedInYear": true,
  "transitions": [
    {
      "at": "2027-03-14T07:00:00.000Z",
      "unixMs": 1805007600000,
      "type": "dst-start",
      "fromOffsetMinutes": -300,
      "toOffsetMinutes": -240,
      "shiftMinutes": 60,
      "fromAbbreviation": "EST",
      "toAbbreviation": "EDT",
      "localBefore": "2027-03-14T02:00:00",
      "localAfter": "2027-03-14T03:00:00"
    },
    {
      "at": "2027-11-07T06:00:00.000Z",
      "unixMs": 1825567200000,
      "type": "dst-end",
      "fromOffsetMinutes": -240,
      "toOffsetMinutes": -300,
      "shiftMinutes": -60,
      "fromAbbreviation": "EDT",
      "toAbbreviation": "EST",
      "localBefore": "2027-11-07T02:00:00",
      "localAfter": "2027-11-07T01:00:00"
    }
  ],
  "tzdata": "2026e"
}

শহর অনুসন্ধান

GET/api/v1/cities

যেসব শহরের নাম মেলে, সেরা মিল ও সবচেয়ে বড় শহর আগে, প্রতিটির দেশ, স্থানাঙ্ক ও টাইম জোনসহ।

প্যারামিটার

নাম	অর্থ
`q`আবশ্যক	শহরের নামের অংশ, অ্যাকসেন্ট ঐচ্ছিক (সর্বোচ্চ 80 অক্ষর)।
`limit`ঐচ্ছিক	কতগুলো ফল, 1–50। ডিফল্ট 10।
`country`ঐচ্ছিক	ISO 3166 দেশের কোড, যেমন GB, শুধু সেই দেশের ফল রাখতে।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/cities?q=lond&limit=3"

উদাহরণ রেসপন্স

{
  "query": "lond",
  "count": 3,
  "total": 7,
  "cities": [
    {
      "slug": "london",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "GB",
        "name": "United Kingdom"
      },
      "region": "Westminster",
      "zone": "Europe/London",
      "lat": 51.5,
      "lng": -0.1167,
      "population": 7994105,
      "capital": true,
      "url": "https://hourora.app/en/london"
    },
    {
      "slug": "londrina",
      "name": "Londrina",
      "asciiName": "Londrina",
      "country": {
        "code": "BR",
        "name": "Brazil"
      },
      "region": "Paraná",
      "zone": "America/Sao_Paulo",
      "lat": -23.3,
      "lng": -51.18,
      "population": 496035,
      "capital": false,
      "url": "https://hourora.app/en/londrina"
    },
    {
      "slug": "london-ontario",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "CA",
        "name": "Canada"
      },
      "region": "Ontario",
      "zone": "America/Toronto",
      "lat": 42.97,
      "lng": -81.25,
      "population": 340900,
      "capital": false,
      "url": "https://hourora.app/en/london-ontario"
    }
  ]
}

এই সার্ভারের আসল রেসপন্স।

একটি শহর

GET/api/v1/cities/{slug}

স্লাগ দিয়ে একটি শহর, তার টাইম জোনের বর্তমান অফসেট ও পরবর্তী ঘড়ি পরিবর্তনসহ।

প্যারামিটার

নাম	অর্থ
`slug`পাথের মধ্যে	শহরের স্লাগ, যেমন tokyo।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/cities/tokyo"

উদাহরণ রেসপন্স

{
  "slug": "tokyo",
  "name": "Tokyo",
  "asciiName": "Tokyo",
  "country": {
    "code": "JP",
    "name": "Japan"
  },
  "region": "Tokyo",
  "zone": "Asia/Tokyo",
  "lat": 35.685,
  "lng": 139.7514,
  "population": 22006300,
  "capital": true,
  "url": "https://hourora.app/en/tokyo",
  "now": {
    "zone": "Asia/Tokyo",
    "local": "2026-10-15T20:42:01",
    "iso": "2026-10-15T20:42:01+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-15T11:42:01.231Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

এই সার্ভারের আসল রেসপন্স।

স্থানাঙ্ক থেকে টাইম জোন

GET/api/v1/lookup

একটি অক্ষাংশ ও দ্রাঘিমাংশের নিকটতম তালিকাভুক্ত শহর এবং তার টাইম জোন। এটি একটি আনুমানিক হিসাব: জোনের সীমানা মডেল করা হয়নি।

প্যারামিটার

নাম	অর্থ
`lat`আবশ্যক	দশমিক ডিগ্রিতে অক্ষাংশ, −90 থেকে 90।
`lng`আবশ্যক	দশমিক ডিগ্রিতে দ্রাঘিমাংশ, −180 থেকে 180।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/lookup?lat=48.85&lng=2.35"

উদাহরণ রেসপন্স

{
  "query": {
    "lat": 48.85,
    "lng": 2.35
  },
  "approximate": true,
  "method": "nearest listed city (great-circle distance); time-zone borders are not modelled",
  "distanceKm": 2.2,
  "city": {
    "slug": "paris",
    "name": "Paris",
    "asciiName": "Paris",
    "country": {
      "code": "FR",
      "name": "France"
    },
    "region": "Île-de-France",
    "zone": "Europe/Paris",
    "lat": 48.8667,
    "lng": 2.3333,
    "population": 4957589,
    "capital": true,
    "url": "https://hourora.app/en/paris"
  },
  "zone": "Europe/Paris",
  "now": {
    "zone": "Europe/Paris",
    "local": "2026-10-15T13:42:01",
    "iso": "2026-10-15T13:42:01+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-15T11:42:01.231Z"
  },
  "tzdata": "2026e"
}

এই সার্ভারের আসল রেসপন্স।

ডেটার সংস্করণ

GET/api/v1/tzdata

উত্তরগুলো IANA টাইম জোন ডেটাবেসের কোন রিলিজ থেকে আসে, এবং Hourora সর্বশেষ কবে তার ডেটা হালনাগাদ করেছে।

প্যারামিটার

কোনো প্যারামিটার নেই।

উদাহরণ অনুরোধ

curl "https://hourora.app/api/v1/tzdata"

উদাহরণ রেসপন্স

{
  "version": "2026e",
  "source": "IANA Time Zone Database",
  "sourceUrl": "https://www.iana.org/time-zones",
  "dataDate": "2026-10-13",
  "range": {
    "from": "1970-01-01",
    "to": "2060-12-31"
  },
  "zones": 344,
  "links": 253,
  "cities": 7269,
  "note": "Outside the compiled range, offsets fall back to the server runtime's own tzdata."
}

এই সার্ভারের আসল রেসপন্স।

ত্রুটি

ত্রুটিও JSON হিসেবে আসে: HTTP স্ট্যাটাস, আপনার প্রোগ্রামের জন্য একটি স্থির কোড এবং মানুষের জন্য একটি বার্তা।

{
  "error": {
    "code": "unknown_zone",
    "message": "\"Mars/Base\" is not an IANA time zone name. List them with /api/v1/zones."
  }
}

স্ট্যাটাস	কোড	কখন
400	`missing_parameter, invalid_parameter`	কোনো প্যারামিটার নেই বা প্রত্যাশিত ফরম্যাটে নেই।
404	`unknown_zone, unknown_city, unknown_country, not_found`	এমন কোনো টাইম জোন, শহর, দেশ বা এন্ডপয়েন্ট নেই।
429	`rate_limited`	আপনার ক্লায়েন্ট থেকে অনেক বেশি অনুরোধ এসেছে; Retry-After-এ দেওয়া সেকেন্ড পর্যন্ত অপেক্ষা করুন।
500	`internal_error`	আমাদের দিকে কিছু একটা ব্যর্থ হয়েছে। অনুগ্রহ করে পরে আবার চেষ্টা করুন।

কীভাবে কাজ করে

সীমা ও ক্যাশিং

প্রতিটি ক্লায়েন্ট প্রতি মিনিটে সর্বোচ্চ 120 অনুরোধ পাঠাতে পারে, স্বল্প সময়ের আকস্মিক বৃদ্ধি অনুমোদিত। এর বেশি হলে API একটি Retry-After হেডারসহ 429 দিয়ে উত্তর দেয়। এই সীমা একটি বিনামূল্যের সেবাকে সুরক্ষিত রাখে; আরও বেশি দরকার হলে ক্যাশ করুন।

প্রতিটি রেসপন্স জানায় সেটি কতক্ষণ ক্যাশ করা যাবে (Cache-Control)। বর্তমান সময় কখনো ক্যাশ হয় না; জোনের তালিকা, শহরের বিবরণ ও লুকআপ পাঁচ মিনিটের জন্য; শহর অনুসন্ধান ও নির্দিষ্ট সময়ের রূপান্তর এক দিনের জন্য।

ঘড়ি তৈরি করছেন? অফসেটটি একবার আনুন, স্থানীয়ভাবে টিক চালান, এবং রেসপন্সে জানানো পরবর্তী ঘড়ি পরিবর্তনের পরে আবার আনুন। প্রতি সেকেন্ডে পোল করার দরকার নেই।

উত্তরগুলো কোথা থেকে আসে

অফসেট, সংক্ষিপ্ত রূপ ও ঘড়ি পরিবর্তন আসে IANA টাইম জোন ডেটাবেসের Hourora-র নিজস্ব কম্পাইল করা কপি থেকে, রিলিজ 2026e, 1970–2060 সালের জন্য। এই সীমার বাইরে সার্ভারের অন্তর্নির্মিত ডেটা ব্যবহৃত হয়, যা পুরোনো হতে পারে।

রূপান্তরে ডেলাইট সেভিং টাইমের প্রান্তগুলো স্পষ্টভাবে মীমাংসা করা হয়: বসন্তে ঘড়ি এগিয়ে গেলে বাদ পড়া সময়কে গ্যাপ হিসেবে জানানো হয়, আর শরতে ঘড়ি পিছিয়ে গেলে দুবার আসা সময়কে ওভারল্যাপ হিসেবে, দুটি মুহূর্তসহ।

স্থানাঙ্ক লুকআপ প্রায় 7,200 তালিকাভুক্ত শহরের মধ্যে নিকটতমটি এবং সেই শহরের জোন ফেরত দেয়। সীমান্তের কাছে, সমুদ্রে বা কম জনবসতির এলাকায় এটি সেই বিন্দুতে আসলে প্রযোজ্য জোন থেকে আলাদা হতে পারে।

ব্যবহারের শর্তাবলি

ব্যক্তিগত ও বাণিজ্যিক ব্যবহারের জন্য বিনামূল্যে। কোনো কি বা অ্যাকাউন্ট লাগে না।
কৃতিত্ব উল্লেখ করলে ভালো লাগবে, তবে বাধ্যতামূলক নয়: ডেটা যেখানে দেখানো হয় তার কাছে hourora.app-এর একটি লিংক।
যেমন আছে তেমনভাবে দেওয়া হয়, কোনো সার্ভিস-লেভেল চুক্তি বা প্রাপ্যতার নিশ্চয়তা ছাড়া। যেখানে ভুল বা অনুপস্থিত সময় ক্ষতির কারণ হতে পারে, সেখানে এটি ব্যবহার করবেন না।
উত্তরগুলো IANA tzdata 2026e অনুসরণ করে। সরকার ঘড়ির সময় বদলালে পরবর্তী IANA রিলিজের সঙ্গে ডেটা হালনাগাদ করা হয়।
সংস্করণ 1 সামঞ্জস্যপূর্ণ থাকবে: নতুন ফিল্ড যোগ হতে পারে, কিছুই সরানো বা নাম বদলানো হবে না। অসামঞ্জস্যপূর্ণ পরিবর্তন আসবে /api/v2 হিসেবে।
অনুগ্রহ করে রেট লিমিটের মধ্যে থাকুন এবং রেসপন্স ক্যাশ করুন। অপব্যবহারমূলক ট্রাফিক ব্লক করা হতে পারে।

প্রশ্নোত্তর

যা জেনে রাখা ভালো

Hourora API কি সত্যিই বিনামূল্যের?

হ্যাঁ। কোনো কি নেই, অ্যাকাউন্ট নেই এবং কোনো পেইড স্তর নেই। প্রতি ক্লায়েন্টের রেট লিমিট সবার জন্য সেবাটি ন্যায্য রাখে।

আমি কি ব্রাউজারে JavaScript থেকে এটি কল করতে পারি?

হ্যাঁ। প্রতিটি এন্ডপয়েন্ট যেকোনো ওয়েবসাইট থেকে ক্রস-অরিজিন অনুরোধ (CORS) অনুমোদন করে, এবং কোনো ক্রেডেনশিয়াল লাগে না।

এটি ডেলাইট সেভিং টাইম কীভাবে সামলায়?

প্রতিটি উত্তর IANA নিয়ম থেকে নির্দিষ্ট মুহূর্তের জন্য হিসাব করা হয়। convert এন্ডপয়েন্ট আরও জানায় কখন অনুরোধ করা দেয়ালঘড়ির সময়ের অস্তিত্ব নেই (ঘড়ি এগিয়ে গেলে) বা তা দুবার আসে (ঘড়ি পিছিয়ে গেলে)।

স্থানাঙ্ক লুকআপ কতটা নির্ভুল?

এটি নিকটতম তালিকাভুক্ত শহরের টাইম জোন ফেরত দেয়, যা মানুষ যেখানে বাস করে তার প্রায় সব জায়গায় সঠিক। এটি জোনের সীমানা মডেল করে না, তাই সীমান্তের কাছে বা সমুদ্রে ভুল হতে পারে।