Timezones
=========

Timezone information, conversion, and difference calculation.

GET /api/v1/timezones
---------------------

List or search timezones.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``region``
     - query
     - no
     - Filter by region (e.g. ``Europe``, ``America``)
   * - ``q``
     - query
     - no
     - Free-text search across timezone names
   * - ``abbr``
     - query
     - no
     - Filter by abbreviation (e.g. ``CET``, ``PST``)
   * - ``limit``
     - query
     - no
     - Maximum results to return (default 50)
   * - ``offset``
     - query
     - no
     - Number of results to skip

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/timezones?region=Europe&limit=2"

.. code-block:: json

   {
     "count": 37,
     "results": [
       {
         "name": "Europe/Berlin",
         "abbreviation": "CET",
         "utc_offset": "+01:00",
         "dst_offset": "+02:00",
         "is_dst": false
       },
       {
         "name": "Europe/London",
         "abbreviation": "GMT",
         "utc_offset": "+00:00",
         "dst_offset": "+01:00",
         "is_dst": false
       }
     ]
   }

GET /api/v1/timezones/{tz_name}
-------------------------------

Get details for a specific timezone.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``tz_name``
     - path
     - yes
     - IANA timezone name (e.g. ``America/New_York``). Use ``%2F`` for the slash in URLs.

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     https://api.apicrate.io/api/v1/timezones/America%2FNew_York

.. code-block:: json

   {
     "name": "America/New_York",
     "abbreviation": "EST",
     "utc_offset": "-05:00",
     "dst_offset": "-04:00",
     "is_dst": false,
     "current_time": "2026-03-26T10:30:00-05:00"
   }

GET /api/v1/timezones-diff
--------------------------

Calculate the hour difference between two timezones.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``from``
     - query
     - yes
     - Source IANA timezone name
   * - ``to``
     - query
     - yes
     - Target IANA timezone name

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/timezones-diff?from=America/New_York&to=Europe/Berlin"

.. code-block:: json

   {
     "from": "America/New_York",
     "to": "Europe/Berlin",
     "difference_hours": 6.0
   }

GET /api/v1/timezones-convert
-----------------------------

Convert a time from one timezone to another.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``from``
     - query
     - yes
     - Source IANA timezone name
   * - ``to``
     - query
     - yes
     - Target IANA timezone name
   * - ``time``
     - query
     - yes
     - Time to convert in ``HH:MM`` or ``HH:MM:SS`` format
   * - ``date``
     - query
     - no
     - Date in ``YYYY-MM-DD`` format (defaults to today)

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/timezones-convert?from=America/New_York&to=Asia/Tokyo&time=09:00&date=2026-03-26"

.. code-block:: json

   {
     "from": {
       "timezone": "America/New_York",
       "datetime": "2026-03-26T09:00:00-04:00"
     },
     "to": {
       "timezone": "Asia/Tokyo",
       "datetime": "2026-03-26T22:00:00+09:00"
     }
   }