BrainyCalc Docs — Date & Time

API Reference

Date & Time

Deterministic tools for date differences, workday computations, Unix timestamp conversions, age calculations, worldwide time zone lookups, duration arithmetic, and fertility cycle estimation.

datetime_difference datetime_add_subtract datetime_work_days datetime_calculate_age datetime_unix_timestamp datetime_day_of_week calc_age calc_date_diff calc_day_counter calc_day_of_week calc_local_time calc_world_time calc_time_duration calc_time_add calc_hours_between calc_pregnancy calc_due_date calc_ovulation calc_period

datetime_difference

Calculate total duration and difference between two dates in days, hours, minutes, and formatted weeks/days.

date arithmetic

Parameter	Type	Required	Description
`startDate`	string	required	Start date in ISO 8601 format (`YYYY-MM-DD`)
`endDate`	string	required	End date in ISO 8601 format (`YYYY-MM-DD`)

Request / Response

// Request
{ "startDate": "2026-01-01", "endDate": "2026-08-05" }

// Response
{
  "startDate": "2026-01-01",
  "endDate": "2026-08-05",
  "difference": {
    "totalDays": 216,
    "totalHours": 5184,
    "totalMinutes": 311040,
    "formatted": "30 weeks and 6 days"
  }
}

datetime_add_subtract

Add or subtract specified amounts of days, weeks, months, years, hours, or minutes to/from a date.

date arithmetic

Parameter	Type	Required	Description
`startDate`	string	required	Base start date string (`YYYY-MM-DD`)
`amount`	number	required	Quantity of units to shift
`unit`	enum	required	`days` · `weeks` · `months` · `years` · `hours` · `minutes`
`operation`	enum	optional	`add` (default) or `subtract`

Request / Response

// Add 14 days to August 5, 2026
{ "startDate": "2026-08-05", "amount": 14, "unit": "days", "operation": "add" }

{
  "initialDate": "2026-08-05",
  "operation": "add",
  "amount": 14,
  "unit": "days",
  "resultDate": "2026-08-19T00:00:00.000Z"
}

datetime_work_days

Calculate working days between two dates, with an option to include or exclude weekends.

business

Parameter	Type	Required	Description
`startDate`	string	required	Start date (`YYYY-MM-DD`)
`endDate`	string	required	End date (`YYYY-MM-DD`)
`includeWeekends`	boolean	optional	Include weekends in total count (default: `false`)

Request / Response

{ "startDate": "2026-08-03", "endDate": "2026-08-14", "includeWeekends": false }

{
  "startDate": "2026-08-03",
  "endDate": "2026-08-14",
  "workDaysCount": 10,
  "weekendsIncluded": false
}

datetime_calculate_age

Calculate exact age in years, months, and days relative to a target date or today.

age

Parameter	Type	Required	Description
`birthDate`	string	required	Birth date (`YYYY-MM-DD`)
`targetDate`	string	optional	Reference date (defaults to current system date)

Request / Response

{ "birthDate": "1990-05-15", "targetDate": "2026-08-05" }

{
  "birthDate": "1990-05-15",
  "years": 36,
  "months": 2,
  "days": 21,
  "totalDays": 13231,
  "formatted": "36 years, 2 months, 21 days"
}

datetime_unix_timestamp

Convert date strings to Unix timestamps (seconds & milliseconds) or convert numeric timestamps back to ISO dates.

conversion

Parameter	Type	Required	Description
`value`	string	required	ISO date string or numeric timestamp string
`mode`	enum	optional	`to_timestamp` (default) or `from_timestamp`

Request / Response

{ "value": "2026-08-05T12:00:00Z", "mode": "to_timestamp" }

{
  "dateString": "2026-08-05T12:00:00Z",
  "timestampSeconds": 1785931200,
  "timestampMs": 1785931200000
}

datetime_day_of_week

Determine day name, weekend status, and day number of the year for any date.

calendar

Parameter	Type	Required	Description
`date`	string	required	Date string (`YYYY-MM-DD`)

Request / Response

{ "date": "2026-08-05" }

