Skip to main content

Random Date Generator API

MOCK DATA

Uniformly random timestamps from any date range — ISO instant, Unix seconds, date, time and weekday — with an exact weekdays-only mode and seeded results.

Generated test data for fixtures and development

Base URL
/api/dates
Category
Date & Time
Capabilities
1 route Seedable
Last updated
July 29, 2026

GET /api/dates Uniformly random instants within a date range

Every record is an independent uniform draw from [from, to] (millisecond precision, both bounds inclusive). The resolved range — defaults included — is echoed in meta.params.

Live requestRuns against the public API
No key required
GET/api/dates

Request parameters

Earliest possible instant, inclusive. YYYY-MM-DD (= midnight UTC) or a full ISO 8601 timestamp. Years 1583–9999. Defaults to 365 days before today (UTC).

Latest possible instant, inclusive. YYYY-MM-DD means midnight UTC — that day is included only at exactly 00:00:00; pass a timestamp to cover it fully. Must be ≥ from. Defaults to today at UTC midnight.

Only return instants that fall on Monday–Friday (UTC weekday), uniformly across the weekday portion of the range. Include the parameter bare to enable. A range with no weekday instant is a 400.

Advanced response options7 options

How many records to generate (1–100).

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/dates"
const res = await fetch("https://randomapi.dev/api/dates");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/dates").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/dates"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
from date

Earliest possible instant, inclusive. YYYY-MM-DD (= midnight UTC) or a full ISO 8601 timestamp. Years 1583–9999. Defaults to 365 days before today (UTC).

example: from=2026-01-01
to date

Latest possible instant, inclusive. YYYY-MM-DD means midnight UTC — that day is included only at exactly 00:00:00; pass a timestamp to cover it fully. Must be ≥ from. Defaults to today at UTC midnight.

example: to=2026-12-31
weekdaysOnly boolean

Only return instants that fall on Monday–Friday (UTC weekday), uniformly across the weekday portion of the range. Include the parameter bare to enable. A range with no weekday instant is a 400.

default: false
example: weekdaysOnly=true
Universal parameters Shared response and formatting options 7
count int

How many records to generate (1–100).

default: 10
allowed: 1 – 100
example: count=3
seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=iso,unix
exclude list

Return all fields except these (comma-separated).

example: exclude=weekday
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 5
iso string (ISO 8601)

The generated instant in UTC, with millisecond precision.

example: 2026-03-14T09:26:53.123Z

unix integer

Seconds since the Unix epoch (floor of the instant; negative before 1970).

example: 1773480413

date string (YYYY-MM-DD)

UTC calendar date of the instant.

example: 2026-03-14

time string (HH:MM:SS)

UTC wall-clock time of the instant, seconds precision (milliseconds live in iso).

example: 09:26:53

weekday string

English weekday name of the UTC date — never Saturday/Sunday when weekdaysOnly=true.

example: Saturday

Documented examples

