# How do I turn time words into a date?

Checked 2026-11-14 against GilbApp 49467c2b74111a7021a0419594f5f64ec3cc0eb0.

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.

## Steps

1. 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/resolve

   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.
2. 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.

   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.
3. 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/render

   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

```curl
# 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

```curl
# 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

```typescript
// 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");
}
```