{
  "date": "2026-08-05",
  "dayName": "Wednesday",
  "isWeekend": false,
  "dayOfYear": 217
}

calc_age

Extended age calculator returning years, months, days, total days, and total weeks from a birth date.

extended date

Parameter	Type	Required	Description
`birth_date`	string	required	Birth date (`YYYY-MM-DD`)
`reference_date`	string	optional	Reference date (defaults to today)

Request / Response

{ "birth_date": "1995-10-20", "reference_date": "2026-08-05" }

{
  "birth_date": "1995-10-20",
  "years": 30,
  "months": 9,
  "days": 16,
  "total_days": 11247,
  "total_weeks": 1606
}

calc_date_diff

Calculate date difference across multiple metrics: exact days, weeks, months, and years.

extended date

Parameter	Type	Required	Description
`date1`	string	required	First date (`YYYY-MM-DD`)
`date2`	string	required	Second date (`YYYY-MM-DD`)

Request / Response

{ "date1": "2026-01-01", "date2": "2026-08-05" }

{
  "date1": "2026-01-01",
  "date2": "2026-08-05",
  "days": 216,
  "weeks": 30.86,
  "months": 7.1,
  "years": 0.5914
}

calc_day_counter

Count the exact number of days and relative periods between a start date and an end date.

extended date

Parameter	Type	Required	Description
`start_date`	string	required	Start date (`YYYY-MM-DD`)
`end_date`	string	required	End date (`YYYY-MM-DD`)

Request / Response

{ "start_date": "2026-01-01", "end_date": "2026-12-31" }

{
  "date1": "2026-01-01",
  "date2": "2026-12-31",
  "days": 364,
  "weeks": 52,
  "months": 11.96,
  "years": 0.9966
}

calc_day_of_week

Get weekday name, month name, day of month, year, and calculated week number for a given date.

calendar

Parameter	Type	Required	Description
`date`	string	required	Target date (`YYYY-MM-DD`)

Request / Response

{ "date": "2026-08-05" }

{
  "date": "2026-08-05",
  "day_of_week": "Wednesday",
  "month": "August",
  "day_number": 5,
  "year": 2026,
  "week_number": 1
}

calc_local_time

Retrieves current local time, formatted date, runtime IANA timezone, Unix timestamp, and timezone offset.

world time

Parameter	Type	Required	Description
No parameters required

Request / Response

// Request
{}

// Response
{
  "local_time": "11:43:00",
  "local_date": "Wednesday, August 5, 2026",
  "timezone": "America/New_York",
  "timezone_display": "America/New York",
  "timestamp": 1785930180000,
  "timezone_offset_mins": 240
}

calc_world_time

Search current time across global cities/countries, filter by region, or perform direct IANA time zone queries.

world time

Parameter	Type	Required	Description
`query`	string	optional	Country or city name to search (e.g., `"Tokyo"`, `"United Kingdom"`)
`region`	enum	optional	`All` · `Africa` · `Americas` · `Asia` · `Europe` · `Oceania`
`timezone`	string	optional	Direct IANA timezone string (e.g., `"Asia/Kabul"`)
`offset_hours`	number	optional	UTC offset hours fallback
`offset_minutes`	number	optional	UTC offset minutes fallback

Request / Response

{ "query": "Tokyo" }

{
  "query": "Tokyo",
  "region": "All",
  "match_count": 1,
  "results": [
    {
      "flag": "🇯🇵",
      "country": "Japan",
      "city": "Tokyo",
      "timezone": "Asia/Tokyo",
      "region": "Asia",
      "time": "00:43:00",
      "date": "Thu, Aug 6",
      "offset_string": "GMT+9"
    }
  ]
}

calc_time_duration

Calculates time duration between two times of day (HH:MM or HH:MM:SS), handling overnight roll-overs automatically.

time math

Parameter	Type	Required	Description
`start`	string	required	Start time (`HH:MM` or `HH:MM:SS`)
`end`	string	required	End time (`HH:MM` or `HH:MM:SS`)

Request / Response

{ "start": "09:00:00", "end": "17:30:00" }

