# PDB API
> The RCSB Protein Data Bank as an API — 3D macromolecular structures of proteins, nucleic acids and complexes, powered by the official RCSB PDB data and search services. Fetch a structure entry by its 4-character PDB id for its title, experimental method (X-ray, cryo-EM, NMR), resolution, keywords, deposit and release dates, authors, primary citation and entity & assembly counts; run full-text search across the whole archive returning matching PDB ids and the total hit count; read a polymer entity for its protein or nucleic-acid name, one-letter sequence, length, source organism, chains and linked UniProt ids; read a biological assembly for its oligomeric state, symmetry and chain & atom counts; list the ligands bound in a structure with their component ids and names; and look up any chemical component (ligand) by code for its formula, weight, SMILES and InChIKey. Ideal for structural-biology and drug-discovery tools, molecular viewers, bioinformatics pipelines, education apps and research dashboards.

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

## Pricing
- **Free** (Free) — 550 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 19,000 calls/Mo, 6 req/s
- **Pro** ($21/Mo) — 88,000 calls/Mo, 15 req/s
- **Mega** ($57/Mo) — 340,000 calls/Mo, 40 req/s

## Endpoints

### Structures

#### `GET /v1/search` — Full-text search of the PDB

**Parameters:**
- `query` (query, required, string) — Search text, e.g. hemoglobin Example: `hemoglobin`
- `limit` (query, optional, string) — Max ids (1-100)
- `start` (query, optional, string) — Pagination offset

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/search?query=hemoglobin"
```

**Response:**
```json
{
    "data": {
        "ids": [
            "3GOU",
            "6IHX",
            "2PGH",
            "9JYU",
            "9RXG",
            "3PEL",
            "3PI9",
            "3PIA",
            "1FSX",
            "6II1",
            "1G0B",
            "4YU3",
            "1FHJ",
            "1G08",
            "1G09",
            "1G0A",
            "1HBR",
            "2D5X",
            "2QSP",
            "5C6E",
            "3CIU",
            "2ZFB",
            "2QLS",
            "3GQP",
            "3PI8"
        ],
        "count": 25,
        "query": "hemoglobin",
        "start": 0,
        "total": 9054
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:09.263Z",
        "request_id": "95aa872c-33fa-46ca-844f-88173c98f61a"
    },
    "status": "ok",
    "message": "Search results retrieved",
    "success": true
}
```

#### `GET /v1/structure` — A structure entry

**Parameters:**
- `id` (query, required, string) — 4-char PDB id, e.g. 4HHB Example: `4HHB`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/structure?id=4HHB"
```

**Response:**
```json
{
    "data": {
        "structure": {
            "id": "4HHB",
            "title": "THE CRYSTAL STRUCTURE OF HUMAN DEOXYHAEMOGLOBIN AT 1.74 ANGSTROMS RESOLUTION",
            "method": [
                "X-RAY DIFFRACTION"
            ],
            "authors": [
                "Fermi, G.",
                "Perutz, M.F."
            ],
            "citation": {
                "doi": null,
                "year": 1984,
                "title": "The crystal structure of human deoxyhaemoglobin at 1.74 A resolution",
                "pubmed": null,
                "journal": "J.Mol.Biol."
            },
            "keywords": "OXYGEN TRANSPORT",
            "released": "1984-07-17",
            "revision": "2024-05-22",
            "deposited": "1984-03-07",
            "resolution": 1.74,
            "assembly_ids": [
                "1"
            ],
            "assembly_count": 1,
            "molecular_weight": 64.74,
            "polymer_entity_ids": [
                "1",
                "2"
            ],
            "deposited_atom_count": 4779,
            "polymer_entity_count": 2,
            "nonpolymer_entity_count": 2
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:10.023Z",
        "request_id": "54e29fa5-5044-4ed9-bd10-9270efb01b8d"
    },
    "status": "ok",
    "message": "Structure retrieved",
    "success": true
}
```

### Entities

#### `GET /v1/assembly` — A biological assembly

