# Isotopes API
> Atomic isotope reference data as an API, built on the NIST Atomic Weights and Isotopic Compositions. For every known nuclide: its element (atomic number Z and symbol), mass number, relative atomic mass, natural isotopic composition (abundance) and the element's standard atomic weight. Look an isotope up by label (C-12, U-238) or by symbol + mass, list every isotope of an element, rank isotopes by mass or natural abundance, or search. A precise physics and chemistry reference for science, education, lab and engineering apps. Distinct from element-level data.

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

## Pricing
- **Free** (Free) — 600 calls/Mo, 5 req/s
- **Starter** ($7/Mo) — 18,000 calls/Mo, 15 req/s
- **Pro** ($19/Mo) — 90,000 calls/Mo, 30 req/s
- **Business** ($44/Mo) — 450,000 calls/Mo, 50 req/s

## Endpoints

### Isotopes

#### `GET /v1/element` — All isotopes of an element

**Parameters:**
- `symbol` (query, optional, string) — Element symbol (preferred) Example: `Sn`
- `z` (query, optional, string) — Atomic number, e.g. 50

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

**Response:**
```json
{
    "data": {
        "name": "Tin",
        "element": "Sn",
        "isotopes": [
            {
                "z": 50,
                "name": "Tin",
                "symbol": "Sn",
                "abundance": null,
                "atomic_mass": null,
                "mass_number": 99,
                "standard_atomic_weight": 118.71
            },
            {
                "z": 50,
                "name": "Tin",
                "symbol": "Sn",
                "abundance": null,
                "atomic_mass": 99.93904,
                "mass_number": 100,
                "standard_atomic_weight": 118.71
            },
            {
                "z": 50,
                "name": "Tin",
                "symbol": "Sn",
                "abundance": null,
                "atomic_mass": null,
                "mass_number": 101,
                "standard_atomic_weight": 118.71
            },
            {
                "z": 50,
                "name": "Tin",
                "symbol": "Sn",
                "abundance": null,
                "atomic_mass": 101.9303,
                "mass_number": 102,
                "standard_atomic_weight": 118.71
            },
            {
                "z": 50,
                "name": "Tin",
                "symbol": "Sn",
                "abundance": null,
                "atomic_mass": null,
                "mass_number": 103,
                "standard_atomic_weight": 118.71
            },
            {
                "z": 50
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/isotope` — Isotope by label or symbol+mass

