# Package Type Codes API
> The UN/ECE Recommendation 21 package-type codes — the codes used to describe the kind of packaging in trade, transport and customs documents (packing lists, dangerous-goods declarations, EDI messages) — as an API. The reference a logistics, customs or e-invoicing system needs. Each of 400+ codes (for example 1A = steel drum, 5H = woven-plastic bag, BX = box, CT = carton, JY = jerrican) carries an alphanumeric code, a name, a description and a numeric code. Look a code up, reverse-look-up the codes that share a numeric code, search by name, or list them all. This is the packaging-type CODE register — distinct from containercodes-api (ISO 6346 shipping containers) and unitcodes-api (units of measure). 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/packagecodes-api/..."
```

## Pricing
- **Free** (Free) — 13,000 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 140,000 calls/Mo, 10 req/s
- **Pro** ($17/Mo) — 700,000 calls/Mo, 25 req/s
- **Mega** ($40/Mo) — 3,600,000 calls/Mo, 60 req/s

## Endpoints

### Lookup

#### `GET /v1/code` — Package type by UN/ECE code

**Parameters:**
- `code` (query, required, string) — UN/ECE package code Example: `1A`

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

**Response:**
```json
{
    "data": {
        "package": {
            "code": "1A",
            "name": "Drum, steel",
            "active": true,
            "status": "active",
            "description": null,
            "numeric_code": "34"
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:01.074Z",
        "request_id": "2f1ba269-76f1-4e85-9f7a-54901b9e78e8"
    },
    "status": "ok",
    "message": "Package code retrieved successfully",
    "success": true
}
```

#### `GET /v1/numeric` — Codes for a numeric code

**Parameters:**
- `numeric` (query, required, string) — Numeric code Example: `34`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/packagecodes-api/v1/numeric?numeric=34"
```

**Response:**
```json
{
    "data": {
        "count": 13,
        "packages": [
            {
                "code": "1A",
                "name": "Drum, steel",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1B",
                "name": "Drum, aluminium",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1D",
                "name": "Drum, plywood",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1G",
                "name": "Drum, fibre",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "DI",
                "name": "Drum, iron",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "DR",
                "name": "Drum",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
   
…(truncated, see openapi.json for full schema)
```

### Search

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

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

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

**Response:**
```json
{
    "data": {
        "count": 23,
        "query": "drum",
        "total": 23,
        "packages": [
            {
                "code": "1A",
                "name": "Drum, steel",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1B",
                "name": "Drum, aluminium",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1D",
                "name": "Drum, plywood",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1G",
                "name": "Drum, fibre",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1W",
                "name": "Drum, wooden",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34 or 35"
            },
            {
                "code": "DI",
                "name": "Drum, iron",
                "active": true,
                "status": "active",
                "description": n
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List package 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/packagecodes-api/v1/list?status=active&limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 404,
        "packages": [
            {
                "code": "1A",
                "name": "Drum, steel",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1B",
                "name": "Drum, aluminium",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1D",
                "name": "Drum, plywood",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1F",
                "name": "Container, flexible",
                "active": true,
                "status": "active",
                "description": "A packaging container of flexible construction.",
                "numeric_code": "93"
            },
            {
                "code": "1G",
                "name": "Drum, fibre",
                "active": true,
                "status": "active",
                "description": null,
                "numeric_code": "34"
            },
            {
                "code": "1W",
                "name": "Drum, wooden",
                "active": true,
                "status": "active",
        
…(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/packagecodes-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "packagecodes-api",
        "endpoints": {
            "GET /v1/code": "Package type by UN/ECE code (code=, e.g. 1A).",
            "GET /v1/list": "List package codes (status=active|deprecated, limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/search": "Search by code, name or description (q=, e.g. drum).",
            "GET /v1/numeric": "Codes for a numeric code (numeric=, e.g. 34)."
        },
        "description": "UN/ECE Recommendation 21 package-type codes for trade, transport and customs: alphanumeric code, name, description and numeric code. Look up a code, reverse-look-up by numeric code, search, or list. Distinct from containercodes-api (ISO 6346 containers) and unitcodes-api (units of measure). No key.",
        "total_codes": 406,
        "active_codes": 404
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:01.666Z",
        "request_id": "b60a5214-bd97-4b59-8eb0-52e0edf4af07"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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