Skip to main content

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.

Authoritative reference data or standards computation

Base URL
/api/plural-rules
Category
Text & Content
Capabilities
2 routes
Last updated
July 29, 2026
Data source

GET /api/plural-rules/select Select the cardinal or ordinal plural category for one numeric value

Live requestRuns against the public API
No key required
GET/api/plural-rules/select?locale=en-US&type=ordinal&value=2

Request parameters

Unicode BCP 47 locale identifier. It is canonicalized, then explicitly checked against the runtime's plural-rule data; unsupported locales are a 400, never a silent default-locale fallback.

cardinal selects quantity forms (one item, two items); ordinal selects ordering forms (1st, 2nd, 3rd).

Finite numeric operand to classify, between -10^15 and 10^15 inclusive.

Minimum visible fraction digits used before plural selection. Must be no greater than maximumFractionDigits.

Maximum fraction digits used to round the operand before plural selection (0–20).

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/plural-rules/select?locale=en-US&type=ordinal&value=2"
const res = await fetch("https://randomapi.dev/api/plural-rules/select?locale=en-US&type=ordinal&value=2");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/plural-rules/select?locale=en-US&type=ordinal&value=2").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/plural-rules/select?locale=en-US&type=ordinal&value=2"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 5
locale string required

Unicode BCP 47 locale identifier. It is canonicalized, then explicitly checked against the runtime's plural-rule data; unsupported locales are a 400, never a silent default-locale fallback.

allowed: 2 – 64
example: locale=en-US
type enum

cardinal selects quantity forms (one item, two items); ordinal selects ordering forms (1st, 2nd, 3rd).

default: cardinal
allowed: cardinal | ordinal
example: type=ordinal
value float required

Finite numeric operand to classify, between -10^15 and 10^15 inclusive.

allowed: -1000000000000000 – 1000000000000000
example: value=2
minimumFractionDigits int

Minimum visible fraction digits used before plural selection. Must be no greater than maximumFractionDigits.

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

Maximum fraction digits used to round the operand before plural selection (0–20).

default: 3
allowed: 0 – 20
example: maximumFractionDigits=3
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=value,locale
exclude list

Return all fields except these (comma-separated).

example: exclude=maximumFractionDigits
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

Numeric operand supplied by the caller.

example: 2

locale string

Actual locale resolved by Intl.PluralRules.

example: en-US

type string

cardinal or ordinal rule family.

example: ordinal

category string

Selected ECMA-402 plural category.

example: two

categories string[]

All categories available for this resolved locale/type.

example: ["one","two","few","other"]

minimumFractionDigits integer

Resolved minimum fraction digits used during selection.

example: 0

maximumFractionDigits integer

Resolved maximum fraction digits used during selection.

example: 3

Documented examples