{
  "start": "09:00:00",
  "end": "17:30:00",
  "hours": 8,
  "minutes": 30,
  "seconds": 0,
  "total_seconds": 30600,
  "display": "8h 30m 0s"
}

calc_time_add

Add or subtract hours, minutes, and seconds to/from a base time string.

time math

Parameter	Type	Required	Description
`time`	string	required	Base time string (`HH:MM` or `HH:MM:SS`)
`add_hours`	number	optional	Hours to add (positive or negative)
`add_minutes`	number	optional	Minutes to add (positive or negative)
`add_seconds`	number	optional	Seconds to add (positive or negative)

Request / Response

{ "time": "14:15:00", "add_hours": 3, "add_minutes": 45 }

{
  "original": "14:15:00",
  "result": "18:00:00",
  "added": { "hours": 3, "minutes": 45, "seconds": 0 }
}

calc_hours_between

Calculate elapsed hours, minutes, and seconds between two times. Alias for calc_time_duration.

time math

Parameter	Type	Required	Description
`start`	string	required	Start time (`HH:MM` or `HH:MM:SS`)
`end`	string	required	End time (`HH:MM` or `HH:MM:SS`)

Request / Response

{ "start": "08:30:00", "end": "16:45:00" }

{
  "start": "08:30:00",
  "end": "16:45:00",
  "hours": 8,
  "minutes": 15,
  "seconds": 0,
  "total_seconds": 29700,
  "display": "8h 15m 0s"
}

calc_pregnancy

Computes estimated due date, conception date, current week/day progress, remaining days, and trimester from LMP.

pregnancy

Parameter	Type	Required	Description
`lmp_date`	string	required	Last menstrual period date (`YYYY-MM-DD`)

Request / Response

{ "lmp_date": "2026-01-01" }

{
  "lmp_date": "2026-01-01",
  "due_date": "2026-10-08",
  "conception_estimate": "2026-01-15",
  "weeks_pregnant": 31,
  "days_into_week": 0,
  "days_remaining": 64,
  "trimester": "Third (weeks 27–40)"
}

calc_due_date

Estimate pregnancy due date and progress metrics from last menstrual period. Alias for calc_pregnancy.

pregnancy

Parameter	Type	Required	Description
`lmp_date`	string	required	Last menstrual period date (`YYYY-MM-DD`)

Request / Response

{ "lmp_date": "2026-01-01" }

{
  "lmp_date": "2026-01-01",
  "due_date": "2026-10-08",
  "conception_estimate": "2026-01-15",
  "weeks_pregnant": 31,
  "days_remaining": 64,
  "trimester": "Third (weeks 27–40)"
}

calc_ovulation

Calculates estimated ovulation date, fertile window range, and next period start date.

cycle

Parameter	Type	Required	Description
`lmp_date`	string	required	Last menstrual period date (`YYYY-MM-DD`)
`cycle_length`	number	optional	Average cycle length in days (default: `28`)

Request / Response

{ "lmp_date": "2026-08-01", "cycle_length": 28 }

{
  "lmp_date": "2026-08-01",
  "cycle_length": 28,
  "ovulation_date": "2026-08-15",
  "fertile_window_start": "2026-08-10",
  "fertile_window_end": "2026-08-16",
  "next_period": "2026-08-29"
}

calc_period

Predicts start and end dates for the next 3 menstrual cycles based on LMP and cycle parameters.

cycle

Parameter	Type	Required	Description
`lmp_date`	string	required	Last menstrual period date (`YYYY-MM-DD`)
`cycle_length`	number	optional	Cycle length in days (default: `28`)
`period_length`	number	optional	Period duration in days (default: `5`)

Request / Response

{ "lmp_date": "2026-08-01", "cycle_length": 28, "period_length": 5 }

{
  "lmp_date": "2026-08-01",
  "cycle_length": 28,
  "period_length": 5,
  "next_3_periods": [
    { "start": "2026-08-29", "end": "2026-09-02" },
    { "start": "2026-09-26", "end": "2026-09-30" },
    { "start": "2026-10-24", "end": "2026-10-28" }
  ]
}