Build-generated requests and complete responses 4
Ten dates from the past year
GET /api/dates 
{
  "data": [
    {
      "iso": "2026-01-19T09:22:04.990Z",
      "unix": 1768814524,
      "date": "2026-01-19",
      "time": "09:22:04",
      "weekday": "Monday"
    },
    {
      "iso": "2025-08-12T10:25:52.652Z",
      "unix": 1754994352,
      "date": "2025-08-12",
      "time": "10:25:52",
      "weekday": "Tuesday"
    },
    {
      "iso": "2026-06-06T19:10:47.489Z",
      "unix": 1780773047,
      "date": "2026-06-06",
      "time": "19:10:47",
      "weekday": "Saturday"
    },
    {
      "iso": "2025-09-23T08:07:07.137Z",
      "unix": 1758614827,
      "date": "2025-09-23",
      "time": "08:07:07",
      "weekday": "Tuesday"
    },
    {
      "iso": "2026-05-29T07:12:49.356Z",
      "unix": 1780038769,
      "date": "2026-05-29",
      "time": "07:12:49",
      "weekday": "Friday"
    },
    {
      "iso": "2025-08-04T01:40:39.031Z",
      "unix": 1754271639,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Five dates within 2026
GET /api/dates?from=2026-01-01&to=2026-12-31&count=5 
{
  "data": [
    {
      "iso": "2026-06-23T21:54:04.647Z",
      "unix": 1782251644,
      "date": "2026-06-23",
      "time": "21:54:04",
      "weekday": "Tuesday"
    },
    {
      "iso": "2026-01-15T09:28:55.796Z",
      "unix": 1768469335,
      "date": "2026-01-15",
      "time": "09:28:55",
      "weekday": "Thursday"
    },
    {
      "iso": "2026-11-08T22:36:44.071Z",
      "unix": 1794177404,
      "date": "2026-11-08",
      "time": "22:36:44",
      "weekday": "Sunday"
    },
    {
      "iso": "2026-02-26T04:24:51.172Z",
      "unix": 1772079891,
      "date": "2026-02-26",
      "time": "04:24:51",
      "weekday": "Thursday"
    },
    {
      "iso": "2026-10-31T11:12:17.659Z",
      "unix": 1793445137,
      "date": "2026-10-31",
      "time": "11:12:17",
      "weekday": "Saturday"
    }
  ],
  "meta": {
    "endpoint": "dates",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Reproducible weekday timestamps for Q1 2026
GET /api/dates?from=2026-01-01&to=2026-03-31&weekdaysOnly=true&seed=42&count=3 
{
  "data": [
    {
      "iso": "2026-02-12T02:24:21.574Z",
      "unix": 1770863061,
      "date": "2026-02-12",
      "time": "02:24:21",
      "weekday": "Thursday"
    },
    {
      "iso": "2026-01-05T11:47:41.964Z",
      "unix": 1767613661,
      "date": "2026-01-05",
      "time": "11:47:41",
      "weekday": "Monday"
    },
    {
      "iso": "2026-03-17T23:45:35.320Z",
      "unix": 1773791135,
      "date": "2026-03-17",
      "time": "23:45:35",
      "weekday": "Tuesday"
    }
  ],
  "meta": {
    "endpoint": "dates",
    "count": 3,
    "seed": 42,
    "params": {
      "from": "2026-01-01",
      "to": "2026-03-31",
      "weekdaysOnly": true
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Just the dates, as CSV
GET /api/dates?from=2026-01-01&to=2026-06-30&fields=date&format=csv 
date
2026-03-28
2026-01-08
2026-06-04
2026-01-28
2026-05-31
2026-01-03
2026-01-15
2026-05-31
2026-03-23
2026-06-23

About this API

Coverage, behavior and common use cases

Coverage & behavior

Each record is one uniformly random instant, drawn at millisecond precision from the inclusive range [from, to] and returned in five ready-to-use shapes: the full ISO 8601 instant (iso), Unix seconds (unix), the UTC calendar date (date), the UTC wall-clock time (time) and the UTC weekday name.

The behaviors that usually bite are pinned down:

  • Defaults = the past year. Omit both bounds and the range is the 365 days ending today: to defaults to today at UTC midnight, from to 365 days before that. The resolved bounds are always echoed in meta.params, so you can see exactly what range was used.
  • Bounds are instants, and date-only values mean midnight UTC. to=2026-12-31 is the instant 2026-12-31T00:00:00Z — December 31 itself is only included at exactly midnight. Pass a timestamp (to=2026-12-31T23:59:59Z) to cover the whole day. Both endpoints of the range are reachable, and from=to legitimately pins every record to that single instant (with a warning).
  • weekdaysOnly=true keeps output on Monday–Friday by UTC weekday — and it stays exactly uniform over the weekday portion of the range (no naive shift-off-the-weekend pile-up on Mondays and Fridays). A range containing no weekday instant at all (say, a single Saturday) is rejected with a 400 instead of quietly returning weekend data.
  • from > to is a 400 naming both values — never a silent swap. Years are limited to 1583–9999: weekday names before the Gregorian reform would be historically wrong, and beyond 9999 the date field couldn't stay YYYY-MM-DD.

This is mock data — random instants, not a dataset. With a seed the same query returns identical dates forever. For calendar facts about a specific date (ISO week, leap year, day of year) use /api/date-info; for the live clock in a timezone use /api/time.

Use it for

  • Seed databases with realistic createdAt/updatedAt timestamps over a chosen window
  • Reproducible date fixtures for tests — pin a seed and the dates never change
  • Simulate business-day events (orders, logins, trades) with weekdaysOnly for realistic charts

Frequently asked questions

Practical answers about this endpoint 3
How do I bound the range?

from and to (YYYY-MM-DD) — timestamps are uniform inside the range, and both bounds genuinely constrain output (contract-tested).

Can I get weekdays only?

Yes — weekdaysOnly=true excludes Saturdays and Sundays exactly, not probabilistically.

What formats are in each record?

ISO 8601 instant, Unix seconds, date, time and weekday — project what you need with fields.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Date Info API REAL DATA

Real calendar facts for any date — weekday, ISO week, day of year, quarter, leap year, days in month, weekend flag and Unix timestamp. Defaults to today.
Current Time API REAL DATA

Current time in any IANA timezone — UTC instant, unix seconds, local date & time, UTC offset, ISO week, day of year and a live DST flag.
Fake Transaction Data API MOCK DATA

Fake account transactions with realistic merchants, weighted statuses and currency-correct amounts — filter by type, status, amount range and date window.
Fake Product Review API MOCK DATA

Sentiment-coherent fake product reviews — 1–2★ complain, 3★ shrug, 4–5★ rave — with star-rating and date-range filters and full seed determinism.