# Units of Measure Codes API
> The UN/ECE Recommendation 20 unit-of-measure codes — the codes used to identify units of measure in trade documents, invoices and EDI messages — as an API. The reference a customs, ERP or e-invoicing system needs. Each unit (for example KGM = kilogram, MTR = metre, LTR = litre, C62 = one/each, TNE = tonne, MTK = square metre) carries a 2–3 character common code, a name, the unit symbol, a description and a status (active or deprecated). Look a code up, reverse-look-up the code(s) for a symbol (kg → KGM), search by name or symbol, or list every code filtered by status. This is the unit-of-measure CODE register — distinct from unit-api, which performs unit-conversion maths. Served from memory — always fast.

## 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/unitcodes-api/..."
```

## Pricing
- **Free** (Free) — 13,000 calls/Mo, 3 req/s
- **Starter** ($6/Mo) — 150,000 calls/Mo, 10 req/s
- **Pro** ($16/Mo) — 800,000 calls/Mo, 25 req/s
- **Mega** ($38/Mo) — 4,000,000 calls/Mo, 60 req/s

## Endpoints

### Lookup

#### `GET /v1/code` — Unit by UN/ECE common code

**Parameters:**
- `code` (query, required, string) — UN/ECE common code Example: `KGM`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitcodes-api/v1/code?code=KGM"
```

**Response:**
```json
{
    "data": {
        "unit": {
            "code": "KGM",
            "name": "kilogram",
            "active": true,
            "status": "active",
            "symbol": "kg",
            "description": "A unit of mass equal to one thousand grams."
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:03.411Z",
        "request_id": "aa150d53-cc2b-4219-a5f0-83cda7eba7c9"
    },
    "status": "ok",
    "message": "Unit code retrieved successfully",
    "success": true
}
```

#### `GET /v1/symbol` — Codes for a unit symbol

**Parameters:**
- `symbol` (query, required, string) — Unit symbol Example: `kg`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitcodes-api/v1/symbol?symbol=kg"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "units": [
            {
                "code": "KGM",
                "name": "kilogram",
                "active": true,
                "status": "active",
                "symbol": "kg",
                "description": "A unit of mass equal to one thousand grams."
            }
        ],
        "symbol": "kg"
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:03.542Z",
        "request_id": "728b4d0a-5b37-4b10-9a53-eeef9f48345c"
    },
    "status": "ok",
    "message": "Symbol lookup retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search unit codes

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `metre`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitcodes-api/v1/search?q=metre&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "query": "metre",
        "total": 491,
        "units": [
            {
                "code": "23",
                "name": "gram per cubic centimetre",
                "active": true,
                "status": "active",
                "symbol": "g/cm³",
                "description": null
            },
            {
                "code": "25",
                "name": "gram per square centimetre",
                "active": true,
                "status": "active",
                "symbol": "g/cm²",
                "description": null
            },
            {
                "code": "28",
                "name": "kilogram per square metre",
                "active": true,
                "status": "active",
                "symbol": "kg/m²",
                "description": null
            },
            {
                "code": "2J",
                "name": "cubic centimetre per second",
                "active": true,
                "status": "active",
                "symbol": "cm³/s",
                "description": null
            },
            {
                "code": "2M",
                "name": "centimetre per second",
                "active": true,
                "status": "active",
                "symbol": "cm/s",
                "description": null
            },
            {
                "code": "2X",
                "name": "metre per minute",
                "active": true,
                "st
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List unit codes

**Parameters:**
- `status` (query, optional, string) — active or deprecated Example: `active`
- `limit` (query, optional, string) — Page size (1-500) Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitcodes-api/v1/list?status=active&limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 1755,
        "units": [
            {
                "code": "10",
                "name": "group",
                "active": true,
                "status": "active",
                "symbol": null,
                "description": "A unit of count defining the number of groups (group: set of items classified together)."
            },
            {
                "code": "11",
                "name": "outfit",
                "active": true,
                "status": "active",
                "symbol": null,
                "description": "A unit of count defining the number of outfits (outfit: a complete set of equipment / materials / objects used for a specific purpose)."
            },
            {
                "code": "13",
                "name": "ration",
                "active": true,
                "status": "active",
                "symbol": null,
                "description": "A unit of count defining the number of rations (ration: a single portion of provisions)."
            },
            {
                "code": "14",
                "name": "shot",
                "active": true,
                "status": "active",
                "symbol": null,
                "description": "A unit of liquid measure, especially related to spirits."
            },
            {
                "code": "15",
                "name": "stick, military",
                "active": true,
                "status": "act
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "service": "unitcodes-api",
        "endpoints": {
            "GET /v1/code": "Unit by UN/ECE common code (code=, e.g. KGM).",
            "GET /v1/list": "List unit codes (status=active|deprecated, limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/search": "Search by code, name or symbol (q=, e.g. metre).",
            "GET /v1/symbol": "Codes for a unit symbol (symbol=, e.g. kg)."
        },
        "description": "UN/ECE Recommendation 20 units-of-measure codes for trade, invoicing and EDI: 2–3 character common code, name, symbol, description and status. Look up a code, reverse-look-up from a symbol, search, or list. Distinct from unit-api (conversion maths). No key.",
        "total_codes": 2136,
        "active_codes": 1755,
        "deprecated_codes": 381
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:03.896Z",
        "request_id": "a6ef240a-1d6f-40cb-b1c5-b7e612bdd83b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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