ISO 8601 Duration Parser
Parse, build, and convert ISO 8601 duration strings like P1Y2M3DT4H5M6S into human-readable time spans.
Parse
Build
P0D
Apply to Date
The ISO 8601 duration parser converts between machine-readable duration strings like P1Y2M3DT4H5M6S and human-readable units. Paste a duration to break it into its components, or fill in the fields to build a valid ISO 8601 duration from scratch. Both directions work bidirectionally and update live as you type.
How ISO 8601 Duration Strings Work
An ISO 8601 duration always starts with the letter P (for "period"). Date components come after P, time components come after a T separator. Each component is a number followed by a unit letter: Y for years, M for months, D for days, H for hours, M for minutes (after T), and S for seconds. Components you do not need can be omitted entirely.
- P1Y means one year.
- P30D means thirty days.
- PT15M means fifteen minutes (the T separator is required because M after P alone means months).
- P1Y2M3DT4H5M6S means one year, two months, three days, four hours, five minutes, and six seconds.
- PT1H30M means one and a half hours.
The M ambiguity is the most common source of bugs: P1M means one month, PT1M means one minute. The T separator is mandatory whenever you have time components, even if no date components are present.
When to Use ISO 8601 Durations
ISO 8601 is the international standard for representing dates and times unambiguously, and the duration format is the standard way to express "an amount of time" in any system that needs to be interoperable across languages and locales:
- JSON APIs: many REST APIs return durations as ISO 8601 strings because they parse identically in every programming language. YouTube's video duration field, GitHub Actions step timeouts, and Kubernetes pod startup probes all use this format.
- XML schemas: the xsd:duration type stores durations as ISO 8601 strings. Any system that reads XML configuration (legacy enterprise apps, RSS feeds, SVG animations) expects this format.
- Java and JavaScript date libraries: Java's Duration.parse() and JavaScript libraries like date-fns and Luxon all accept ISO 8601 strings as input. Building one by hand is faster than constructing the equivalent object in code.
- Recurrence rules: the iCalendar (RFC 5545) format uses ISO 8601 durations in DURATION and TRIGGER properties for calendar events and alarms.
- Database storage: PostgreSQL's INTERVAL type can be cast to and from ISO 8601 strings, making them portable between database engines.
If you need to shift a date by an ISO 8601 duration, the date add/subtract calculator takes the same input units. To compute the duration between two specific dates, use the date difference calculator. For recurring schedules instead of single durations, the cron expression builder generates the matching cron syntax.
Parsing vs Building
Parse mode is for when you receive an ISO duration string from an API, a database, or a config file and need to know what it actually represents. Paste the string and the tool shows each component value, a plain-English description, and the approximate total in seconds. The total seconds value is labeled "approximate" because months and years are calendar-dependent (a month can be 28 to 31 days, a year 365 or 366) - the parser uses average values of 30.44 days per month and 365.25 days per year for the approximation.
Build mode is the reverse: fill the Years, Months, Days, Hours, Minutes, and Seconds fields with whole numbers and the parser assembles the matching ISO 8601 string. Empty or zero fields are omitted from the output, so filling only Minutes with 15 produces PT15M, not P0Y0M0DT0H15M0S. This makes the result clean and portable.
Why Total Seconds Is Approximate for Months and Years
ISO 8601 durations are calendar-relative for the larger units. "One month" added to January 1 is 31 days; "one month" added to February 1 is 28 or 29 days. Until the duration is anchored to a specific start date, there is no single correct integer answer for "how many seconds is P1M". The parser reports an average for convenience (30.44 days per month = 2,629,800 seconds), which is good enough for sizing buffers or comparing durations, but should not be used for billing, exact scheduling, or anything where the calendar matters.
For exact arithmetic against a real date, paste the resulting duration components into the date add/subtract calculator along with the anchor date - that tool applies calendar rules properly. To go in the other direction (compute an ISO duration between two known dates), use the date difference calculator and then build the matching string here from the resulting unit counts.
Frequently Asked Questions
P stands for "period" and is the required prefix for every ISO 8601 duration string. It marks the value as a duration so parsers can distinguish it from a date or a timestamp. Without the leading P the string is invalid and most libraries will refuse to parse it.
P1M is one month. PT1M is one minute. The letter M is reused for both months and minutes, and the T separator (which marks the start of the time portion) is the only way to tell them apart. Always include the T whenever your duration has hours, minutes, or seconds, even if no date components are present.
Months and years vary in length depending on the calendar context. One month is 28 to 31 days; one year is 365 or 366. The parser uses averages (30.44 days per month, 365.25 days per year) to compute Total Seconds, which is good enough for sizing intervals or comparing durations but not exact. For precise arithmetic anchor the duration to a real date and use the date add/subtract calculator.
ISO 8601 technically allows a fractional value on the smallest unit (for example PT1.5H or PT30.5S), but support varies between parsers - Java accepts it, JavaScript's standard library does not. For maximum portability, convert the fractional value to the next smaller unit (PT1.5H becomes PT1H30M, PT30.5S becomes PT30S500MS in libraries that support milliseconds).
The ISO 8601 standard does not officially support negative durations, but some implementations extend it with a leading minus sign (for example -PT5M for negative five minutes). Java's Duration class accepts the leading minus, while the strict standard does not. If you need a negative duration, use Subtract mode in the date add/subtract calculator instead.
P0D is a valid duration meaning zero days, equivalent to no time at all. Some systems use it as a "null" or "no offset" value where an empty string is not allowed. PT0S (zero seconds) and PT0M (zero minutes) are equally valid representations. The parser accepts all three and reports zero for every component.
YouTube's API returns the contentDetails.duration field as an ISO 8601 string. A 3-minute and 30-second video appears as PT3M30S. A 1-hour and 15-minute video appears as PT1H15M. Paste the string into the parser to read it as minutes and seconds, then format it for display however your app needs.
The portable form is PT30M (thirty minutes). PT0.5H is technically valid per the spec but not universally supported. Both represent the same duration; the builder produces the portable form by default to maximize compatibility with parsers in different languages.
A duration is an amount of time with no anchor (P1Y means "one year" without saying which year). An interval has two anchors and represents a specific span between two moments (2026-01-01/2027-01-01 or 2026-01-01/P1Y). ISO 8601 supports both formats. The parser on this page handles durations; for intervals, anchor the duration to a real date using the date add/subtract calculator.
PostgreSQL accepts ISO 8601 duration strings directly for its INTERVAL type: SELECT INTERVAL 'P1Y2M3DT4H5M6S'. MySQL does not parse ISO 8601 durations natively - you need to translate to the integer-and-unit syntax it uses (INTERVAL 1 YEAR + INTERVAL 2 MONTH + INTERVAL 3 DAY). Paste the ISO string into the parser to see the integer values, then build the equivalent MySQL expression.