Time & Date

Time operations for timestamps, parsing, and calculations

Overview

The time tool provides operations for getting current time, parsing timestamps, formatting dates, and calculating time differences.

time

Get current time, convert timezones, or calculate time differences.

Input Parameters

operation · string · required

The time operation to perform. Must be one of: now, parse, format, diff

timestamp · string

ISO 8601 timestamp for parse/format/diff operations

format · string

Output format string (for format operation)

timestamp2 · string

Second timestamp for diff operation

Operations

now

Get the current UTC time.

Input

No additional parameters required.

Output

iso · string

RFC3339 formatted timestamp (ISO 8601)

unix · integer

Unix timestamp in seconds since epoch

unix_millis · integer

Unix timestamp in milliseconds since epoch

Example

{
  "operation": "now"
}

Response

{
  "iso": "2024-01-15T14:30:00.123Z",
  "unix": 1705329000,
  "unix_millis": 1705329000123
}

---

parse

Parse an ISO 8601 timestamp string into multiple formats.

Input

timestamp · string · required

ISO 8601 timestamp string to parse

Output

iso · string

RFC3339 formatted timestamp

unix · integer

Unix timestamp in seconds

unix_millis · integer

Unix timestamp in milliseconds

Example

{
  "operation": "parse",
  "timestamp": "2024-01-15T14:30:00Z"
}

Response

{
  "iso": "2024-01-15T14:30:00+00:00",
  "unix": 1705329000,
  "unix_millis": 1705329000000
}

Error Conditions

• InvalidParameters: Invalid timestamp format (must be ISO 8601)

---

diff

Calculate the time difference between two timestamps.

Input

timestamp · string · required

First ISO 8601 timestamp (earlier time)

timestamp2 · string · required

Second ISO 8601 timestamp (later time)

Output

seconds · integer

Difference in seconds (timestamp2 - timestamp)

minutes · integer

Difference in minutes

hours · integer

Difference in hours

days · integer

Difference in days

Example

{
  "operation": "diff",
  "timestamp": "2024-01-15T10:00:00Z",
  "timestamp2": "2024-01-15T14:30:00Z"
}

Response

{
  "seconds": 16200,
  "minutes": 270,
  "hours": 4,
  "days": 0
}

All durations are signed. If timestamp2 is before timestamp, values will be negative.

Error Conditions

• InvalidParameters: Invalid timestamp or timestamp2 format

Examples

Get Current Time

{
  "operation": "now"
}

Parse Date String

{
  "operation": "parse",
  "timestamp": "2024-01-15T09:00:00-05:00"
}

Response:

{
  "iso": "2024-01-15T14:00:00+00:00",
  "unix": 1705327200,
  "unix_millis": 1705327200000
}

Calculate Time Elapsed

{
  "operation": "diff",
  "timestamp": "2024-01-01T00:00:00Z",
  "timestamp2": "2024-01-15T14:30:00Z"
}

Response:

{
  "seconds": 1243800,
  "minutes": 20730,
  "hours": 345,
  "days": 14
}

Negative Difference

{
  "operation": "diff",
  "timestamp": "2024-01-15T14:00:00Z",
  "timestamp2": "2024-01-15T10:00:00Z"
}

Response:

{
  "seconds": -14400,
  "minutes": -240,
  "hours": -4,
  "days": 0
}

Use Cases

Log Timestamping

Get current time for log entries:

{
  "operation": "now"
}

Duration Tracking

Calculate how long a task took:

{
  "operation": "diff",
  "timestamp": "<start_time>",
  "timestamp2": "<end_time>"
}

Deadline Checking

Calculate days until deadline:

{
  "operation": "diff",
  "timestamp": "<now>",
  "timestamp2": "<deadline>"
}

Parse External Timestamps

Convert timestamps from APIs or logs:

{
  "operation": "parse",
  "timestamp": "<external_timestamp>"
}

Technical Details

Timezone Handling

All timestamps are normalized to UTC. Input timestamps with timezone offsets (e.g., -05:00) are converted to UTC for comparison and output.

ISO 8601 Format

Accepted timestamp formats:

• 2024-01-15T14:30:00Z (UTC)
• 2024-01-15T14:30:00+00:00 (UTC with offset)
• 2024-01-15T09:30:00-05:00 (with timezone offset)
• 2024-01-15T14:30:00.123Z (with milliseconds)

Duration Precision

• seconds: Exact duration in seconds
• minutes: Truncated to whole minutes
• hours: Truncated to whole hours
• days: Truncated to whole days

Example: 25.5 hours = 25 hours, 0 days

Sanitization

No sanitization required - internal tool with no external data access.

Approval

No approval required - safe internal operation.

Error Handling

InvalidParameters

• Unknown operation
• Missing required timestamp parameter
• Invalid ISO 8601 timestamp format