{"openapi":"3.1.0","info":{"title":"Relative Time & Locale Date API","version":"1.0.0","description":"Humanise timestamps and format dates for any locale and timezone using full ICU. The relative endpoint turns an instant into a localised relative phrase against now (or a given reference time) — \"3 hours ago\", \"vor 3 Stunden\", \"in 2 days\", \"il y a 5 minutes\" — automatically choosing the best unit from seconds to years. The format endpoint renders a localised date/time string (e.g. \"mardi 2 juin 2026 à 15:30\" or \"2026年6月2日 22:30:00\"), honouring the locale (BCP 47), a named IANA timezone, the chosen date and time styles (full/long/medium/short) and 12/24-hour preference, and returns a parts breakdown for custom displays. Pass dates as ISO 8601 or unix timestamps. Everything is computed locally with no network calls. Ideal for internationalised UIs, activity feeds, notifications, comments and dashboards. A relative-time and locale date formatter — distinct from current-time-in-a-timezone (time), the UTC parse/token toolkit (datetime) and number/currency formatting (numberformat). No upstream key, no cache.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/datelocale-api","description":"oanor gateway"}],"tags":[{"name":"Relative Time"},{"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/format":{"get":{"operationId":"get_v1_format","tags":["Relative Time"],"summary":"Locale + timezone date display","description":"","parameters":[{"name":"date","in":"query","required":true,"description":"The date (ISO/unix)","schema":{"type":"string"},"example":"2026-06-02T13:30:00Z"},{"name":"locale","in":"query","required":false,"description":"BCP 47 locale","schema":{"type":"string"},"example":"fr-FR"},{"name":"dateStyle","in":"query","required":false,"description":"full, long, medium, short","schema":{"type":"string"},"example":"full"},{"name":"timeStyle","in":"query","required":false,"description":"full, long, medium, short","schema":{"type":"string"},"example":"short"},{"name":"timezone","in":"query","required":false,"description":"IANA timezone","schema":{"type":"string"},"example":"Europe/Paris"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"date":"2026-06-02T13:30:00.000Z","parts":[{"type":"weekday","value":"mardi"},{"type":"literal","value":" "},{"type":"day","value":"2"},{"type":"literal","value":" "},{"type":"month","value":"juin"},{"type":"literal","value":" "},{"type":"year","value":"2026"},{"type":"literal","value":" à "},{"type":"hour","value":"15"},{"type":"literal","value":":"},{"type":"minute","value":"30"}],"locale":"fr-FR","timezone":"Europe/Paris","formatted":"mardi 2 juin 2026 à 15:30"},"meta":{"timestamp":"2026-06-01T23:40:41.488Z","request_id":"abe285cf-37ee-47e6-b1ed-f6d05ea04d6c"},"status":"ok","message":"Date formatted","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/relative":{"get":{"operationId":"get_v1_relative","tags":["Relative Time"],"summary":"Humanised relative time","description":"","parameters":[{"name":"from","in":"query","required":true,"description":"The event time (ISO/unix)","schema":{"type":"string"},"example":"2026-06-02T10:00:00Z"},{"name":"to","in":"query","required":false,"description":"Reference time (default now)","schema":{"type":"string"},"example":"2026-06-02T13:00:00Z"},{"name":"locale","in":"query","required":false,"description":"BCP 47 locale","schema":{"type":"string"},"example":"de"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"to":"2026-06-02T13:00:00.000Z","from":"2026-06-02T10:00:00.000Z","unit":"hour","value":-3,"locale":"de","is_past":true,"relative":"vor 3 Stunden","seconds_diff":-10800},"meta":{"timestamp":"2026-06-01T23:40:41.586Z","request_id":"f75ff6a7-7af4-4dd0-8822-0bf8db31c91a"},"status":"ok","message":"Relative time computed","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":"Styles & locales","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Humanise timestamps and format dates for any locale and timezone with full ICU. /v1/relative?from=2026-06-02T10:00:00Z&locale=de turns an instant into a localised relative phrase against now (or a given 'to') — 'vor 3 Stunden', '3 hours ago', 'in 2 days', 'il y a 5 minutes' — automatically choosing the best unit (second to year). /v1/format?date=...&locale=fr-FR&dateStyle=full&timeStyle=short&timezone=Europe/Paris renders a localised date/time string (e.g. 'mardi 2 juin 2026 à 15:30') with a parts breakdown, honouring the locale, named IANA timezone and 12/24-hour preference. Pass dates as ISO 8601 or unix timestamps. Everything is computed locally with no network calls. Ideal for internationalised UIs, feeds, notifications, comments and dashboards. A relative-time and locale date formatter — distinct from current-time-in-a-timezone (time), the UTC parse/token toolkit (datetime) and number/currency formatting (numberformat). No key, no cache.","styles":["full","long","medium","short"],"endpoints":["/v1/relative","/v1/format","/v1/meta"],"example_locales":["en-US","de-DE","fr-FR","es-ES","ja-JP","ar-EG","pt-BR","zh-CN"]},"meta":{"timestamp":"2026-06-01T23:40:41.683Z","request_id":"004535e9-df95-40ed-a71b-a35c497d4b1a"},"status":"ok","message":"Meta retrieved","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":2060,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":605,"monthly_call_quota":39000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2000,"monthly_call_quota":208000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5220,"monthly_call_quota":800000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/datelocale-api"}