{"openapi":"3.1.0","info":{"title":"Duration API","version":"1.0.0","description":"Work with ISO-8601 durations — the PnYnMnDTnHnMnS strings (P3Y6M4DT12H30M5S, PT1H30M) used across calendars, scheduling, video metadata, billing periods and APIs. Parse a duration into its components and a total in seconds and milliseconds; format a number of seconds (or individual year/month/week/day/hour/minute/second fields) back into a canonical ISO-8601 string; humanise any duration into readable text (\"1 hour and 30 minutes\"); and measure the exact duration between two instants (ISO timestamps or unix epochs) as both an ISO-8601 string and a precise second count. Years and months use documented calendar averages and are clearly flagged as approximate. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. Distinct from date/time parsing and relative-time (\"3 hours ago\") formatting.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/duration-api","description":"oanor gateway"}],"tags":[{"name":"Duration"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/between":{"get":{"operationId":"get_v1_between","tags":["Duration"],"summary":"Duration between two instants","description":"","parameters":[{"name":"start","in":"query","required":true,"description":"ISO date or unix ts","schema":{"type":"string"},"example":"2026-01-01T00:00:00Z"},{"name":"end","in":"query","required":true,"description":"ISO date or unix ts","schema":{"type":"string"},"example":"2026-01-02T03:04:05Z"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"end":"2026-01-02T03:04:05.000Z","start":"2026-01-01T00:00:00.000Z","iso8601":"P1DT3H4M5S","direction":"end after start","humanized":"1 day, 3 hours, 4 minutes and 5 seconds","components":{"days":1,"hours":3,"weeks":0,"years":0,"months":0,"minutes":4,"seconds":5},"total_seconds":97445,"total_milliseconds":97445000},"meta":{"timestamp":"2026-06-02T16:51:50.004Z","request_id":"d61a2d5d-14cb-4610-813d-ff77c7b9d490"},"status":"ok","message":"Duration between two instants","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/format":{"get":{"operationId":"get_v1_format","tags":["Duration"],"summary":"Format seconds/components to ISO-8601","description":"","parameters":[{"name":"seconds","in":"query","required":false,"description":"Total seconds","schema":{"type":"string"},"example":"5400"},{"name":"hours","in":"query","required":false,"description":"Hours field","schema":{"type":"string"}},{"name":"minutes","in":"query","required":false,"description":"Minutes field","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Days field","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"iso8601":"PT1H30M","humanized":"1 hour and 30 minutes","components":{"days":0,"hours":1,"weeks":0,"years":0,"months":0,"minutes":30,"seconds":0},"total_seconds":5400},"meta":{"timestamp":"2026-06-02T16:51:50.116Z","request_id":"7e6afd5a-3ab8-4e4e-8170-67b6078439a5"},"status":"ok","message":"Format seconds/components to ISO-8601","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/humanize":{"get":{"operationId":"get_v1_humanize","tags":["Duration"],"summary":"Humanize a duration","description":"","parameters":[{"name":"duration","in":"query","required":false,"description":"ISO-8601 duration","schema":{"type":"string"},"example":"P1DT2H"},{"name":"seconds","in":"query","required":false,"description":"Total seconds (alternative)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"input":"P1DT2H","humanized":"1 day and 2 hours","total_seconds":93600},"meta":{"timestamp":"2026-06-02T16:51:50.222Z","request_id":"42d64a0e-d7a5-40ed-8969-8facd9e58e38"},"status":"ok","message":"Humanize a duration","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/parse":{"get":{"operationId":"get_v1_parse","tags":["Duration"],"summary":"Parse an ISO-8601 duration","description":"","parameters":[{"name":"duration","in":"query","required":true,"description":"ISO-8601 duration","schema":{"type":"string"},"example":"P3Y6M4DT12H30M5S"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"total_seconds uses calendar averages (1 month = 30.436875 days, 1 year = 365.2425 days)","sign":"+","input":"P3Y6M4DT12H30M5S","humanized":"3 years, 6 months, 4 days, 12 hours, 30 minutes and 5 seconds","components":{"days":4,"hours":12,"weeks":0,"years":3,"months":6,"minutes":30,"seconds":5},"approximate":true,"total_seconds":110839937,"total_milliseconds":110839937000},"meta":{"timestamp":"2026-06-02T16:51:50.314Z","request_id":"d309e54b-1578-497a-8008-bca2f73538fc"},"status":"ok","message":"Parse an ISO-8601 duration","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"name":"Duration API","notes":"Years and months use calendar averages for total_seconds (flagged via `approximate`); /between is exact from the real timestamps.","version":"v1","endpoints":[{"path":"/v1/parse","params":{"duration":"ISO-8601 duration, e.g. P3Y6M4DT12H30M5S (required)"},"returns":"components, total_seconds, humanized"},{"path":"/v1/format","params":{"seconds":"number, OR","years_months_weeks_days_hours_minutes_seconds":"individual fields"},"returns":"ISO-8601 string + components"},{"path":"/v1/humanize","params":{"duration":"ISO-8601 string, OR seconds: number"},"returns":"human-readable text"},{"path":"/v1/between","params":{"end":"ISO date or unix ts (required)","start":"ISO date or unix ts (required)"},"returns":"exact duration between two instants"},{"path":"/v1/meta","params":[],"returns":"this document"}],"description":"Parse, format, humanize and measure ISO-8601 durations (PnYnMnDTnHnMnS). Pure local, no key."},"meta":{"timestamp":"2026-06-02T16:51:50.396Z","request_id":"23c4d99e-63d7-4763-a61a-03ba51fa6415"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":1060,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":260,"monthly_call_quota":9100,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2200,"monthly_call_quota":140000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5800,"monthly_call_quota":720000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/duration-api"}