---
title: "Number to words in 12 languages, with ordinal and currency forms"
method: GET
path: "/v1/num/words"
tags: ["deterministic", "no-api-key", "num", "numbers", "localisation"]
---

# Number to words in 12 languages, with ordinal and currency forms

`GET /v1/num/words`

## Request

- Base URL: `https://api.duoleads.com`
- URL: `https://api.duoleads.com/v1/num/words`
- Auth: none declared

Number to words: spell a number out in English, Dutch, German, French, Spanish, Italian, Portuguese, Polish, Russian, Turkish, Swedish or Japanese, in cardinal, ordinal or currency form. Currency form agrees the number with the currency noun and gives real minor-unit names for 19 currencies (EUR, USD, GBP, CHF, SEK, NOK, DKK, PLN, RUB, TRY, CNY, INR, BRL, MXN, CAD, AUD, NZD, CZK, HUF); any other ISO 4217 code uses a fraction such as 56/100. Values up to 10^15.

**Output (`data`):** words (ordinals are the masculine singular nominative form, e.g. es segundo, fr deuxième, it secondo, pt segundo, pl drugi, ru второй, sv andra, tr ikinci, ja 二番目; form=year reads pl and ru as an ordinal, ja with the suffix 年, and en, nl, de and sv in hundreds; in the currency form the number agrees with the gender of the currency noun, e.g. fr une couronne, es una libra, ru одна крона, sv ett pund), value, lang, form, currency ({code, unit_singular, unit_plural, minor_singular, minor_plural, minor_units} or null; minor_singular and minor_plural are null for zero-decimal currencies and for currencies without a curated subunit name), parts ({integer_words, minor_words} for the currency form; minor_words is the subunit count in words for the 19 curated currencies (EUR, USD, GBP, CHF, SEK, NOK, DKK, PLN, RUB, TRY, CNY, INR, BRL, MXN, CAD, AUD, NZD, CZK, HUF); every other currency uses the neutral fraction <n>/<10^minor_units> with no leading zeros (10/1000, 1/100, 56/100) instead of a subunit name, and null when there is no minor part; parts is null for other forms), rounding_applied (currency form; present, true, only when surplus decimals were rounded; an amount that rounds up to 1e15 is rejected).

Deterministic: identical input returns identical output, so the response is served with `Cache-Control: private, max-age=31536000, immutable` (the paying client may cache it indefinitely; shared caches must not, because the response is paid).

Price: $0.05 USDC per call (x402, Base). Route contract version 1.0.0. Docs: https://api.duoleads.com/docs#num-words

## Query parameters

- `value` string, required
- `lang` 'en' | 'nl' | 'de' | 'fr' | 'es' | 'it' | 'pt' | 'pl' | 'ru' | 'tr' | 'sv' | 'ja'
- `form` 'cardinal' | 'ordinal' | 'currency' | 'year'
- `currency` string
- `case` 'lower' | 'sentence' | 'title'

## Response `200`

Paid and settled. `data` is route-specific; a route that judges its input returns 200 with `data.valid: false` for a bad value.

- object
  - `ok` unknown, required
  - `route` '/v1/num/words', required
  - `version` '1.0.0', required
  - `data` object, required: words (ordinals are the masculine singular nominative form, e.g. es segundo, fr deuxième, it secondo, pt segundo, pl drugi, ru второй, sv andra, tr ikinci, ja 二番目; form=year reads pl and ru as an ordinal, ja with the suffix 年, and en, nl, de and sv in hundreds; in the currency form the number agrees with the gender of the currency noun, e.g. fr une couronne, es una libra, ru одна крона, sv ett pund), value, lang, form, currency ({code, unit_singular, unit_plural, minor_singular, minor_plural, minor_units} or null; minor_singular and minor_plural are null for zero-decimal currencies and for currencies without a curated subunit name), parts ({integer_words, minor_words} for the currency form; minor_words is the subunit count in words for the 19 curated currencies (EUR, USD, GBP, CHF, SEK, NOK, DKK, PLN, RUB, TRY, CNY, INR, BRL, MXN, CAD, AUD, NZD, CZK, HUF); every other currency uses the neutral fraction <n>/<10^minor_units> with no leading zeros (10/1000, 1/100, 56/100) instead of a subunit name, and null when there is no minor part; parts is null for other forms), rounding_applied (currency form; present, true, only when surplus decimals were rounded; an amount that rounds up to 1e15 is rejected).
    - `words` string, required
    - `value` string, required
    - `lang` string, required
    - `form` string, required
    - `currency` object, nullable, required
      - `code` string, required
      - `unit_singular` string, required
      - `unit_plural` string, required
      - `minor_singular` string, nullable, required
      - `minor_plural` string, nullable, required
      - `minor_units` integer, required
    - `parts` object, nullable
      - `integer_words` string, required
      - `minor_words` string, nullable, required
    - `rounding_applied` boolean
  - `meta` Meta, required
    - `disclaimer` string, required: Legal short disclaimer, identical on every response.
    - `request_id` string, required: ULID.
    - `computed_at` string, date-time, required: RFC 3339 UTC with milliseconds.
    - `price_usd` string, required: Decimal string, "0.05".
    - `deterministic` boolean, required
    - `sources` object[]: Present only on routes that read a vendored dataset: the exact edition that answered.
      - `id` string, required
      - `version` string, required
      - `published` string, required
      - `attribution` string
      - `licence` string

## Other responses

- `400`: MISSING_PARAM, INVALID_PARAM or UNSUPPORTED_VALUE. Not charged: validation runs before the paywall.
- `402`: Payment required. No valid PAYMENT-SIGNATURE was supplied: read the base64 PAYMENT-REQUIRED header (or this body) for the price ($0.05 = 50000 atomic USDC on eip155:8453), sign an EIP-3009 authorization and retry. Also returned when settlement is declined (PAYMENT_FAILED). Nothing is charged on a 402.
- `404`: NOT_FOUND: unknown path. Not charged.
- `405`: METHOD_NOT_ALLOWED: only GET and HEAD are served. Not charged.
- `413`: INPUT_TOO_LARGE: a parameter exceeded its documented maximum length. Not charged.
- `500`: INTERNAL: a server bug. Not charged.

---

[API](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo.md) · [All operations](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/llms.txt) · [OpenAPI document](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/revisions/18790d59615e?raw)