ISO 8601 Duration Calculator
Our time & timestamps tool computes iso8601duration accurately. Enter your inputs for detailed analysis and optimization tips.
Formula
P[n]Y[n]M[n]W[n]DT[n]H[n]M[n]S
P designates the period (required). Date components follow: Y (years), M (months), W (weeks), D (days). T separates date from time components: H (hours), M (minutes), S (seconds). Each n is a positive integer. Components with zero values are omitted. Approximate conversions use 365 days per year and 30 days per month.
Worked Examples
Example 1: Building a Video Duration for Schema Markup
Problem: A video is 2 hours, 15 minutes, and 30 seconds long. Generate the ISO 8601 duration for use in schema.org VideoObject markup.
Solution: Hours: 2, Minutes: 15, Seconds: 30\nNo date components needed\nISO 8601 = P + T + 2H + 15M + 30S = PT2H15M30S\nThis can be placed in the duration property of a VideoObject schema.
Result: ISO 8601 Duration: PT2H15M30S | Total seconds: 8,130 | Total minutes: 135.50
Example 2: Parsing an API Subscription Period
Problem: An API returns the subscription duration as P1Y3M15D. Parse this into human-readable form and calculate approximate total days.
Solution: P1Y3M15D parses as:\nYears: 1, Months: 3, Days: 15\nApproximate total days = 1 x 365 + 3 x 30 + 15 = 365 + 90 + 15 = 470 days\nTotal hours = 470 x 24 = 11,280 hours\nTotal seconds = 470 x 86,400 = 40,608,000
Result: Human readable: 1 year, 3 months, 15 days | Approx. 470 days | 40,608,000 seconds
Frequently Asked Questions
What is the ISO 8601 duration format and where is it used?
ISO 8601 is an international standard for representing dates, times, and durations. The duration component uses the format PnYnMnWnDTnHnMnS, where P marks the beginning of a duration (for period), followed by optional date components (Years, Months, Weeks, Days) and time components preceded by T (Hours, Minutes, Seconds). For example, P1Y2M3DT4H5M6S represents 1 year, 2 months, 3 days, 4 hours, 5 minutes, and 6 seconds. This format is widely used in programming languages, APIs, databases, calendar applications, schema markup for search engines, video metadata, subscription services, and project management tools because it provides a language-independent, unambiguous way to express time durations.
How do I read and interpret ISO 8601 duration strings?
An ISO 8601 duration string always starts with the letter P (for period). Everything after P and before T (if present) represents the date portion: Y for years, M for months, W for weeks, D for days. The letter T separates date from time components. After T: H represents hours, M represents minutes, and S represents seconds. Note that M means months before T and minutes after T. Some examples: PT30M means 30 minutes, P7D means 7 days, P1Y6M means 1 year and 6 months, P2DT12H means 2 days and 12 hours, and PT1H30M means 1 hour and 30 minutes. Any component with a zero value can be omitted. The W (week) designator cannot be combined with other date components in strict ISO 8601, though many implementations allow it.
Why are month and year durations considered ambiguous in ISO 8601?
Months and years in ISO 8601 durations are ambiguous because they do not correspond to fixed numbers of seconds. A month can be 28, 29, 30, or 31 days depending on which month and whether it is a leap year. Similarly, a year is 365 or 366 days. This means P1M starting from January 31st might end on February 28th or March 3rd depending on interpretation. For this reason, many programming libraries use a convention of 30 days per month and 365 days per year when converting to absolute time, but this is only an approximation. When precision matters, such as in scientific computing, financial calculations, or scheduling, it is best to use durations in days, hours, minutes, and seconds rather than months and years to avoid ambiguity.
How is ISO 8601 duration used in web development and APIs?
ISO 8601 durations appear extensively in modern web development. In HTML and schema markup, the datetime attribute on time elements uses this format for accessibility and search engine optimization. Google structured data for recipes, videos, events, and courses all require ISO 8601 durations to specify cooking times, video lengths, event durations, and course completion times. REST APIs commonly use this format for timeout values, retry intervals, cache expiration, subscription periods, and scheduling endpoints. YouTube and other video platforms use ISO 8601 durations in their API responses to represent video lengths. In JavaScript, libraries like Luxon and date-fns support parsing and formatting ISO 8601 durations natively, making it the de facto standard for duration representation in web applications.
How do different programming languages handle ISO 8601 durations?
Most modern programming languages have built-in or library support for ISO 8601 durations. Java introduced the Duration and Period classes in java.time (Java 8+), where Duration handles time-based amounts and Period handles date-based amounts. Python has the isodate library for parsing ISO 8601 durations, and the timedelta class for representing absolute durations. In JavaScript, the Temporal API proposal includes Duration support, and libraries like Luxon provide Duration.fromISO() for parsing. C-sharp has XmlConvert.ToTimeSpan() for parsing ISO 8601 durations. Go uses the standard time.ParseDuration with a slightly different syntax but third-party packages handle ISO 8601. PHP has the DateInterval class that directly accepts ISO 8601 duration strings via its constructor. Understanding these implementations helps developers work with duration data across polyglot microservice architectures.
What is ISO 8601 and why should I use it for dates?
ISO 8601 formats dates as YYYY-MM-DD (e.g., 2025-03-15), eliminating ambiguity between US (MM/DD/YYYY) and European (DD/MM/YYYY) formats. It sorts chronologically as text, is internationally recognized, and is the standard for data exchange and APIs.