Convert a time

Parses input and returns the instant in UTC, as Unix seconds and milliseconds, and in each zone of zones. The response says exactly how the input was read: the detected format, the inferred timestamp unit (with what the other units would have meant), and, for a wall-clock time without an offset, the zone used and whether that local time was unique, skipped by a DST gap, or repeated in a DST overlap.

Browser version (runs locally): Time & Time Zones.

Parameters

Also accepted on every endpoint: format (json | text). Parameters may come from the query string, a JSON object body, an urlencoded or multipart form, or (for input) a text/plain body.

Response 200 application/json

Text output (format=text, text/plain): The ISO 8601 time in each requested zone, one per line.

Errors

Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.

Behaviour

• Idempotent: the same arguments always return the same result.
• Requires a client ID and secret (authentication). Each call is recorded as one metadata row against your client ID; inputs and outputs are never stored or logged. Responses carry cache-control: no-store.
• CORS: any origin may call this endpoint from a browser, using your credentials.

Examples

Responses below were produced by running each request through this code at build time. Long strings are shortened.

curl 'https://util.caruana.me/api/time/convert?input=1791900000&zones=UTC%2CEurope%2FParis'

{
  "input": {
    "input": "1791900000",
    "format": "unix",
    "unit": "seconds",
    "unit_auto_detected": true,
    "has_offset": true,
    "local_zone": null,
    "local_time": null,
    "notes": [
      "Unit auto-detected as seconds because the magnitude is below 10^11. For comparison, as milliseconds it would be 1970-01-… (90 more characters)"
    ]
  },
  "instant": {
    "utc": "2026-10-13T14:00:00Z",
    "unix_seconds": 1791900000,
    "unix_milliseconds": 1791900000000
  },
  "zones": [
    {
      "zone": "UTC",
      "iso": "2026-10-13T14:00:00Z",
      "local": "2026-10-13T14:00:00",
      "date": "2026-10-13",
      "time": "14:00:00",
      "offset": "+00:00",
      "offset_minutes": 0,
      "abbreviation": "UTC",
      "offset_name": "UTC",
      "dst": false,
      "weekday": "Tuesday",
      "weekday_number": 2,
      "iso_week": "2026-W42",
      "iso_week_year": 2026,
      "iso_week_number": 42,
      "day_of_year": 286,
      "formatted": {}
    },
    {
      "zone": "Europe/Paris",
      "iso": "2026-10-13T16:00:00+02:00",
      "local": "2026-10-13T16:00:00",
      "date": "2026-10-13",
      "time": "16:00:00",
      "offset": "+02:00",
      "offset_minutes": 120,
      "abbreviation": "GMT+2",
      "offset_name": "Central European Summer Time",
      "dst": true,
      "weekday": "Tuesday",
      "weekday_number": 2,
      "iso_week": "2026-W42",
      "iso_week_year": 2026,
      "iso_week_number": 42,
      "day_of_year": 286,
      "formatted": {}
    }
  ],
  "warnings": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "time_convert",
    "arguments": {
      "input": "1791900000",
      "zones": [
        "UTC",
        "Europe/Paris"
      ]
    }
  }
}

curl 'https://util.caruana.me/api/time/convert?input=2026-03-08T02%3A30&from_zone=America%2FNew_York&zones=UTC'

{
  "input": {
    "input": "2026-03-08T02:30",
    "format": "iso8601",
    "unit": null,
    "unit_auto_detected": false,
    "has_offset": false,
    "local_zone": "America/New_York",
    "local_time": "gap",
    "notes": [
      "No offset in the input: read as wall-clock time in America/New_York (set by from_zone).",
      "2026-03-08T02:30:00 does not exist in America/New_York: it falls in a 60-minute DST gap. Resolved to 2026-03-08T03:30:00… (79 more characters)"
    ]
  },
  "instant": {
    "utc": "2026-03-08T07:30:00Z",
    "unix_seconds": 1772955000,
    "unix_milliseconds": 1772955000000
  },
  "zones": [
    {
      "zone": "UTC",
      "iso": "2026-03-08T07:30:00Z",
      "local": "2026-03-08T07:30:00",
      "date": "2026-03-08",
      "time": "07:30:00",
      "offset": "+00:00",
      "offset_minutes": 0,
      "abbreviation": "UTC",
      "offset_name": "UTC",
      "dst": false,
      "weekday": "Sunday",
      "weekday_number": 7,
      "iso_week": "2026-W10",
      "iso_week_year": 2026,
      "iso_week_number": 10,
      "day_of_year": 67,
      "formatted": {}
    }
  ],
  "warnings": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "time_convert",
    "arguments": {
      "input": "2026-03-08T02:30",
      "from_zone": "America/New_York",
      "zones": [
        "UTC"
      ]
    }
  }
}

curl 'https://util.caruana.me/api/time/convert?input=Tue%2C%2013%20Oct%202026%2014%3A30%3A00%20%2B0200&zones=Asia%2FTokyo&formats=http%2Ciso_week_date%2Chuman'

{
  "input": {
    "input": "Tue, 13 Oct 2026 14:30:00 +0200",
    "unit": null,
    "unit_auto_detected": false,
    "has_offset": true,
    "local_zone": null,
    "local_time": null,
    "notes": [],
    "format": "rfc2822"
  },
  "instant": {
    "utc": "2026-10-13T12:30:00Z",
    "unix_seconds": 1791894600,
    "unix_milliseconds": 1791894600000
  },
  "zones": [
    {
      "zone": "Asia/Tokyo",
      "iso": "2026-10-13T21:30:00+09:00",
      "local": "2026-10-13T21:30:00",
      "date": "2026-10-13",
      "time": "21:30:00",
      "offset": "+09:00",
      "offset_minutes": 540,
      "abbreviation": "GMT+9",
      "offset_name": "Japan Standard Time",
      "dst": false,
      "weekday": "Tuesday",
      "weekday_number": 2,
      "iso_week": "2026-W42",
      "iso_week_year": 2026,
      "iso_week_number": 42,
      "day_of_year": 286,
      "formatted": {
        "http": "Tue, 13 Oct 2026 12:30:00 GMT",
        "iso_week_date": "2026-W42-2",
        "human": "Tuesday, October 13, 2026 at 9:30:00 PM GMT+9"
      }
    }
  ],
  "warnings": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "time_convert",
    "arguments": {
      "input": "Tue, 13 Oct 2026 14:30:00 +0200",
      "zones": [
        "Asia/Tokyo"
      ],
      "formats": [
        "http",
        "iso_week_date",
        "human"
      ]
    }
  }
}