# Number & Currency Formatter API
> Format numbers for any locale using full ICU data — the correct way to display money, percentages and measurements per region. Pass a value and a style and the format endpoint returns the locale-correct string: decimal, currency (any ISO 4217 code, with the right symbol and grouping — e.g. 1.234.567,89 € in de-DE, $1,234,567.89 in en-US, ￥1,234,567 in ja-JP, and the Indian lakh grouping 12,34,567.89 in hi-IN), percent, or unit (e.g. 80 km/h). Control the locale (BCP 47), minimum/maximum fraction digits, grouping, sign display and notation (standard, scientific, engineering or compact like 1.2M). A parts endpoint returns the formatToParts breakdown (integer, group, decimal, fraction, currency symbol…) for building custom-styled displays. Everything is computed locally with no network calls. Ideal for internationalised UIs, invoices and receipts, dashboards and reports. A locale number/currency formatter — distinct from foreign-exchange rates (currency), number-to-words (numberwords) and the numeral-base converter (baseconvert). No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/numberformat-api/..."
```

## Pricing
- **Free** (Free) — 2,080 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 39,500 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 210,000 calls/Mo, 20 req/s
- **Mega** ($52/Mo) — 805,000 calls/Mo, 50 req/s

## Endpoints

### Number Format

#### `GET /v1/format` — Format a number for a locale

**Parameters:**
- `value` (query, required, string) — The number Example: `1234567.89`
- `style` (query, optional, string) — decimal, currency, percent, unit Example: `currency`
- `currency` (query, optional, string) — ISO 4217 (for style=currency) Example: `EUR`
- `locale` (query, optional, string) — BCP 47 locale Example: `de-DE`
- `notation` (query, optional, string) — standard, scientific, engineering, compact

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numberformat-api/v1/format?value=1234567.89&style=currency&currency=EUR&locale=de-DE"
```

**Response:**
```json
{
    "data": {
        "style": "currency",
        "value": 1234567.89,
        "locale": "de-DE",
        "resolved": {
            "currency": "EUR",
            "notation": "standard",
            "useGrouping": "auto",
            "numberingSystem": "latn",
            "maximumFractionDigits": 2,
            "minimumFractionDigits": 2
        },
        "formatted": "1.234.567,89 €"
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:41.809Z",
        "request_id": "635eb465-3c91-4453-8ac5-788971dfcaae"
    },
    "status": "ok",
    "message": "Number formatted",
    "success": true
}
```

#### `GET /v1/parts` — formatToParts breakdown

**Parameters:**
- `value` (query, required, string) — The number Example: `1234.5`
- `locale` (query, optional, string) — BCP 47 locale Example: `en-US`
- `style` (query, optional, string) — decimal, currency, percent, unit
- `currency` (query, optional, string) — ISO 4217 (for style=currency)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numberformat-api/v1/parts?value=1234.5&locale=en-US"
```

**Response:**
```json
{
    "data": {
        "parts": [
            {
                "type": "integer",
                "value": "1"
            },
            {
                "type": "group",
                "value": ","
            },
            {
                "type": "integer",
                "value": "234"
            },
            {
                "type": "decimal",
                "value": "."
            },
            {
                "type": "fraction",
                "value": "5"
            }
        ],
        "style": "decimal",
        "value": 1234.5,
        "locale": "en-US",
        "formatted": "1,234.5"
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:41.898Z",
        "request_id": "22c957ca-f32a-4fd4-b713-d860bb4069e4"
    },
    "status": "ok",
    "message": "Parts computed",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Styles, notations & locales

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numberformat-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Format numbers for any locale using the platform's full ICU data. /v1/format?value=1234567.89&style=currency&currency=EUR&locale=de-DE returns the locale-correct string (e.g. 1.234.567,89 €). Styles: decimal, currency (ISO 4217, with currencyDisplay symbol/code/name), percent and unit (e.g. unit=kilometer-per-hour). Options: locale (BCP 47), minimum/maximumFractionDigits, useGrouping, notation (standard, scientific, engineering, compact — e.g. 1.2M), signDisplay. /v1/parts returns the formatToParts breakdown (integer, group, decimal, fraction, currency symbol, …) for building custom-styled displays. Everything is computed locally with no network calls. Ideal for internationalised UIs, invoices and receipts, dashboards, reports and anywhere numbers or money must read correctly per region. A locale number/currency formatter — distinct from foreign-exchange rates (currency), number-to-words (numberwords) and the base converter (baseconvert). No key, no cache.",
        "styles": [
            "decimal",
            "currency",
            "percent",
            "unit"
        ],
        "endpoints": [
            "/v1/format",
            "/v1/parts",
            "/v1/meta"
        ],
        "notations": [
            "standard",
            "scientific",
            "engineering",
            "compact"
        ],
        "example_locales": [
            "en-US",
            "de-DE",
            "fr-FR",
            "ja-JP",
            
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/numberformat-api
OpenAPI spec: https://www.oanor.com/api/numberformat-api/openapi.json