Skip to main content

Locale Number and Date Format API

REAL DATA

How any BCP 47 locale formats numbers, currency, dates and lists — separators, digit grouping, currency position, hour cycle and first day of week.

Authoritative reference data or standards computation

Base URL
/api/locale-formats
Category
Text & Content
Capabilities
6 routes
Last updated
July 29, 2026
Data source

GET /api/locale-formats/number Format a number for a locale and echo the resolved options

Runs Intl.NumberFormat with exactly the options you pass. Unknown numbering systems and unsanctioned units are rejected rather than silently ignored.

Live requestRuns against the public API
No key required
GET/api/locale-formats/number?locale=de-DE&value=1234567.89

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Finite number to format, bounded to ±1000000000000000 so every integral input stays exactly representable.

decimal is a plain number; percent multiplies the value by 100 and adds the locale's percent sign (which Turkish puts in front of the digits); unit appends a measurement unit and additionally requires 'unit'.

Sanctioned ECMA-402 unit identifier for style=unit — a single unit such as kilometer or byte, or one 'x-per-y' combination such as kilometer-per-hour. Ignored with a warning for any other style.

standard is plain positional notation; compact abbreviates (1.2M, 12 लाख); scientific and engineering use exponent notation.

Minimum digits after the decimal separator. Omitted by default so the locale's own default applies. Must be no greater than maximumFractionDigits when both are supplied.

Maximum digits after the decimal separator, applied with ECMA-402's half-expand rounding. Omitted by default so the locale's own default applies.

Decimal numbering system for the digits — latn, arab, deva, beng, thai and the other simple systems this runtime exposes. Algorithmic and unknown systems are a 400 rather than a silent fallback.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/number?locale=de-DE&value=1234567.89"
const res = await fetch("https://randomapi.dev/api/locale-formats/number?locale=de-DE&value=1234567.89");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/number?locale=de-DE&value=1234567.89").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/number?locale=de-DE&value=1234567.89"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 8
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
value float required

Finite number to format, bounded to ±1000000000000000 so every integral input stays exactly representable.

allowed: -1000000000000000 – 1000000000000000
example: value=1234567.89
style enum

decimal is a plain number; percent multiplies the value by 100 and adds the locale's percent sign (which Turkish puts in front of the digits); unit appends a measurement unit and additionally requires 'unit'.

default: decimal
allowed: decimal | percent | unit
example: style=percent
unit string

Sanctioned ECMA-402 unit identifier for style=unit — a single unit such as kilometer or byte, or one 'x-per-y' combination such as kilometer-per-hour. Ignored with a warning for any other style.

allowed: 3 – 64
example: unit=kilometer-per-hour
notation enum

standard is plain positional notation; compact abbreviates (1.2M, 12 लाख); scientific and engineering use exponent notation.

default: standard
allowed: standard | compact | scientific | engineering
example: notation=compact
minimumFractionDigits int

Minimum digits after the decimal separator. Omitted by default so the locale's own default applies. Must be no greater than maximumFractionDigits when both are supplied.

allowed: 0 – 20
example: minimumFractionDigits=2
maximumFractionDigits int

Maximum digits after the decimal separator, applied with ECMA-402's half-expand rounding. Omitted by default so the locale's own default applies.

allowed: 0 – 20
example: maximumFractionDigits=2
numberingSystem string

Decimal numbering system for the digits — latn, arab, deva, beng, thai and the other simple systems this runtime exposes. Algorithmic and unknown systems are a 400 rather than a silent fallback.

allowed: 3 – 8
example: numberingSystem=arab
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=value,formatted
exclude list

Return all fields except these (comma-separated).

example: exclude=resolvedOptions
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 9
value float

The numeric input, echoed back.

example: 1234567.89

formatted string

The formatted number as this runtime's CLDR data renders it.

example: 1.234.567,89

locale string

Locale actually resolved by Intl.NumberFormat, which may be a parent of the requested tag.

example: de-DE

numberingSystem string

Numbering system actually used for the digits.

example: latn

style string

Resolved style: decimal, percent or unit.

example: decimal

notation string

Resolved notation: standard, compact, scientific or engineering.

example: standard

unit string nullable

Resolved unit identifier, or null for any style other than unit.

example: null

parts object[]

The runtime's formatToParts output: each substring the formatter produced, tagged with the ECMA-402 part type it came from. This is what lets you locate the separator, symbol or field inside `formatted` instead of parsing it.

example: [{"type":"integer","value":"1"},{"type":"group","value":"."},{"type":"integer","value":"234"}]

resolvedOptions object

The formatter's complete ECMA-402 resolvedOptions() object, exactly as this runtime reports it — the resolved locale, numbering system and every option that was actually applied.

example: {"locale":"de-DE","numberingSystem":"latn","style":"decimal","minimumIntegerDigits":1,"minimumFractionDigits":0,"maximumFractionDigits":3,"useGrouping":"auto","notation":"standard","signDisplay":"auto"}

Documented examples