**Parameters:**
- `id` (query, optional, string) — Isotope label (preferred), e.g. C-12 or U-238 Example: `U-238`
- `symbol` (query, optional, string) — Element symbol, e.g. C
- `mass` (query, optional, string) — Mass number, e.g. 12

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/isotopes-api/v1/isotope?id=U-238"
```

**Response:**
```json
{
    "data": {
        "isotope": {
            "z": 92,
            "name": "Uranium",
            "symbol": "U",
            "abundance": 0.992742,
            "atomic_mass": 238.0507882,
            "mass_number": 238,
            "standard_atomic_weight": 238.02891
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:47.430Z",
        "request_id": "d0d5317d-c023-4067-bbf1-e0a0517b9c09"
    },
    "status": "ok",
    "message": "Isotope retrieved successfully",
    "success": true
}
```

#### `GET /v1/list` — List isotopes

**Parameters:**
- `naturally_occurring` (query, optional, string) — true to list only natural Example: `true`
- `limit` (query, optional, string) — Max 1-500 Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`

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

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 288,
        "isotopes": [
            {
                "z": 1,
                "name": "Hydrogen",
                "symbol": "H",
                "abundance": 0.999885,
                "atomic_mass": 1.00782503207,
                "mass_number": 1,
                "standard_atomic_weight": 1.00794
            },
            {
                "z": 1,
                "name": "Hydrogen",
                "symbol": "D",
                "abundance": 0.000115,
                "atomic_mass": 2.0141017778,
                "mass_number": 2,
                "standard_atomic_weight": 1.00794
            },
            {
                "z": 2,
                "name": "Helium",
                "symbol": "He",
                "abundance": 1.34e-6,
                "atomic_mass": 3.0160293191,
                "mass_number": 3,
                "standard_atomic_weight": 4.002602
            },
            {
                "z": 2,
                "name": "Helium",
                "symbol": "He",
                "abundance": 0.99999866,
                "atomic_mass": 4.00260325415,
                "mass_number": 4,
                "standard_atomic_weight": 4.002602
            },
            {
                "z": 3,
                "name": "Lithium",
                "symbol": "Li",
                "abundance": 0.0759,
                "atomic_mass": 6.015122795,
                "mass_number": 6,
                "standard_atomic_weight": 6.
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search isotopes

**Parameters:**
- `q` (query, required, string) — Symbol, element name or label Example: `uranium`
- `limit` (query, optional, string) — Max 1-100 Example: `25`

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

**Response:**
```json
{
    "data": {
        "count": 25,
        "query": "uranium",
        "total": 26,
        "isotopes": [
            {
                "z": 92,
                "name": "Uranium",
                "symbol": "U",
                "abundance": null,
                "atomic_mass": 217.02437,
                "mass_number": 217,
                "standard_atomic_weight": 238.02891
            },
            {
                "z": 92,
                "name": "Uranium",
                "symbol": "U",
                "abundance": null,
                "atomic_mass": 218.02354,
                "mass_number": 218,
                "standard_atomic_weight": 238.02891
            },
            {
                "z": 92,
                "name": "Uranium",
                "symbol": "U",
                "abundance": null,
                "atomic_mass": 219.02492,
                "mass_number": 219,
                "standard_atomic_weight": 238.02891
            },
            {
                "z": 92,
                "name": "Uranium",
                "symbol": "U",
                "abundance": null,
                "atomic_mass": null,
                "mass_number": 220,
                "standard_atomic_weight": 238.02891
            },
            {
                "z": 92,
                "name": "Uranium",
                "symbol": "U",
                "abundance": null,
                "atomic_mass": null,
                "mass_number": 221,
                "standard_atomic_weight": 23
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/rank` — Rank isotopes by metric

**Parameters:**
- `by` (query, optional, string) — abundance | atomic_mass | mass_number Example: `abundance`
- `order` (query, optional, string) — desc or asc Example: `desc`
- `limit` (query, optional, string) — Max 1-300 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/isotopes-api/v1/rank?by=abundance&order=desc&limit=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "order": "desc",
        "metric": "abundance",
        "ranking": [
            {
                "z": 4,
                "name": "Beryllium",
                "value": 1,
                "symbol": "Be",
                "position": 1,
                "abundance": 1,
                "atomic_mass": 9.0121822,
                "mass_number": 9,
                "standard_atomic_weight": 9.012182
            },
            {
                "z": 9,
                "name": "Fluorine",
                "value": 1,
                "symbol": "F",
                "position": 2,
                "abundance": 1,
                "atomic_mass": 18.99840322,
                "mass_number": 19,
                "standard_atomic_weight": 18.9984032
            },
            {
                "z": 11,
                "name": "Sodium",
                "value": 1,
                "symbol": "Na",
                "position": 3,
                "abundance": 1,
                "atomic_mass": 22.9897692809,
                "mass_number": 23,
                "standard_atomic_weight": 22.98976928
            },
            {
                "z": 13,
                "name": "Aluminium",
                "value": 1,
                "symbol": "Al",
                "position": 4,
                "abundance": 1,
                "atomic_mass": 26.98153863,
                "mass_number": 27,
                "standard_atomic_weight": 26.9815386
            },
           
…(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/isotopes-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "isotopes-api",
        "endpoints": {
            "GET /v1/list": "List isotopes (naturally_occurring=true to filter, limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/rank": "Rank isotopes by metric (by=atomic_mass|abundance|mass_number, order, limit).",
            "GET /v1/search": "Search isotopes by symbol, name or label (q=).",
            "GET /v1/element": "All isotopes of an element (symbol=C or z=6).",
            "GET /v1/isotope": "Isotope by id (id=C-12 or U-238), or symbol= + mass=, or z= + mass=."
        },
        "description": "NIST atomic isotope reference for every known nuclide: element (Z, symbol), mass number, relative atomic mass, natural isotopic composition and standard atomic weight. Look up an isotope (C-12, U-238), list an element's isotopes, rank by mass or abundance, or search. Distinct from elements-api. No key.",
        "total_isotopes": 3180,
        "rankable_metrics": [
            "atomic_mass",
            "abundance",
            "mass_number"
        ],
        "distinct_elements": 118,
        "naturally_occurring": 288
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:47.785Z",
        "request_id": "9992d37a-b58b-48d3-91c4-bf2e724af8b4"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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