Timezones
=========

Get current time in any timezone and convert times between zones with DST
awareness.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-get-timezone-info
--------------------------

Get detailed information about a timezone. Accepts IANA identifiers or common
abbreviations. Returns the current time, UTC offset, DST status, and related
metadata.

**Credit cost:** 1 credit per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``timezone``
     - string
     - yes
     - IANA timezone identifier (e.g. ``America/New_York``) or abbreviation
       (e.g. ``EST``).

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-get-timezone-info",
     "arguments": {
       "timezone": "America/New_York"
     }
   }

Response:

.. code-block:: json

   {
     "timezone": "America/New_York",
     "current_time": "2026-03-26T14:30:00-04:00",
     "utc_offset": "-04:00",
     "utc_offset_seconds": -14400,
     "is_dst": true,
     "dst_name": "EDT",
     "standard_name": "EST",
     "country_code": "US"
   }

Errors
^^^^^^

- **Unknown timezone** -- unrecognized IANA identifiers or misspelled names are
  rejected. Use the full IANA format (e.g. ``Europe/London``, not ``London``).
- **Ambiguous abbreviation** -- some abbreviations map to multiple timezones.
  For example, ``CST`` could mean Central Standard Time (US), China Standard
  Time, or Cuba Standard Time. When an abbreviation is ambiguous, the server
  returns an error listing the possible IANA identifiers so you can resubmit
  with a specific one.


apicrate-convert-time
---------------------

Convert a time from one timezone to another. Returns the converted time in both
24-hour and 12-hour formats, along with UTC offsets and the hour difference
between the zones.

**Credit cost:** 1 credit per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``time``
     - string
     - yes
     - Time to convert in ``HH:MM`` or ``HH:MM:SS`` format (24-hour clock).
   * - ``from_timezone``
     - string
     - yes
     - Source IANA timezone identifier or abbreviation.
   * - ``to_timezone``
     - string
     - yes
     - Target IANA timezone identifier or abbreviation.
   * - ``date``
     - string
     - no
     - Date in ``YYYY-MM-DD`` format. Defaults to today in the source timezone.
       Providing a date is important around DST transitions to get the correct
       offset.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-convert-time",
     "arguments": {
       "time": "14:30",
       "from_timezone": "America/New_York",
       "to_timezone": "Europe/London",
       "date": "2026-03-26"
     }
   }

Response:

.. code-block:: json

   {
     "from": {
       "timezone": "America/New_York",
       "time_24h": "14:30:00",
       "time_12h": "2:30 PM",
       "date": "2026-03-26",
       "utc_offset": "-04:00",
       "is_dst": true
     },
     "to": {
       "timezone": "Europe/London",
       "time_24h": "18:30:00",
       "time_12h": "6:30 PM",
       "date": "2026-03-26",
       "utc_offset": "+00:00",
       "is_dst": false
     },
     "hour_difference": 4
   }

Errors
^^^^^^

- **Unknown timezone** -- either ``from_timezone`` or ``to_timezone`` is not a
  recognized IANA identifier or abbreviation.
- **Invalid time format** -- the ``time`` parameter must be in ``HH:MM`` or
  ``HH:MM:SS`` 24-hour format. Values like ``2:30 PM`` or ``25:00`` are
  rejected.
- **Ambiguous abbreviation** -- abbreviations that map to multiple timezones
  (e.g. ``CST``) are rejected with a list of matching IANA identifiers.
  Resubmit with the specific identifier.
- **Invalid date** -- the ``date`` parameter, if provided, must be a valid
  ``YYYY-MM-DD`` string. Non-existent dates (e.g. ``2026-02-30``) are rejected.