← More from code, and code examples
How do I turn time words into a date?
Short answer
Send the words and a time zone to POST https://id.gilb.com/base/time/resolve, and read the start and end back in UTC.
Before you start
You know the time zone the words are meant in.
Words used here (2)
- IANA time zone name
- An IANA time zone name is one zone name from the IANA time zone database, such as Europe/Oslo; it is not a UTC offset.
- field
- A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
Steps
Send the words and a time zone.
Send phrase, the words, and zone, an IANA time zone name such as Europe/Oslo, as JSON, with no token:
POST https://id.gilb.com/base/time/resolveMore about this
It reads only a fixed list of phrases, in any case, such as: today, yesterday, tomorrow; last, this or next week, month, quarter or year; a weekday, such as tuesday or tuesday at 09:00; by friday; 3 days ago; past 7 days; this week so far; year to date; march; week 12; the 1990s; during 2020; since 2015; between 09:00 and 17:00; monday to friday; at noon; in 2 hours; within 2 hours; 5 business days later; the first monday; 2026-11-12; 2026-11-12T09:00 Europe/Oslo. A weekday alone means that day in this week, which starts on Monday, even when it has passed. next tuesday is not on the list, and words not on it are not read.
Read the start and end back.
The answer is zulu, with start and end in UTC, the world's reference time, written with a Z at the end. The end is not included: today ends at the next midnight in your zone.
More about this
A single moment, such as in 2 hours, has start and end the same and point true. by friday has start null. Words that are not a stretch of time come back in their own field: floating for a clock time with no day, such as 14:00; length for for 3 hours; repeat for every monday; rate for twice a week. When the words cannot be read the answer is still 200, with unresolved and a reason, such as phrase-unknown, zone-missing, zone-unknown, or local-time-ambiguous with detail skipped or repeated for a clock time that does not exist, or comes twice, when the clocks change.
To say a span in words, send it to POST /base/time/render.
Send start, end and zone as JSON:
POST https://id.gilb.com/base/time/renderMore about this
The answer is text, such as 2026-11-16 – 2026-11-22 for a week, with zone and rule, Gregorian, Monday week, end not included. A start of null gives before and the end. end must be text, so a span with no end, such as from now on, cannot be said this way: it answers 400 zone and end are required. A zone the server does not know answers 200 with unresolved zone-unknown.
Deeper
Also asked:
How do I turn words like next Friday into a date? Send them with a time zone to POST https://id.gilb.com/base/time/resolve. next friday is not on its list and comes back unresolved; friday means Friday of this week, and next week the whole of next week.
GilbPlatform never uses the server's own time zone and never guesses one. A zone written in the words wins; then zone. Without zone, the request may carry readingZone, the zone a person reads calendar words in, or, with placeNamed true, wallZone, the zone of the place the words name. With none of them, words that need a zone answer zone-missing. past 7 days, 2 hours ago, in 2 hours and a UTC time such as 2026-11-12T08:00:00Z need no zone.
The words are read against now, the server's clock, unless the request sends now, a UTC time. the day before and 3 days after count from anchor, a UTC time the request sends; without it they answer anchor-missing. in Europe/Oslo gives the time now, or the time at instant, a UTC time the request sends, on that zone's clock, as text such as 2026-11-11 18:45, in the field wall.
A body that is a JSON value other than an object or an array, such as a string or a number, answers 400 body must be an object; an object or an array with no phrase and no expression answers 400 phrase or expression is required. expression is the form the words are turned into; this answer sends phrase. Both routes need no token and read no vault: they only do the calendar sums.
The Developer Guide, GilbPlatform's guide for people who build apps on it, has no chapter on this yet; this answer is written from GilbPlatform's code.
Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/time.ts:1-3 ("It does not look up a user or a place, and it does not read the host zone. The caller passes the zone"), :10-23 (body phrase, expression, now, zone, anchor, instant, readingZone, wallZone, placeNamed), :25-29 (render body start, end, zone), :35-60 (resolve: body must be an object, phrase or expression is required, now defaults to the server clock), :62-73 (render: zone and end are required, start must be a Zulu instant or null), :85-100 (POST /base/time/resolve and /base/time/render; 400 {error:BadRequest, message}; no principal read: no token needed); src/server/app.ts:792 (registered; no auth hook in front: :356-434 are context hooks only); src/time/parse.ts:39-170 (the closed phrase list; lower-cased; next tuesday matches none and falls to civilOrInstant: phrase-unknown), :7-37 and :236-239 (number words); src/time/resolve.ts:21 (CALENDAR_RULE Gregorian, Monday week, end not included), :76-93 (ZuluSpan: start null only for an open start; end exclusive; point; result kinds zulu, unresolved, floating, length, repeat, rate, wall), :215-228 (zone-missing, zone-unknown), :268-275 (weekday = that day of this Monday week), :529-533, :567-571 (local-time-ambiguous, detail skipped|repeated from src/time/zone.ts:68, :103), :492-500 (anchor-missing), :520-527 (renderIn: instant or now), :619-645 (render text; before ...; day spans a – b); src/time/stored-zone.ts:60-78 (a zone in the words wins; then zone; then readingZone or, with placeNamed, wallZone; kinds that need no zone); src/time/zone.ts:13-20 (zone known to Intl). GilbVeda (public read, 2026-11-11): t:ReadingZone, t:WallZone, t:IanaTimeZoneName (all Suggested). Shared with the GilbVeda page on space and time: "Programs can turn words for a time into an exact time, for a time zone the program names." No Developer Guide chapter covers time words. GilbPlatform 0fc5a548 (https://id.gilb.com/version, read 14 November 2026): src/time/parse.ts:148-153 (a weekday alone, or with a time), :169 (last, this or next only before week, month, quarter or year).
For developers
curl
resolve.sh
# Turn words into a UTC span. No token is needed.
curl -s https://id.gilb.com/base/time/resolve \
-H "Content-Type: application/json" \
-d '{"phrase":"next week","zone":"Europe/Oslo"}'
# 200: {"zulu":{"start":"<UTC time>","end":"<UTC time>"}}
# Words it cannot read: {"unresolved":{"reason":"phrase-unknown"}}
curl
render.sh
# Say a UTC span on a zone's clock.
curl -s https://id.gilb.com/base/time/render \
-H "Content-Type: application/json" \
-d '{"start":"<UTC start>","end":"<UTC end>","zone":"Europe/Oslo"}'
# 200: {"text":"<the span on that clock>","zone":"Europe/Oslo","rule":"Gregorian, Monday week, end not included"}
TypeScript
time-words.ts
// Turn time words into a UTC span with POST /base/time/resolve.
export type Resolved =
| { zulu: { start: string | null; end: string | null; point?: true } }
| { unresolved: { reason: string; detail?: string } }
| { floating: { time: string } }
| { length: { unit: string; count: number; seconds?: number } }
| { repeat: { every: string; time?: string; interval: number } }
| { rate: { count: number; per: string } }
| { wall: { text: string; zone: string; rule: string } };
export async function timeWords(phrase: string, zone: string): Promise<{ start: string | null; end: string | null }> {
const res = await fetch("https://id.gilb.com/base/time/resolve", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ phrase, zone }),
});
if (!res.ok) throw new Error(`time words answered ${res.status}`);
const answer = (await res.json()) as Resolved;
if ("zulu" in answer) return { start: answer.zulu.start, end: answer.zulu.end };
if ("unresolved" in answer) throw new Error(`not read: ${answer.unresolved.reason}`);
throw new Error("these words are not a stretch of time");
}
Checked against GilbApp 49467c2.