Build-generated requests and complete responses 6
German thousands separators
GET /api/locale-formats/number?locale=de-DE&value=1234567.89 
{
  "data": {
    "value": 1234567.89,
    "formatted": "1.234.567,89",
    "locale": "de-DE",
    "numberingSystem": "latn",
    "style": "decimal",
    "notation": "standard",
    "unit": null,
    "parts": [
      {
        "type": "integer",
        "value": "1"
      },
      {
        "type": "group",
        "value": "."
      },
      {
        "type": "integer",
        "value": "234"
      },
      {
        "type": "group",
        "value": "."
      },
      {
        "type": "integer",
        "value": "567"
      },
      {
        "type": "decimal",
        "value": ","
      },
      {
        "type": "fraction",
        "value": "89"
      }
    ],
    "resolvedOptions": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Indian lakh grouping
GET /api/locale-formats/number?locale=hi-IN&value=1234567.89 
{
  "data": {
    "value": 1234567.89,
    "formatted": "12,34,567.89",
    "locale": "hi-IN",
    "numberingSystem": "latn",
    "style": "decimal",
    "notation": "standard",
    "unit": null,
    "parts": [
      {
        "type": "integer",
        "value": "12"
      },
      {
        "type": "group",
        "value": ","
      },
      {
        "type": "integer",
        "value": "34"
      },
      {
        "type": "group",
        "value": ","
      },
      {
        "type": "integer",
        "value": "567"
      },
      {
        "type": "decimal",
        "value": "."
      },
      {
        "type": "fraction",
        "value": "89"
      }
    ],
    "resolvedOptions": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Compact notation in Japanese
GET /api/locale-formats/number?locale=ja-JP&value=1234567.89&notation=compact 
{
  "data": {
    "value": 1234567.89,
    "formatted": "123万",
    "locale": "ja-JP",
    "numberingSystem": "latn",
    "style": "decimal",
    "notation": "compact",
    "unit": null,
    "parts": [
      {
        "type": "integer",
        "value": "123"
      },
      {
        "type": "compact",
        "value": "万"
      }
    ],
    "resolvedOptions": {
      "locale": "ja-JP",
      "numberingSystem": "latn",
      "style": "decimal",
      "minimumIntegerDigits": 1,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 0,
      "minimumSignificantDigits": 1,
      "maximumSignificantDigits": 2,
      "useGrouping": "min2",
      "notation": "compact",
      "compactDisplay": "short",
      "signDisplay": "auto",
      "roundingIncrement": 1,
      "roundingMode": "halfExpand",
      "roundingPriority": "morePrecision",
      "trailingZeroDisplay": "auto"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Kilometres per hour as a unit
GET /api/locale-formats/number?locale=fr-FR&value=88&style=unit&unit=kilometer-per-hour 
{
  "data": {
    "value": 88,
    "formatted": "88 km/h",
    "locale": "fr-FR",
    "numberingSystem": "latn",
    "style": "unit",
    "notation": "standard",
    "unit": "kilometer-per-hour",
    "parts": [
      {
        "type": "integer",
        "value": "88"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "unit",
        "value": "km/h"
      }
    ],
    "resolvedOptions": {
      "locale": "fr-FR",
      "numberingSystem": "latn",
      "style": "unit",
      "unit": "kilometer-per-hour",
      "unitDisplay": "short",
      "minimumIntegerDigits": 1,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 3,
      "useGrouping": "auto",
      "notation": "standard",
      "signDisplay": "auto",
      "roundingIncrement": 1,
      "roundingMode": "halfExpand",
      "roundingPriority": "auto",
      "trailingZeroDisplay": "auto"
    }
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Percent with Arabic-Indic digits
GET /api/locale-formats/number?locale=en-US&value=0.256&style=percent&numberingSystem=arab 
{
  "data": {
    "value": 0.256,
    "formatted": "٢٦٪؜",
    "locale": "en-US",
    "numberingSystem": "arab",
    "style": "percent",
    "notation": "standard",
    "unit": null,
    "parts": [
      {
        "type": "integer",
        "value": "٢٦"
      },
      {
        "type": "percentSign",
        "value": "٪"
      },
      {
        "type": "literal",
        "value": "؜"
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "numberingSystem": "arab",
      "style": "percent",
      "minimumIntegerDigits": 1,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 0,
      "useGrouping": "auto",
      "notation": "standard",
      "signDisplay": "auto",
      "roundingIncrement": 1,
      "roundingMode": "halfExpand",
      "roundingPriority": "auto",
      "trailingZeroDisplay": "auto"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Spanish leaves four digits ungrouped
GET /api/locale-formats/number?locale=es-ES&value=1234 
{
  "data": {
    "value": 1234,
    "formatted": "1234",
    "locale": "es-ES",
    "numberingSystem": "latn",
    "style": "decimal",
    "notation": "standard",
    "unit": null,
    "parts": [
      {
        "type": "integer",
        "value": "1234"
      }
    ],
    "resolvedOptions": {
      "locale": "es-ES",
      "numberingSystem": "latn",
      "style": "decimal",
      "minimumIntegerDigits": 1,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 3,
      "useGrouping": "auto",
      "notation": "standard",
      "signDisplay": "auto",
      "roundingIncrement": 1,
      "roundingMode": "halfExpand",
      "roundingPriority": "auto",
      "trailingZeroDisplay": "auto"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/number",
    "params": {
      "locale": "es-ES",
      "value": 1234,
      "style": "decimal",
      "notation": "standard"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/locale-formats/currency Format an amount in a currency, with symbol placement and fraction digits

Formats the amount you supply in the currency you name. It never converts between currencies and holds no exchange rates.

Live requestRuns against the public API
No key required
GET/api/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Finite amount to format, bounded to ±1000000000000000. Negative amounts show the locale's negative currency form.

Active ISO 4217 alphabetic code, case-insensitive, validated against the same table as /api/currencies. The currency's own CLDR fraction digits are applied (JPY 0, KWD 3).

symbol uses the locale's usual symbol; narrowSymbol drops any disambiguating prefix ($ instead of US$); code prints the ISO code; name prints the localized currency name, which many locales place after the digits even when they put the symbol in front.

accounting selects the locale's accounting negative form, which wraps negatives in parentheses in locales such as en-US; standard uses the ordinary minus form.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR"
const res = await fetch("https://randomapi.dev/api/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 5
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
amount float required

Finite amount to format, bounded to ±1000000000000000. Negative amounts show the locale's negative currency form.

allowed: -1000000000000000 – 1000000000000000
example: amount=1234.5
currency string required

Active ISO 4217 alphabetic code, case-insensitive, validated against the same table as /api/currencies. The currency's own CLDR fraction digits are applied (JPY 0, KWD 3).

allowed: 3 – 3
example: currency=EUR
currencyDisplay enum

symbol uses the locale's usual symbol; narrowSymbol drops any disambiguating prefix ($ instead of US$); code prints the ISO code; name prints the localized currency name, which many locales place after the digits even when they put the symbol in front.

default: symbol
allowed: symbol | narrowSymbol | code | name
example: currencyDisplay=name
currencySign enum

accounting selects the locale's accounting negative form, which wraps negatives in parentheses in locales such as en-US; standard uses the ordinary minus form.

default: standard
allowed: standard | accounting
example: currencySign=accounting
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=amount,currency
exclude list

Return all fields except these (comma-separated).

example: exclude=resolvedOptions
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 10
amount float

The amount supplied by the caller.

example: 1234.5

currency string

Canonical uppercase ISO 4217 code that was formatted.

example: EUR

formatted string

The formatted monetary string for this locale and currency.

example: 1.234,50 €

currencyText string nullable

Exact substring the runtime emitted for the currency part — a symbol, ISO code or localized name depending on currencyDisplay. Null if the runtime emitted no currency part.

example: €

currencyPosition string (prefix | suffix) nullable

Whether the currency part precedes or follows the digits for this locale AND this currencyDisplay. The symbol, narrowSymbol and code forms share the locale's one CLDR pattern, but the localized name form trails the digits in many locales whose symbol leads them (en-US: $1,234.56 but 1,234.56 US dollars). Null if the runtime emitted no currency part.

example: suffix

locale string

Locale actually resolved by Intl.NumberFormat.

example: de-DE

minimumFractionDigits integer

Resolved minimum fraction digits — ECMA-402 takes this from the currency's own CLDR minor-unit digit count, not from the locale.

example: 2

maximumFractionDigits integer

Resolved maximum fraction digits: 0 for JPY, 2 for EUR and USD, 3 for KWD and BHD.

example: 2

parts object[]

The runtime's formatToParts output: each substring the formatter produced, tagged with the ECMA-402 part type it came from. This is what lets you locate the separator, symbol or field inside `formatted` instead of parsing it.

example: [{"type":"integer","value":"1"},{"type":"group","value":"."},{"type":"integer","value":"234"}]

resolvedOptions object

The formatter's complete ECMA-402 resolvedOptions() object, exactly as this runtime reports it — the resolved locale, numbering system and every option that was actually applied.

example: {"locale":"de-DE","numberingSystem":"latn","style":"decimal","minimumIntegerDigits":1,"minimumFractionDigits":0,"maximumFractionDigits":3,"useGrouping":"auto","notation":"standard","signDisplay":"auto"}

Documented examples

Build-generated requests and complete responses 4
Euro suffix in Germany
GET /api/locale-formats/currency?locale=de-DE&amount=1234.5&currency=EUR 
{
  "data": {
    "amount": 1234.5,
    "currency": "EUR",
    "formatted": "1.234,50 €",
    "currencyText": "€",
    "currencyPosition": "suffix",
    "locale": "de-DE",
    "minimumFractionDigits": 2,
    "maximumFractionDigits": 2,
    "parts": [
      {
        "type": "integer",
        "value": "1"
      },
      {
        "type": "group",
        "value": "."
      },
      {
        "type": "integer",
        "value": "234"
      },
      {
        "type": "decimal",
        "value": ","
      },
      {
        "type": "fraction",
        "value": "50"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "currency",
        "value": "€"
      }
    ],
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Yen prefix with no decimals
GET /api/locale-formats/currency?locale=ja-JP&amount=1234.5&currency=JPY 
{
  "data": {
    "amount": 1234.5,
    "currency": "JPY",
    "formatted": "￥1,235",
    "currencyText": "￥",
    "currencyPosition": "prefix",
    "locale": "ja-JP",
    "minimumFractionDigits": 0,
    "maximumFractionDigits": 0,
    "parts": [
      {
        "type": "currency",
        "value": "￥"
      },
      {
        "type": "integer",
        "value": "1"
      },
      {
        "type": "group",
        "value": ","
      },
      {
        "type": "integer",
        "value": "235"
      }
    ],
    "resolvedOptions": {
      "locale": "ja-JP",
      "numberingSystem": "latn",
      "style": "currency",
      "currency": "JPY",
      "currencyDisplay": "symbol",
      "currencySign": "standard",
      "minimumIntegerDigits": 1,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 0,
      "useGrouping": "auto",
      "notation": "standard",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
US accounting negative
GET /api/locale-formats/currency?locale=en-US&amount=-1234.5&currency=USD&currencySign=accounting 
{
  "data": {
    "amount": -1234.5,
    "currency": "USD",
    "formatted": "($1,234.50)",
    "currencyText": "$",
    "currencyPosition": "prefix",
    "locale": "en-US",
    "minimumFractionDigits": 2,
    "maximumFractionDigits": 2,
    "parts": [
      {
        "type": "literal",
        "value": "("
      },
      {
        "type": "currency",
        "value": "$"
      },
      {
        "type": "integer",
        "value": "1"
      },
      {
        "type": "group",
        "value": ","
      },
      {
        "type": "integer",
        "value": "234"
      },
      {
        "type": "decimal",
        "value": "."
      },
      {
        "type": "fraction",
        "value": "50"
      },
      {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Kuwaiti dinar keeps three decimals
GET /api/locale-formats/currency?locale=en-US&amount=1234.5&currency=KWD&currencyDisplay=code 
{
  "data": {
    "amount": 1234.5,
    "currency": "KWD",
    "formatted": "KWD 1,234.500",
    "currencyText": "KWD",
    "currencyPosition": "prefix",
    "locale": "en-US",
    "minimumFractionDigits": 3,
    "maximumFractionDigits": 3,
    "parts": [
      {
        "type": "currency",
        "value": "KWD"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "integer",
        "value": "1"
      },
      {
        "type": "group",
        "value": ","
      },
      {
        "type": "integer",
        "value": "234"
      },
      {
        "type": "decimal",
        "value": "."
      },
      {
        "type": "fraction",
        "value": "500"
      }
    ],
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/locale-formats/date-time Format an instant for a locale, time zone and calendar

Formats an absolute instant with Intl.DateTimeFormat. Omitting both dateStyle and timeStyle yields the locale's plain numeric date; omitting 'at' formats the current instant.

Live requestRuns against the public API
No key required
GET/api/locale-formats/date-time?locale=de-DE&at=2026-01-15T12%3A34%3A56Z&dateStyle=full&timeStyle=full

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Absolute instant: YYYY-MM-DD (UTC midnight) or RFC3339 with Z or an explicit offset. Defaults to the current instant, which is echoed in meta.params.

CLDR date length. Omit both dateStyle and timeStyle to get the locale's default numeric date with no time.

CLDR time length. full and long include the time-zone name; medium includes seconds; short is hours and minutes.

IANA time zone id, case-insensitive (Europe/Copenhagen, asia/tokyo, UTC). Unknown ids are a 400; browse them at /api/timezones.

CLDR calendar identifier such as gregory, buddhist, hebrew, islamic-umalqura, japanese or iso8601. Defaults to the locale's own calendar; unknown identifiers are a 400.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/date-time?locale=de-DE&at=2026-01-15T12:34:56Z&dateStyle=full&timeStyle=full"
const res = await fetch("https://randomapi.dev/api/locale-formats/date-time?locale=de-DE&at=2026-01-15T12:34:56Z&dateStyle=full&timeStyle=full");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/date-time?locale=de-DE&at=2026-01-15T12:34:56Z&dateStyle=full&timeStyle=full").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/date-time?locale=de-DE&at=2026-01-15T12:34:56Z&dateStyle=full&timeStyle=full"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 6
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
at date

Absolute instant: YYYY-MM-DD (UTC midnight) or RFC3339 with Z or an explicit offset. Defaults to the current instant, which is echoed in meta.params.

example: at=2026-01-15T12:34:56Z
dateStyle enum

CLDR date length. Omit both dateStyle and timeStyle to get the locale's default numeric date with no time.

allowed: full | long | medium | short
example: dateStyle=full
timeStyle enum

CLDR time length. full and long include the time-zone name; medium includes seconds; short is hours and minutes.

allowed: full | long | medium | short
example: timeStyle=short
timeZone string

IANA time zone id, case-insensitive (Europe/Copenhagen, asia/tokyo, UTC). Unknown ids are a 400; browse them at /api/timezones.

default: UTC
allowed: 2 – 64
example: timeZone=Europe/Copenhagen
calendar string

CLDR calendar identifier such as gregory, buddhist, hebrew, islamic-umalqura, japanese or iso8601. Defaults to the locale's own calendar; unknown identifiers are a 400.

allowed: 3 – 32
example: calendar=buddhist
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=at,formatted
exclude list

Return all fields except these (comma-separated).

example: exclude=resolvedOptions
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 9
at string (ISO 8601 UTC)

The absolute instant that was formatted, in canonical UTC.

example: 2026-01-15T12:34:56.000Z

formatted string

The formatted date and/or time for this locale, zone and calendar.

example: Donnerstag, 15. Januar 2026 um 12:34:56 Koordinierte Weltzeit

locale string

Locale actually resolved by Intl.DateTimeFormat.

example: de-DE

timeZone string

Canonical IANA time zone the instant was rendered in.

example: UTC

calendar string

Calendar actually used — the locale default unless 'calendar' was supplied.

example: gregory

numberingSystem string

Numbering system used for the numeric fields.

example: latn

hourCycle string nullable

Resolved hour cycle (h11, h12, h23, h24). Null when the output contains no hour field, for example a date-only request.

example: h23

parts object[]

The runtime's formatToParts output: each substring the formatter produced, tagged with the ECMA-402 part type it came from. This is what lets you locate the separator, symbol or field inside `formatted` instead of parsing it.

example: [{"type":"integer","value":"1"},{"type":"group","value":"."},{"type":"integer","value":"234"}]

resolvedOptions object

The formatter's complete ECMA-402 resolvedOptions() object, exactly as this runtime reports it — the resolved locale, numbering system and every option that was actually applied.

example: {"locale":"de-DE","numberingSystem":"latn","style":"decimal","minimumIntegerDigits":1,"minimumFractionDigits":0,"maximumFractionDigits":3,"useGrouping":"auto","notation":"standard","signDisplay":"auto"}

Documented examples

Build-generated requests and complete responses 5
German full date and time
GET /api/locale-formats/date-time?locale=de-DE&at=2026-01-15T12:34:56Z&dateStyle=full&timeStyle=full 
{
  "data": {
    "at": "2026-01-15T12:34:56.000Z",
    "formatted": "Donnerstag, 15. Januar 2026 um 12:34:56 Koordinierte Weltzeit",
    "locale": "de-DE",
    "timeZone": "UTC",
    "calendar": "gregory",
    "numberingSystem": "latn",
    "hourCycle": "h23",
    "parts": [
      {
        "type": "weekday",
        "value": "Donnerstag"
      },
      {
        "type": "literal",
        "value": ", "
      },
      {
        "type": "day",
        "value": "15"
      },
      {
        "type": "literal",
        "value": ". "
      },
      {
        "type": "month",
        "value": "Januar"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "year",
        "value": "2026"
      },
      {
        "type": "literal",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
US short numeric date
GET /api/locale-formats/date-time?locale=en-US&at=2026-01-15T12:34:56Z&dateStyle=short 
{
  "data": {
    "at": "2026-01-15T12:34:56.000Z",
    "formatted": "1/15/26",
    "locale": "en-US",
    "timeZone": "UTC",
    "calendar": "gregory",
    "numberingSystem": "latn",
    "hourCycle": null,
    "parts": [
      {
        "type": "month",
        "value": "1"
      },
      {
        "type": "literal",
        "value": "/"
      },
      {
        "type": "day",
        "value": "15"
      },
      {
        "type": "literal",
        "value": "/"
      },
      {
        "type": "year",
        "value": "26"
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "calendar": "gregory",
      "numberingSystem": "latn",
      "timeZone": "UTC",
      "dateStyle": "short"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Tokyo wall clock, medium length
GET /api/locale-formats/date-time?locale=ja-JP&at=2026-01-15T12:34:56Z&dateStyle=medium&timeStyle=medium&timeZone=Asia/Tokyo 
{
  "data": {
    "at": "2026-01-15T12:34:56.000Z",
    "formatted": "2026/01/15 21:34:56",
    "locale": "ja-JP",
    "timeZone": "Asia/Tokyo",
    "calendar": "gregory",
    "numberingSystem": "latn",
    "hourCycle": "h23",
    "parts": [
      {
        "type": "year",
        "value": "2026"
      },
      {
        "type": "literal",
        "value": "/"
      },
      {
        "type": "month",
        "value": "01"
      },
      {
        "type": "literal",
        "value": "/"
      },
      {
        "type": "day",
        "value": "15"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "hour",
        "value": "21"
      },
      {
        "type": "literal",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Thai Buddhist calendar year
GET /api/locale-formats/date-time?locale=th-TH&at=2026-01-15T12:34:56Z&dateStyle=long 
{
  "data": {
    "at": "2026-01-15T12:34:56.000Z",
    "formatted": "15 มกราคม 2569",
    "locale": "th-TH",
    "timeZone": "UTC",
    "calendar": "buddhist",
    "numberingSystem": "latn",
    "hourCycle": null,
    "parts": [
      {
        "type": "day",
        "value": "15"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "month",
        "value": "มกราคม"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "year",
        "value": "2569"
      }
    ],
    "resolvedOptions": {
      "locale": "th-TH",
      "calendar": "buddhist",
      "numberingSystem": "latn",
      "timeZone": "UTC",
      "dateStyle": "long"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Hebrew calendar for an English locale
GET /api/locale-formats/date-time?locale=en-US&at=2026-01-15T12:34:56Z&dateStyle=long&calendar=hebrew 
{
  "data": {
    "at": "2026-01-15T12:34:56.000Z",
    "formatted": "26 Tevet 5786",
    "locale": "en-US",
    "timeZone": "UTC",
    "calendar": "hebrew",
    "numberingSystem": "latn",
    "hourCycle": null,
    "parts": [
      {
        "type": "day",
        "value": "26"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "month",
        "value": "Tevet"
      },
      {
        "type": "literal",
        "value": " "
      },
      {
        "type": "year",
        "value": "5786"
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "calendar": "hebrew",
      "numberingSystem": "latn",
      "timeZone": "UTC",
      "dateStyle": "long"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/locale-formats/patterns Separators, grouping, currency position, hour cycle and week start for one locale

Every value is derived from the runtime's own formatToParts output and Intl.Locale info accessors — nothing is hardcoded. A locale the runtime has no data for is an explicit 404.

Live requestRuns against the public API
No key required
GET/api/locale-formats/patterns?locale=de-DE

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/patterns?locale=de-DE"
const res = await fetch("https://randomapi.dev/api/locale-formats/patterns?locale=de-DE");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/patterns?locale=de-DE").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/patterns?locale=de-DE"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=locale,resolvedLocale
exclude list

Return all fields except these (comma-separated).

example: exclude=textDirection
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 20
locale string

Canonical form of the requested BCP 47 tag.

example: de-DE

resolvedLocale string

Locale Intl.NumberFormat actually resolved to, which may be a parent of the requested tag.

example: de-DE

decimalSeparator string nullable

Character(s) separating the integer and fraction parts, from formatToParts of 1234567890.123.

example: ,

groupSeparator string nullable

Character(s) between digit groups, or null when this locale does not group this magnitude. May be a narrow no-break space.

example: .

groupingPattern string nullable

Primary and secondary group sizes as 'primary;secondary' — 3;3 for German, 3;2 for the Indian lakh–crore style. It says how digits are chunked once grouping applies; minimumGroupingDigits says at which magnitude it starts. Null when the locale does not group.

example: 3;3

minimumGroupingDigits integer nullable

CLDR's minimumGroupingDigits: how many digits must precede the first group separator before this locale groups at all. 1 in most locales, but 2 in es, it, pl, hu and others — they write 1234 with no separator and only group from 12345 up — so grouping by pattern alone over-groups them. Null whenever groupingPattern is null.

example: 1

percentSign string nullable

Percent sign this locale uses, from a percent-styled formatToParts.

example: %

minusSign string nullable

Minus sign this locale uses. Several Nordic and Baltic locales (sv-SE, fi-FI, nb-NO, lt-LT) use U+2212 rather than an ASCII hyphen-minus.

example: -

plusSign string nullable

Plus sign this locale uses, from a format with signDisplay 'always'.

example: +

defaultNumberingSystem string

Numbering system Intl.NumberFormat resolves for this locale (latn, arab, deva …).

example: latn

currencyPosition string (prefix | suffix) nullable

Whether the currency symbol precedes or follows the digits, from formatting 1234.56 USD with currencyDisplay 'symbol'. CLDR keeps one currency pattern per locale, so this does not depend on the currency code — but it does depend on currencyDisplay: the localized 'name' form trails the digits in many locales that put the symbol in front. Ask /currency for that.

example: suffix

currencySpacing string nullable

Exact literal between the currency symbol and the adjacent digits for USD — often a no-break space (the example here is U+00A0), empty when they are adjacent. Unlike the position, this CAN differ for a currency whose symbol is alphabetic, so use /currency for a specific code.

example:  

accountingNegativeForm string (parentheses | minusSign) nullable

How this locale writes a negative accounting amount: 'parentheses' for en-US ($1,234.56 in brackets) or 'minusSign' for de-DE. Both are read out of formatToParts, allowing for the bidi control characters ar and fa glue onto the bracket. Null only if a locale emits neither form — every locale checked in this runtime reports one of the two.

example: minusSign

hourCycle string nullable

Resolved hour cycle for an hour-only format: h23/h24 mean a 24-hour clock, h11/h12 a 12-hour clock.

example: h23

calendar string

Default calendar for this locale — gregory for most, buddhist for th-TH.

example: gregory

shortDatePattern string nullable

LDML-style pattern derived from formatToParts of 2026-03-05T13:07:09.000Z under dateStyle 'short'. Null when the short date is not purely numeric.

example: dd.MM.yy

firstDayOfWeek integer (1-7) nullable

First day of the week, ISO numbering (1 = Monday … 7 = Sunday), from Intl.Locale getWeekInfo. Null when the runtime does not implement it.

example: 1

firstDayOfWeekName string nullable

English name of firstDayOfWeek, for readability. Null whenever firstDayOfWeek is null.

example: Monday

weekendDays integer[] nullable

Weekend days in the same ISO numbering — [6,7] in most of Europe, [5,6] in much of the Arab world. Null when getWeekInfo is unavailable.

example: [6,7]

textDirection string (ltr | rtl) nullable

Text direction from Intl.Locale getTextInfo. Null when the runtime does not implement it.

example: ltr

Documented examples

Build-generated requests and complete responses 5
How Germany formats numbers and dates
GET /api/locale-formats/patterns?locale=de-DE 
{
  "data": {
    "locale": "de-DE",
    "resolvedLocale": "de-DE",
    "decimalSeparator": ",",
    "groupSeparator": ".",
    "groupingPattern": "3;3",
    "minimumGroupingDigits": 1,
    "percentSign": "%",
    "minusSign": "-",
    "plusSign": "+",
    "defaultNumberingSystem": "latn",
    "currencyPosition": "suffix",
    "currencySpacing": " ",
    "accountingNegativeForm": "minusSign",
    "hourCycle": "h23",
    "calendar": "gregory",
    "shortDatePattern": "dd.MM.yy",
    "firstDayOfWeek": null,
    "firstDayOfWeekName": null,
    "weekendDays": null,
    "textDirection": null
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/patterns",
    "params": {
      "locale": "de-DE"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Indian 3;2 digit grouping
GET /api/locale-formats/patterns?locale=hi-IN 
{
  "data": {
    "locale": "hi-IN",
    "resolvedLocale": "hi-IN",
    "decimalSeparator": ".",
    "groupSeparator": ",",
    "groupingPattern": "3;2",
    "minimumGroupingDigits": 1,
    "percentSign": "%",
    "minusSign": "-",
    "plusSign": "+",
    "defaultNumberingSystem": "latn",
    "currencyPosition": "prefix",
    "currencySpacing": "",
    "accountingNegativeForm": "minusSign",
    "hourCycle": "h12",
    "calendar": "gregory",
    "shortDatePattern": "d/M/yy",
    "firstDayOfWeek": null,
    "firstDayOfWeekName": null,
    "weekendDays": null,
    "textDirection": null
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/patterns",
    "params": {
      "locale": "hi-IN"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
US week starts on Sunday
GET /api/locale-formats/patterns?locale=en-US 
{
  "data": {
    "locale": "en-US",
    "resolvedLocale": "en-US",
    "decimalSeparator": ".",
    "groupSeparator": ",",
    "groupingPattern": "3;3",
    "minimumGroupingDigits": 1,
    "percentSign": "%",
    "minusSign": "-",
    "plusSign": "+",
    "defaultNumberingSystem": "latn",
    "currencyPosition": "prefix",
    "currencySpacing": "",
    "accountingNegativeForm": "parentheses",
    "hourCycle": "h12",
    "calendar": "gregory",
    "shortDatePattern": "M/d/yy",
    "firstDayOfWeek": null,
    "firstDayOfWeekName": null,
    "weekendDays": null,
    "textDirection": null
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/patterns",
    "params": {
      "locale": "en-US"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
French narrow no-break group separator
GET /api/locale-formats/patterns?locale=fr-FR 
{
  "data": {
    "locale": "fr-FR",
    "resolvedLocale": "fr-FR",
    "decimalSeparator": ",",
    "groupSeparator": " ",
    "groupingPattern": "3;3",
    "minimumGroupingDigits": 1,
    "percentSign": "%",
    "minusSign": "-",
    "plusSign": "+",
    "defaultNumberingSystem": "latn",
    "currencyPosition": "suffix",
    "currencySpacing": " ",
    "accountingNegativeForm": "parentheses",
    "hourCycle": "h23",
    "calendar": "gregory",
    "shortDatePattern": "dd/MM/y",
    "firstDayOfWeek": null,
    "firstDayOfWeekName": null,
    "weekendDays": null,
    "textDirection": null
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/patterns",
    "params": {
      "locale": "fr-FR"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Spanish grouping threshold of two digits
GET /api/locale-formats/patterns?locale=es-ES 
{
  "data": {
    "locale": "es-ES",
    "resolvedLocale": "es-ES",
    "decimalSeparator": ",",
    "groupSeparator": ".",
    "groupingPattern": "3;3",
    "minimumGroupingDigits": 2,
    "percentSign": "%",
    "minusSign": "-",
    "plusSign": "+",
    "defaultNumberingSystem": "latn",
    "currencyPosition": "suffix",
    "currencySpacing": " ",
    "accountingNegativeForm": "minusSign",
    "hourCycle": "h23",
    "calendar": "gregory",
    "shortDatePattern": "d/M/yy",
    "firstDayOfWeek": null,
    "firstDayOfWeekName": null,
    "weekendDays": null,
    "textDirection": null
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/patterns",
    "params": {
      "locale": "es-ES"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/locale-formats/list Join items the way a locale writes lists

Intl.ListFormat conjunction, disjunction and unit output. English conjunctions keep the Oxford comma; Japanese uses ideographic commas.

Live requestRuns against the public API
No key required
GET/api/locale-formats/list?locale=en-US&items=red%2Cgreen%2Cblue

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Comma-separated list items, 1–20 entries of at most 100 characters each. Surrounding whitespace is trimmed and empty entries are dropped.

conjunction is an 'and' list, disjunction an 'or' list, unit a plain enumeration used for measurements.

Length of the connecting words. Many locales render all three identically; Danish disjunctions shorten 'eller' to 'el.'.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/list?locale=en-US&items=red,green,blue"
const res = await fetch("https://randomapi.dev/api/locale-formats/list?locale=en-US&items=red,green,blue");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/list?locale=en-US&items=red,green,blue").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/list?locale=en-US&items=red,green,blue"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 4
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
items list required

Comma-separated list items, 1–20 entries of at most 100 characters each. Surrounding whitespace is trimmed and empty entries are dropped.

example: items=red,green,blue
type enum

conjunction is an 'and' list, disjunction an 'or' list, unit a plain enumeration used for measurements.

default: conjunction
allowed: conjunction | disjunction | unit
example: type=disjunction
style enum

Length of the connecting words. Many locales render all three identically; Danish disjunctions shorten 'eller' to 'el.'.

default: long
allowed: long | short | narrow
example: style=short
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=items,formatted
exclude list

Return all fields except these (comma-separated).

example: exclude=resolvedOptions
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 7
items string[]

The parsed list items, in input order.

example: ["red","green","blue"]

formatted string

The joined list for this locale, type and style.

example: red, green, and blue

locale string

Locale actually resolved by Intl.ListFormat.

example: en-US

type string

Resolved list type: conjunction, disjunction or unit.

example: conjunction

style string

Resolved list style: long, short or narrow.

example: long

parts object[]

The runtime's formatToParts output: each substring the formatter produced, tagged with the ECMA-402 part type it came from. This is what lets you locate the separator, symbol or field inside `formatted` instead of parsing it.

example: [{"type":"integer","value":"1"},{"type":"group","value":"."},{"type":"integer","value":"234"}]

resolvedOptions object

The formatter's complete ECMA-402 resolvedOptions() object, exactly as this runtime reports it — the resolved locale, numbering system and every option that was actually applied.

example: {"locale":"de-DE","numberingSystem":"latn","style":"decimal","minimumIntegerDigits":1,"minimumFractionDigits":0,"maximumFractionDigits":3,"useGrouping":"auto","notation":"standard","signDisplay":"auto"}

Documented examples

Build-generated requests and complete responses 4
English Oxford-comma conjunction
GET /api/locale-formats/list?locale=en-US&items=red,green,blue 
{
  "data": {
    "items": [
      "red",
      "green",
      "blue"
    ],
    "formatted": "red, green, and blue",
    "locale": "en-US",
    "type": "conjunction",
    "style": "long",
    "parts": [
      {
        "type": "element",
        "value": "red"
      },
      {
        "type": "literal",
        "value": ", "
      },
      {
        "type": "element",
        "value": "green"
      },
      {
        "type": "literal",
        "value": ", and "
      },
      {
        "type": "element",
        "value": "blue"
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "type": "conjunction",
      "style": "long"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
German or-list
GET /api/locale-formats/list?locale=de-DE&items=Rot,Gelb,Blau&type=disjunction 
{
  "data": {
    "items": [
      "Rot",
      "Gelb",
      "Blau"
    ],
    "formatted": "Rot, Gelb oder Blau",
    "locale": "de-DE",
    "type": "disjunction",
    "style": "long",
    "parts": [
      {
        "type": "element",
        "value": "Rot"
      },
      {
        "type": "literal",
        "value": ", "
      },
      {
        "type": "element",
        "value": "Gelb"
      },
      {
        "type": "literal",
        "value": " oder "
      },
      {
        "type": "element",
        "value": "Blau"
      }
    ],
    "resolvedOptions": {
      "locale": "de-DE",
      "type": "disjunction",
      "style": "long"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Japanese ideographic commas
GET /api/locale-formats/list?locale=ja-JP&items=A,B,C 
{
  "data": {
    "items": [
      "A",
      "B",
      "C"
    ],
    "formatted": "A、B、C",
    "locale": "ja-JP",
    "type": "conjunction",
    "style": "long",
    "parts": [
      {
        "type": "element",
        "value": "A"
      },
      {
        "type": "literal",
        "value": "、"
      },
      {
        "type": "element",
        "value": "B"
      },
      {
        "type": "literal",
        "value": "、"
      },
      {
        "type": "element",
        "value": "C"
      }
    ],
    "resolvedOptions": {
      "locale": "ja-JP",
      "type": "conjunction",
      "style": "long"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Danish short disjunction
GET /api/locale-formats/list?locale=da-DK&items=rod,gul,blaa&type=disjunction&style=short 
{
  "data": {
    "items": [
      "rod",
      "gul",
      "blaa"
    ],
    "formatted": "rod, gul el. blaa",
    "locale": "da-DK",
    "type": "disjunction",
    "style": "short",
    "parts": [
      {
        "type": "element",
        "value": "rod"
      },
      {
        "type": "literal",
        "value": ", "
      },
      {
        "type": "element",
        "value": "gul"
      },
      {
        "type": "literal",
        "value": " el. "
      },
      {
        "type": "element",
        "value": "blaa"
      }
    ],
    "resolvedOptions": {
      "locale": "da-DK",
      "type": "disjunction",
      "style": "short"
    }
  },
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/locale-formats/relative-time Write a relative time the way a locale phrases it

Intl.RelativeTimeFormat with numeric='auto' by default, so -1 day becomes 'yesterday' rather than '1 day ago' where the locale has a word for it.

Live requestRuns against the public API
No key required
GET/api/locale-formats/relative-time?locale=en-US&value=-1&unit=day

Request parameters

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

Signed offset in the chosen unit — negative is in the past, positive in the future. Must be finite.

Time unit the value is counted in.

auto lets the locale use idiomatic words such as 'yesterday' or 'gestern' when it has one; always keeps the number, giving '1 day ago'.

Advanced response options4 options

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

Return all fields except these (comma-separated).

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/locale-formats/relative-time?locale=en-US&value=-1&unit=day"
const res = await fetch("https://randomapi.dev/api/locale-formats/relative-time?locale=en-US&value=-1&unit=day");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/locale-formats/relative-time?locale=en-US&value=-1&unit=day").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/locale-formats/relative-time?locale=en-US&value=-1&unit=day"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 4
locale string required

Unicode BCP 47 locale identifier such as de-DE, hi-IN or en-US-u-nu-arab. It is canonicalized, then checked against the data this runtime actually holds for the formatter the route uses; a locale with no data is rejected instead of being answered in the runtime's default language.

allowed: 2 – 64
example: locale=de-DE
value float required

Signed offset in the chosen unit — negative is in the past, positive in the future. Must be finite.

allowed: -1000000000000000 – 1000000000000000
example: value=-1
unit enum required

Time unit the value is counted in.

allowed: year | quarter | month | week | day | hour | minute | second
example: unit=day
numeric enum

auto lets the locale use idiomatic words such as 'yesterday' or 'gestern' when it has one; always keeps the number, giving '1 day ago'.

default: auto
allowed: always | auto
example: numeric=always
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=value,unit
exclude list

Return all fields except these (comma-separated).

example: exclude=resolvedOptions
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 7
value float

Signed offset supplied by the caller.

example: -1

unit string

Time unit the value was interpreted in.

example: day

formatted string

The locale's phrasing of that relative time.

example: yesterday

locale string

Locale actually resolved by Intl.RelativeTimeFormat.

example: en-US

numeric string

Resolved numeric mode: always or auto.

example: auto

parts object[]

formatToParts output; the numeric part also carries the unit it belongs to, and unit is null on literal parts.

example: [{"type":"integer","value":"1","unit":"day"},{"type":"literal","value":" day ago","unit":null}]

resolvedOptions object

The formatter's complete ECMA-402 resolvedOptions() object, exactly as this runtime reports it — the resolved locale, numbering system and every option that was actually applied.

example: {"locale":"de-DE","numberingSystem":"latn","style":"decimal","minimumIntegerDigits":1,"minimumFractionDigits":0,"maximumFractionDigits":3,"useGrouping":"auto","notation":"standard","signDisplay":"auto"}

Documented examples

Build-generated requests and complete responses 4
Yesterday in English
GET /api/locale-formats/relative-time?locale=en-US&value=-1&unit=day 
{
  "data": {
    "value": -1,
    "unit": "day",
    "formatted": "yesterday",
    "locale": "en-US",
    "numeric": "auto",
    "parts": [
      {
        "type": "literal",
        "value": "yesterday",
        "unit": null
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "style": "long",
      "numeric": "auto",
      "numberingSystem": "latn"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/relative-time",
    "params": {
      "locale": "en-US",
      "value": -1,
      "unit": "day",
      "numeric": "auto"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Numeric mode keeps the count
GET /api/locale-formats/relative-time?locale=en-US&value=-1&unit=day&numeric=always 
{
  "data": {
    "value": -1,
    "unit": "day",
    "formatted": "1 day ago",
    "locale": "en-US",
    "numeric": "always",
    "parts": [
      {
        "type": "integer",
        "value": "1",
        "unit": "day"
      },
      {
        "type": "literal",
        "value": " day ago",
        "unit": null
      }
    ],
    "resolvedOptions": {
      "locale": "en-US",
      "style": "long",
      "numeric": "always",
      "numberingSystem": "latn"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/relative-time",
    "params": {
      "locale": "en-US",
      "value": -1,
      "unit": "day",
      "numeric": "always"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
In three months, in German
GET /api/locale-formats/relative-time?locale=de-DE&value=3&unit=month 
{
  "data": {
    "value": 3,
    "unit": "month",
    "formatted": "in 3 Monaten",
    "locale": "de-DE",
    "numeric": "auto",
    "parts": [
      {
        "type": "literal",
        "value": "in ",
        "unit": null
      },
      {
        "type": "integer",
        "value": "3",
        "unit": "month"
      },
      {
        "type": "literal",
        "value": " Monaten",
        "unit": null
      }
    ],
    "resolvedOptions": {
      "locale": "de-DE",
      "style": "long",
      "numeric": "auto",
      "numberingSystem": "latn"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/relative-time",
    "params": {
      "locale": "de-DE",
      "value": 3,
      "unit": "month",
      "numeric": "auto"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Russian relative quarters
GET /api/locale-formats/relative-time?locale=ru-RU&value=-2&unit=quarter 
{
  "data": {
    "value": -2,
    "unit": "quarter",
    "formatted": "2 квартала назад",
    "locale": "ru-RU",
    "numeric": "auto",
    "parts": [
      {
        "type": "integer",
        "value": "2",
        "unit": "quarter"
      },
      {
        "type": "literal",
        "value": " квартала назад",
        "unit": null
      }
    ],
    "resolvedOptions": {
      "locale": "ru-RU",
      "style": "long",
      "numeric": "auto",
      "numberingSystem": "latn"
    }
  },
  "meta": {
    "endpoint": "locale-formats",
    "route": "/relative-time",
    "params": {
      "locale": "ru-RU",
      "value": -2,
      "unit": "quarter",
      "numeric": "auto"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Real locale formatting answers computed with the runtime's ECMA-402 Intl implementation over Unicode CLDR. No formatting table is bundled or hand-maintained here: /number, /currency, /date-time, /list and /relative-time are thin, fully-parameterized wrappers over Intl.NumberFormat, Intl.DateTimeFormat, Intl.ListFormat and Intl.RelativeTimeFormat, and every one of them returns the formatter's complete resolvedOptions() so the answer is self-describing rather than a magic string.

/patterns is the reference route. For one locale it reports the decimal and group separators, the grouping pattern (3;3 for German, 3;2 for the Indian lakh–crore style) and the magnitude at which grouping actually starts, the percent, minus and plus signs, the default numbering system, whether the currency symbol is a prefix or a suffix and what spacing sits next to it, whether accounting negatives use parentheses or a minus sign, the hour cycle (h11/h12/h23/h24), the default calendar, a rendering-derived short-date pattern, the first day of the week, the weekend days and the text direction. Every symbol is read back from formatToParts for that locale — none of it is hardcoded.

How the derived fields are produced (so you can check them):

  • decimalSeparator, groupSeparator and groupingPattern come from Intl.NumberFormat(locale).formatToParts(1234567890.123) — a value big enough that a 3;2 locale shows both group sizes.
  • minimumGroupingDigits is measured separately, by formatting smaller and smaller magnitudes until the group separator disappears. groupingPattern on its own over-groups a whole class of locales: es-ES, it-IT, pl-PL, hu-HU, bg-BG, sl-SI, lv-LV and et-EE all report groupingPattern: 3;3 but need 2 digits in front of the separator, so they write 1234 unseparated and only group from 12.345 up — and /number?locale=es-ES&value=1234 returns exactly that. Grouping a four-digit number for those locales is a bug you would otherwise ship.
  • minusSign comes from formatToParts(-1), plusSign from signDisplay: always on 1, and percentSign from a percent-styled format of 0.5.
  • currencyPosition and currencySpacing come from formatting 1234.56 in USD with currencyDisplay: symbol. CLDR keeps one currency pattern per locale, so the position genuinely does not depend on which currency you name — but it does depend on currencyDisplay: the localized name form is a suffix in many locales that put the symbol in front, so en-US gives $1,234.56 and 1,234.56 US dollars. The spacing varies too: CLDR inserts a separator when the symbol sits against a digit, so en-US reports "" for the $ of USD while SEK 1,234.56 gets a no-break space. Use /currency when you need the spacing, or the name placement, for one specific code.
  • accountingNegativeForm comes from the same currency format with currencySign: accounting applied to a negative amount. The bracket test tolerates the bidi control characters ar and fa glue onto the bracket literal, so those locales report parentheses rather than nothing.
  • shortDatePattern is read back from formatToParts of 2026-03-05T13:07:09.000Z under dateStyle: short, mapping digit widths onto d/dd, M/MM and yy/y. It is a pattern derived from output, not CLDR's stored pattern string, and it is null whenever the short date is not purely numeric (an era or a spelled-out month, for example).

Honest limits, in full:

  • Output follows the serving runtime's ICU/CLDR data and can change when that runtime is upgraded. No CLDR version is pinned or claimed, which is exactly why resolvedOptions() is echoed on every response.
  • Locale coverage is the runtime's, not ours. A tag the runtime has no data for is a 400 (404 on /patterns) rather than a silent fallback to English, so the set of accepted locales can differ between runtimes and can grow after an upgrade.
  • firstDayOfWeek, weekendDays and textDirection come from Intl.Locale.prototype.getWeekInfo/getTextInfo, which are feature-detected; where a runtime does not implement them the fields are null, never guessed.
  • ECMA-402 exposes no measurement-system data, so this endpoint does not report one instead of inventing it.
  • This endpoint formats and reports only. It holds no exchange rates, never converts between currencies and will not gain an FX route. /currency renders the amount you send in the currency you name.
  • currency is validated against this platform's active ISO 4217 table (the same one behind /api/currencies), so withdrawn codes, ISO funds codes and precious-metal codes are rejected.
  • Unknown numberingSystem and calendar values are rejected rather than silently ignored, because ECMA-402 would otherwise return the locale default under the label you asked for.

Use it for

  • Render server-side numbers, prices and timestamps the way a user's locale actually writes them
  • Look up a country's decimal and thousands separators before building a CSV export or an input mask
  • Decide whether a UI should show a 12-hour or a 24-hour clock for a given locale
  • Start a calendar grid on the locale's real first day of the week instead of assuming Monday
  • Verify Indian lakh–crore digit grouping and other non-uniform grouping without hand-writing CLDR patterns

Frequently asked questions

Practical answers about this endpoint 6
How do I find the thousands separator for a country?

Call /api/locale-formats/patterns?locale=de-DE. It returns groupSeparator and decimalSeparator read straight out of Intl.NumberFormat formatToParts, so German answers . and , while French answers a narrow no-break space and ,. Check minimumGroupingDigits too: it is 2 in Spanish, Italian and Polish, which write 1234 with no separator at all.

Why does Indian formatting group digits as 12,34,567?

Indian locales use a primary group of 3 and secondary groups of 2. /patterns?locale=hi-IN reports groupingPattern: "3;2", and /number?locale=hi-IN&value=1234567.89 renders 12,34,567.89.

Which locales use a 24-hour clock?

The hourCycle field on /patterns answers it: h23 or h24 means a 24-hour clock, h11 or h12 a 12-hour clock. It comes from Intl.DateTimeFormat resolved options, not a hand-kept list.

What is the first day of the week for a locale?

firstDayOfWeek on /patterns uses ISO numbering (1 = Monday … 7 = Sunday) from Intl.Locale.prototype.getWeekInfo, alongside weekendDays. Both are null when the runtime does not implement that method.

Does this API convert currencies or return exchange rates?

No. /currency formats the amount you supply in the currency you name and reports symbol placement and fraction digits. There are no FX rates here and no conversion route is planned.

Is the CLDR version pinned?

No. Every answer comes from the ICU/CLDR data compiled into the runtime serving the request, so output can change after a runtime upgrade. That is why each response echoes the formatter's resolvedOptions().

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Locale Plural Rules API REAL DATA

Select real cardinal or ordinal plural categories for a BCP 47 locale with runtime ECMA-402/CLDR rules and explicit locale validation.
BCP 47 Language Tag API REAL DATA

Canonicalize BCP 47 language tags and run RFC 4647 lookup or basic filtering with bounded, deterministic matching.
ISO 4217 Currency Codes API REAL DATA

Every active ISO 4217 currency — code, name, symbol, minor-unit decimals and the countries using it. Search the list or look up one code, with honest 404s.
Timezone Database API REAL DATA

Live IANA offsets, DST transitions, local-time ambiguity resolution and exact instant conversion — no guessed wall-clock mappings.
ISO 3166 Countries API REAL DATA

All 249 ISO 3166-1 countries and territories with codes, regions, capitals, currencies, languages, calling codes, flags and label-safe land points.
Exact Money and Minor Units API REAL DATA

Exact ISO 4217 major/minor-unit conversion and weighted allocation using decimal strings and integer arithmetic — no floats, rounding or FX rates.