Resolve Local Date-Time
time.resolve_local_datetime
Overview
You send an ISO local date-time and an IANA zone. A time that occurs once is NORMAL. A fall-back overlap is OVERLAP_EARLIER or OVERLAP_LATER, or refused when disambiguation is REJECT (the default). A spring-forward gap is refused unless disambiguation is NEXT_VALID, which shifts forward by the gap and returns GAP_SHIFTED. This is not natural-language parsing and not recurrence expansion.
A local reading is not always one instant. Naming REJECT, EARLIER, LATER or NEXT_VALID makes the gap and overlap choice a contract instead of a silent guess.
Reliability
Default disambiguation is REJECT, so an overlap or gap is a typed failure until you choose a branch. NEXT_VALID on a gap uses the same forward shift as java.time atZone. TIMEZONE_UNKNOWN — trigger: zoneId is not a resolvable IANA region id; retryable: no; next: send Europe/Brussels or UTC. DATETIME_FORMAT_INVALID — trigger: localDateTime is not an ISO local date-time; retryable: no; next: send 2026-10-25T02:30:00 without an offset. DATETIME_AMBIGUOUS — trigger: the reading happens twice and disambiguation is REJECT; retryable: no; next: resend EARLIER or LATER. DATETIME_NONEXISTENT — trigger: the reading never happens and disambiguation is not NEXT_VALID; retryable: no; next: resend NEXT_VALID or correct the wall time.
Context footprint
One local reading and one zone in. A successful call costs 1 execution credit.
When to use it
When you hold a zone-less local date-time and must say how DST gaps and overlaps resolve.
When you already have an instant, or you need to convert that instant into another zone.
Scope
Non-goals
- Does not parse natural-language dates (use time.parse_datetime)
- Does not convert between two zones (use time.convert_timezone)
Properties
Capabilities
Cost & billing
Flat rate per invocation
File handling
How we handle your data
What this means
This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.
Squillify guarantees
- Runs inside Squillify
- This skill runs inside Squillify.
- Payloads are not sent to an external service by this skill.
- Squillify does not permanently store submitted payloads.
- Telemetry records metadata only, not submitted content.
- Submitted payloads are not used for training.
- Submitted payloads are not reviewed by humans.
- This skill does not target sensitive data.
- The response does not contain submitted content.
Your responsibility
Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.
Input schema
| Field | Type | Required | Description |
|---|---|---|---|
| localDateTime | string | Yes | ISO local date-time without offset. |
| zoneId | string | Yes | IANA region zone or UTC. |
| disambiguation | string | No | Gap and overlap policy; omit it for REJECT. |
Output schema
| Field | Type | Required | Description |
|---|---|---|---|
| instant | string | Yes | Resolved UTC instant. |
| offset | string | Yes | UTC offset as ±HH:MM[:SS]. |
| offsetSeconds | integer | Yes | The same UTC offset expressed as a signed count of seconds, including sub-minute offsets. |
| zoneId | string | Yes | Canonical IANA zone. |
| resolution | string | Yes | How the local reading was resolved. |
| candidateOffsets | array | Yes | From 0 through 4 offset strings: valid overlap offsets, or the transition before/after pair on a gap. |
| shiftSeconds | integer | Yes | Gap shift in seconds. |
| _meta | object | Yes | Closed applied tzdb receipt naming the IANA tzdbVersion used. |
API contract
POST /v1/executecurl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"time.resolve_local_datetime","input":{"localDateTime":"2026-01-15T12:00:00","zoneId":"Europe/Brussels"}}'import { Squillify } from "@squillify/sdk";
const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });
const { output } = await sq.execute("time.resolve_local_datetime", {"localDateTime":"2026-01-15T12:00:00","zoneId":"Europe/Brussels"});Errors
| Code | HTTP | Retryable | Description |
|---|---|---|---|
| VALIDATION_ERROR | 400 | No | The request payload failed schema validation. |
| UNAUTHORIZED | 401 | No | Missing or invalid API key. |
| SKILL_NOT_ACCESSIBLE | 403 | No | The API key is not granted access to this skill. |
| SKILL_NOT_AVAILABLE_FOR_PLAN | 403 | No | This skill is not included in your current plan. |
| PLAN_ELIGIBILITY_UNAVAILABLE | 503 | Yes | Plan eligibility could not be decided. Retry after backoff. |
| SKILL_NOT_FOUND | 404 | No | The requested skill or version does not exist. |
| TENANT_RATE_LIMITED | 429 | Yes | Request rate limit exceeded. Retry after backoff. |
| QUOTA_EXCEEDED | 429 | Yes | Plan quota exhausted. Retryable once the quota period resets. |
| EXECUTION_TIMEOUT | 504 | Yes | Execution exceeded the allowed time budget. |
| TIMEZONE_UNKNOWN | 400 | No | The request payload failed this skill's input validation. |
| DATETIME_FORMAT_INVALID | 400 | No | The request payload failed this skill's input validation. |
| DATETIME_AMBIGUOUS | 412 | No | The input is valid but cannot be processed as-is. |
| DATETIME_NONEXISTENT | 412 | No | The input is valid but cannot be processed as-is. |
Other limits
| Limit | Value |
|---|---|
| Recommended inline bytes | 32 KiB |
Limitations
- Does not parse natural-language dates (use time.parse_datetime)
- Does not convert between two zones (use time.convert_timezone)
- Reading the offset of an instant you already hold (use time.timezone_offset_at)
- Guessing a zone from a city name
How to call
POST /v1/execute (requires authentication)
{
"skillKey": "time.resolve_local_datetime",
"input": {
"localDateTime": "2026-01-15T12:00:00",
"zoneId": "Europe/Brussels"
}
}Examples
Ordinary winter time in Brussels
{
"localDateTime": "2026-01-15T12:00:00",
"zoneId": "Europe/Brussels"
}{
"offsetSeconds": 3600,
"resolution": "NORMAL",
"candidateOffsets": [
"+01:00"
],
"shiftSeconds": 0,
"instant": "2026-01-15T11:00:00Z",
"offset": "+01:00",
"_meta": {
"tzdbVersion": "2026b"
},
"zoneId": "Europe/Brussels"
}Later pass of the Brussels autumn overlap
{
"localDateTime": "2026-10-25T02:30:00",
"disambiguation": "LATER",
"zoneId": "Europe/Brussels"
}{
"offsetSeconds": 3600,
"resolution": "OVERLAP_LATER",
"candidateOffsets": [
"+02:00",
"+01:00"
],
"shiftSeconds": 0,
"instant": "2026-10-25T01:30:00Z",
"offset": "+01:00",
"_meta": {
"tzdbVersion": "2026b"
},
"zoneId": "Europe/Brussels"
}Recommended use cases
- Turning a wall-clock booking into an instant when DST may fold or skip an hour
- Choosing the later overlap pass, or the next valid time after a spring gap
Avoid for
- Reading the offset of an instant you already hold (use time.timezone_offset_at)
- Guessing a zone from a city name
Related skills
Composable with
Safety & privacy
- Runs without calling any external service.
- Your payloads are never stored permanently.
- Telemetry captures metadata only — never your payload contents.
- We never train models on your payloads.
- No human reviews your payloads.