Parse relative dates
From 10 January 2020 at 12:00 UTC, the phrase in 3 days becomes 13 January 2020 at 12:00 UTC. Type a short English or Spanish phrase and a reference moment to get the exact date and time it points to. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Text
- in 3 days
- Anchor
- 2020-01-10T12:00:00.000Z
- ISO date and time
- 2020-01-13T12:00:00.000Z
- Unix timestamp (milliseconds)
- 1,578,916,800,000
Parse finite English/Spanish relative phrases into absolute ISO timestamps against an anchor.
From a phrase to an exact moment
People write dates relative to now all the time: in 3 days, in a few weeks, a while ago. A phrase like that has no fixed meaning until you say where it starts, which is why the tool asks for a reference moment. It then counts forward or back from that moment and gives you the exact result. The time of day carries over unchanged, so a phrase counted from noon still lands at noon: from 10 January 2020 at 12:00 UTC, in 3 days becomes 13 January 2020 at 12:00 UTC. You get the result both as a readable date and time and as a single number of milliseconds.
Getting reliable answers
The most common surprise comes from the reference moment. Counted from a different starting point, the same phrase points to a different day, so keep the reference with the result whenever it matters. The tool works with a limited set of short English and Spanish phrases rather than any sentence, and an empty phrase or a value that is not text is rejected before anything is calculated. Everything happens on your device with nothing looked up online, so the same phrase and the same reference moment always give the same answer, without a spreadsheet.
Edge cases and limits
Empty strings, wrong types, and contradictory ranges are rejected early. Civil dates without timezone are calendar dates. Embedded tables travel inside the capability folder with no network calls at runtime.
Review examples before integrating.
What you can do with it
Daily work
Get a reliable answer without a spreadsheet.
FAQ
What is a relative date?
It is an expression such as in 3 days that only makes sense from a starting point. On its own it names no day; with a reference moment it points to one exact date and time.
What is the reference moment for?
It is the instant the phrase counts from. The same phrase gives different results from different reference moments, so note which one you used if you need to repeat the calculation later.
Which languages can I write the phrase in?
English or Spanish. The tool understands a limited set of short relative phrases in those two languages rather than any sentence you like, which keeps every answer predictable.
What does the result contain?
The date and time in ISO format, such as 2020-01-13 at 12:00 UTC, and the same moment as a count of milliseconds, here 1578916800000, ready for a spreadsheet or another tool.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/date/relative-parse \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"in 3 days"}'const res = await fetch("https://api.kit.forhosting.com/date/relative-parse", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "in 3 days"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/date/relative-parse",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"text": "in 3 days"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/relative-parse", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"text":"in 3 days"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"text":"in 3 days"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/relative-parse", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"text": "in 3 days"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "date.relative_parse",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
How it works
Parse finite English/Spanish relative phrases into absolute ISO timestamps against an anchor. The calculation is fully deterministic and runs free in your browser with the same pure function as the API. Inputs are validated before arithmetic so bad types become clear invalid_input errors. Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values. Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values.
Inputs and outputs
Optional fields use documented defaults. Required schema fields must be present and typed. Success payloads always include the primary output fields so UI bindings stay stable. Extremely large intermediates that overflow IEEE-754 become out-of-range errors rather than nulls. Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values. Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values.
Edge cases and limits
Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values. Additional guidance covers validation order, deterministic results, browser and API parity, stable error match strings for certification, and safe handling of out-of-range floating values.
Integration use cases
Automation
Same pure function in widget and API.
Teaching
Stable golden fixtures for demos.
Technical questions
Is it free?
Yes, tier A in the browser.
Network?
No network; parse on-device.
Invalid input?
invalid_input with a clear match.
Stable?
Deterministic goldens freeze the contract.
Author?
samurai.