**Parameters:**
- `id` (query, required, string) — PDB id Example: `4HHB`
- `assembly` (query, optional, string) — Assembly number (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/assembly?id=4HHB&assembly=1"
```

**Response:**
```json
{
    "data": {
        "assembly": {
            "method": "PISA",
            "pdb_id": "4HHB",
            "details": "author_and_software_defined_assembly",
            "symmetry": [
                {
                    "type": "Cyclic",
                    "symbol": "C2",
                    "oligomeric_state": "Hetero 4-mer"
                },
                {
                    "type": "Dihedral",
                    "symbol": "D2",
                    "oligomeric_state": "Homo 4-mer"
                }
            ],
            "assembly_id": "1",
            "total_atoms": 4779,
            "modeled_residues": 574,
            "oligomeric_count": 4,
            "oligomeric_state": "tetrameric",
            "polymer_entity_instances": 4,
            "nonpolymer_entity_instances": 6
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:10.191Z",
        "request_id": "4a0ed668-ea3a-463a-aad6-3bec5b6019eb"
    },
    "status": "ok",
    "message": "Assembly retrieved",
    "success": true
}
```

#### `GET /v1/polymer` — A polymer entity (protein / nucleic acid)

**Parameters:**
- `id` (query, required, string) — PDB id Example: `4HHB`
- `entity` (query, optional, string) — Entity number (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/polymer?id=4HHB&entity=1"
```

**Response:**
```json
{
    "data": {
        "polymer": {
            "name": "Hemoglobin subunit alpha",
            "type": "Protein",
            "chains": [
                "A",
                "C"
            ],
            "length": 141,
            "pdb_id": "4HHB",
            "source": [
                {
                    "organism": "Homo sapiens",
                    "taxonomy_id": 9606
                }
            ],
            "sequence": "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR",
            "entity_id": "1",
            "uniprot_ids": [
                "P69905"
            ]
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:10.346Z",
        "request_id": "2f8ab080-efc2-450e-9870-b909d766efe9"
    },
    "status": "ok",
    "message": "Polymer entity retrieved",
    "success": true
}
```

### Ligands

#### `GET /v1/chemcomp` — A chemical component / ligand

**Parameters:**
- `id` (query, required, string) — Component id, e.g. HEM Example: `HEM`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/chemcomp?id=HEM"
```

**Response:**
```json
{
    "data": {
        "chemcomp": {
            "id": "HEM",
            "name": "PROTOPORPHYRIN IX CONTAINING FE",
            "type": "non-polymer",
            "smiles": null,
            "formula": "C34 H32 Fe N4 O4",
            "inchi_key": null,
            "atom_count": 75,
            "bond_count": 82,
            "formula_weight": 616.487,
            "mon_nstd_parent": null
        }
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:10.531Z",
        "request_id": "9eb2ae14-1a8a-4899-8009-8b638563f7f7"
    },
    "status": "ok",
    "message": "Chemical component retrieved",
    "success": true
}
```

#### `GET /v1/ligands` — Ligands bound in a structure

**Parameters:**
- `id` (query, required, string) — PDB id Example: `4HHB`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pdb-api/v1/ligands?id=4HHB"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "pdb_id": "4HHB",
        "ligands": [
            {
                "name": "PROTOPORPHYRIN IX CONTAINING FE",
                "chains": [
                    "A",
                    "B",
                    "C",
                    "D"
                ],
                "comp_id": "HEM",
                "entity_id": "3"
            },
            {
                "name": "PHOSPHATE ION",
                "chains": [
                    "B",
                    "D"
                ],
                "comp_id": "PO4",
                "entity_id": "4"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:10.915Z",
        "request_id": "508dd85d-8cf0-46ff-af88-b3edb7ae44f2"
    },
    "status": "ok",
    "message": "Ligands retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

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

**Response:**
```json
{
    "data": {
        "note": "3D macromolecular structures from the RCSB PDB. /v1/structure?id=4HHB = a structure entry (title, experimental method, resolution, keywords, deposit/release dates, authors, primary citation, entity & assembly counts, molecular weight); /v1/search?query=hemoglobin = full-text search returning matching PDB ids and the total count (paginate with start & limit); /v1/polymer?id=4HHB&entity=1 = a polymer entity (protein/nucleic-acid name, type, one-letter sequence, length, source organism, chains, linked UniProt ids); /v1/assembly?id=4HHB&assembly=1 = a biological assembly (oligomeric state, symmetry, chain & atom counts); /v1/ligands?id=4HHB = the ligands bound in a structure (component id, name, chains); /v1/chemcomp?id=HEM = a chemical component / ligand definition (name, formula, weight, SMILES, InChIKey). PDB ids are 4 characters (e.g. 4HHB). Data courtesy of RCSB PDB. For protein sequences & function see the UniProt API.",
        "source": "RCSB Protein Data Bank REST + search APIs (rcsb.org)",
        "endpoints": [
            "/v1/structure",
            "/v1/search",
            "/v1/polymer",
            "/v1/assembly",
            "/v1/ligands",
            "/v1/chemcomp",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T08:14:11.000Z",
        "request_id": "69861c60-3d6a-4a14-a47d-366668b24d74"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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