Build-generated requests and complete responses 3
English second-place ordinal
GET /api/plural-rules/select?locale=en-US&type=ordinal&value=2 
{
  "data": {
    "value": 2,
    "locale": "en",
    "type": "ordinal",
    "category": "two",
    "categories": [
      "few",
      "one",
      "two",
      "other"
    ],
    "minimumFractionDigits": 0,
    "maximumFractionDigits": 3
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/select",
    "params": {
      "locale": "en-US",
      "type": "ordinal",
      "value": 2,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 3
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Arabic dual cardinal form
GET /api/plural-rules/select?locale=ar&type=cardinal&value=2 
{
  "data": {
    "value": 2,
    "locale": "ar",
    "type": "cardinal",
    "category": "two",
    "categories": [
      "few",
      "many",
      "one",
      "two",
      "zero",
      "other"
    ],
    "minimumFractionDigits": 0,
    "maximumFractionDigits": 3
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/select",
    "params": {
      "locale": "ar",
      "type": "cardinal",
      "value": 2,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 3
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Russian many category
GET /api/plural-rules/select?locale=ru&value=5 
{
  "data": {
    "value": 5,
    "locale": "ru",
    "type": "cardinal",
    "category": "many",
    "categories": [
      "few",
      "many",
      "one",
      "other"
    ],
    "minimumFractionDigits": 0,
    "maximumFractionDigits": 3
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/select",
    "params": {
      "locale": "ru",
      "type": "cardinal",
      "value": 5,
      "minimumFractionDigits": 0,
      "maximumFractionDigits": 3
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/plural-rules/categories List every plural category available for a locale and rule type

Returns the runtime locale/type vocabulary. Fraction-digit options are intentionally /select-only because ECMA-402 pluralCategories is not narrowed by them.

Live requestRuns against the public API
No key required
GET/api/plural-rules/categories?locale=ru&type=cardinal

Request parameters

Unicode BCP 47 locale identifier. It is canonicalized, then explicitly checked against the runtime's plural-rule data; unsupported locales are a 400, never a silent default-locale fallback.

cardinal selects quantity forms (one item, two items); ordinal selects ordering forms (1st, 2nd, 3rd).

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/plural-rules/categories?locale=ru&type=cardinal"
const res = await fetch("https://randomapi.dev/api/plural-rules/categories?locale=ru&type=cardinal");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/plural-rules/categories?locale=ru&type=cardinal").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/plural-rules/categories?locale=ru&type=cardinal"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
locale string required

Unicode BCP 47 locale identifier. It is canonicalized, then explicitly checked against the runtime's plural-rule data; unsupported locales are a 400, never a silent default-locale fallback.

allowed: 2 – 64
example: locale=en-US
type enum

cardinal selects quantity forms (one item, two items); ordinal selects ordering forms (1st, 2nd, 3rd).

default: cardinal
allowed: cardinal | ordinal
example: type=ordinal
Universal parameters Shared response and formatting options 4
fields list

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

example: fields=locale,type
exclude list

Return all fields except these (comma-separated).

example: exclude=categories
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 3
locale string

Actual locale resolved by Intl.PluralRules.

example: ru

type string

cardinal or ordinal rule family.

example: cardinal

categories string[]

The complete category vocabulary exposed by the runtime for this locale/type.

example: ["one","few","many","other"]

Documented examples

Build-generated requests and complete responses 3
Russian cardinal categories
GET /api/plural-rules/categories?locale=ru&type=cardinal 
{
  "data": {
    "locale": "ru",
    "type": "cardinal",
    "categories": [
      "few",
      "many",
      "one",
      "other"
    ]
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/categories",
    "params": {
      "locale": "ru",
      "type": "cardinal"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
English ordinal categories
GET /api/plural-rules/categories?locale=en&type=ordinal 
{
  "data": {
    "locale": "en",
    "type": "ordinal",
    "categories": [
      "few",
      "one",
      "two",
      "other"
    ]
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/categories",
    "params": {
      "locale": "en",
      "type": "ordinal"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Danish cardinal categories
GET /api/plural-rules/categories?locale=da-DK&type=cardinal 
{
  "data": {
    "locale": "da",
    "type": "cardinal",
    "categories": [
      "one",
      "other"
    ]
  },
  "meta": {
    "endpoint": "plural-rules",
    "route": "/categories",
    "params": {
      "locale": "da-DK",
      "type": "cardinal"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Locale-aware plural selection using the runtime's standards-based Intl.PluralRules implementation. It answers which translation branch a numeric value belongs to — zero, one, two, few, many or other — without reducing every language to an English singular/plural assumption.

  • /select accepts one finite number, a BCP 47 locale and type=cardinal|ordinal. Fraction-digit options are passed to ECMA-402 before selection, because rounding and visible decimals can change the chosen category.
  • /categories returns the runtime's category vocabulary for the resolved locale/type, in the order exposed by resolvedOptions().pluralCategories. Fraction-digit options belong only to /select: ECMA-402 does not narrow pluralCategories to categories reachable under one rounding configuration, so this route deliberately does not accept them.

Locale handling is deliberately strict. The input is canonicalized with Intl.getCanonicalLocales, checked with Intl.PluralRules.supportedLocalesOf, and echoed in canonical form. An unsupported locale returns a 400 instead of silently falling back to the Worker's default locale. The response also exposes the actual resolved locale, because a supported regional tag may intentionally use its parent language's plural data.

The rules come from the runtime's ICU/CLDR data and can improve with runtime upgrades. This endpoint chooses grammatical categories only; it does not translate nouns or sentences.

Use it for

  • Choose the correct ICU message branch for localized item counts on a server or test fixture
  • Verify cardinal and ordinal plural behavior for Arabic, Slavic and other multi-form languages
  • Inspect every plural category a locale can produce before authoring translation keys

Frequently asked questions

Practical answers about this endpoint 3
Which plural categories can the API return?

The ECMA-402 categories are zero, one, two, few, many and other; each locale exposes only the categories its cardinal or ordinal rules actually use.

Does an unsupported locale fall back to English?

No. The locale is canonicalized and checked against runtime plural data first; unsupported values answer 400 rather than silently returning a different language's rule.

Why do fraction digit options matter?

Plural operands are evaluated after ECMA-402 number rounding. minimumFractionDigits and maximumFractionDigits make that visible behavior explicit and reproducible.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
ISO 639 Language Codes API REAL DATA

All 183 active ISO 639 two-letter language codes with matching terminology and bibliographic three-letter codes, searchable with exact lookups.
BCP 47 Language Tag API REAL DATA

Canonicalize BCP 47 language tags and run RFC 4647 lookup or basic filtering with bounded, deterministic matching.
Unicode Normalization and Segmentation API REAL DATA

Inspect UTF-16 and Unicode scalar values, apply the four standard normalization forms, and segment text into graphemes, words or sentences.
Random Number Generator API MOCK DATA

Random integers or floats in any range — control decimal precision, draw guaranteed-unique values, and pin a seed for reproducible sequences.
Random Word API MOCK DATA

Random English words by part of speech — nouns, verbs, adjectives or adverbs — with working length filters, seedable output and honest 400s when nothing fits.
Locale-Aware String Sorting API REAL DATA

Sort and compare strings the way a locale actually orders them: German sorts ä with a, Swedish sorts it after z. Every option visibly changes the answer.