order enum random is a seeded shuffle of the matches; atomicNumber is ascending Z.
default: random
allowed: random | atomicNumber
example: order=atomicNumber
Periodic Table & Chemical Elements API
REAL DATAAll 118 chemical elements from PubChem — masses, states, configurations, CPK colours and oxidation states, plus a ready-to-render periodic-table grid.
Authoritative reference data or standards computation
- Base URL
- /api/elements
- Category
- Developer Tools
- Capabilities
- 3 routes Seedable
- Last updated
GET /api/elements
Order defaults to random (seeded, so a fixed seed is a reproducible draw); order=atomicNumber gives the canonical order.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 13
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
order | enum | default: random allowed: random | atomicNumber example: atomicNumber | random is a seeded shuffle of the matches; atomicNumber is ascending Z. |
groupBlock | enum | default: any allowed: actinide | alkali-metal | alkaline-earth-metal | halogen | lanthanide | metalloid | noble-gas | nonmetal | post-transition-metal | transition-metal | any example: noble-gas | Only elements in this PubChem category, as a URL-safe slug (actinide, alkali-metal, alkaline-earth-metal, halogen, lanthanide, metalloid, noble-gas, nonmetal, post-transition-metal, transition-metal). |
block | enum | default: any allowed: s | p | d | f | any example: f | Only elements in this block. Derived from the IUPAC layout, not a PubChem column. |
state | enum | default: any allowed: solid | liquid | gas | any example: gas | Only elements in this state at standard conditions. Includes the 9 superheavies whose state PubChem only predicts — check standardStatePredicted on each record. |
group | int | allowed: 1 – 18 example: 17 | Only elements in this IUPAC group. The 30 f-block elements have no group number and never match. |
period | int | allowed: 1 – 7 example: 2 | Only elements in this period. |
minMass | float | allowed: 0 – 400 example: 200 | Only elements with an atomic mass ≥ this value. |
maxMass | float | allowed: 0 – 400 example: 20 | Only elements with an atomic mass ≤ this value. |
minElectronegativity | float | allowed: 0 – 4 example: 3 | Only elements with a Pauling electronegativity ≥ this value. The 23 elements without a published value never match. |
maxElectronegativity | float | allowed: 0 – 4 example: 1 | Only elements with a Pauling electronegativity ≤ this value; elements without a published value never match. |
era | enum | default: any allowed: ancient | dated | any example: ancient | ancient selects exactly the 13 elements PubChem records as "Ancient"; dated selects the 105 with a numeric year. |
discoveredFrom | int | allowed: 1000 – 2100 example: 1900 | Only elements with a discovery year ≥ this. The 13 "Ancient" elements carry no year and are never matched — use era=ancient for those. |
discoveredTo | int | allowed: 1000 – 2100 example: 1800 | Only elements with a discovery year ≤ this; the "Ancient" elements carry no year and are never matched. |
groupBlock enum Only elements in this PubChem category, as a URL-safe slug (actinide, alkali-metal, alkaline-earth-metal, halogen, lanthanide, metalloid, noble-gas, nonmetal, post-transition-metal, transition-metal).
default: any
allowed: actinide | alkali-metal | alkaline-earth-metal | halogen | lanthanide | metalloid | noble-gas | nonmetal | post-transition-metal | transition-metal | any
example: groupBlock=noble-gas
block enum Only elements in this block. Derived from the IUPAC layout, not a PubChem column.
default: any
allowed: s | p | d | f | any
example: block=f
state enum Only elements in this state at standard conditions. Includes the 9 superheavies whose state PubChem only predicts — check standardStatePredicted on each record.
default: any
allowed: solid | liquid | gas | any
example: state=gas
group int Only elements in this IUPAC group. The 30 f-block elements have no group number and never match.
allowed: 1 – 18
example: group=17
period int Only elements in this period.
allowed: 1 – 7
example: period=2
minMass float Only elements with an atomic mass ≥ this value.
allowed: 0 – 400
example: minMass=200
maxMass float Only elements with an atomic mass ≤ this value.
allowed: 0 – 400
example: maxMass=20
minElectronegativity float Only elements with a Pauling electronegativity ≥ this value. The 23 elements without a published value never match.
allowed: 0 – 4
example: minElectronegativity=3
maxElectronegativity float Only elements with a Pauling electronegativity ≤ this value; elements without a published value never match.
allowed: 0 – 4
example: maxElectronegativity=1
era enum ancient selects exactly the 13 elements PubChem records as "Ancient"; dated selects the 105 with a numeric year.
default: any
allowed: ancient | dated | any
example: era=ancient
discoveredFrom int Only elements with a discovery year ≥ this. The 13 "Ancient" elements carry no year and are never matched — use era=ancient for those.
allowed: 1000 – 2100
example: discoveredFrom=1900
discoveredTo int Only elements with a discovery year ≤ this; the "Ancient" elements carry no year and are never matched.
allowed: 1000 – 2100
example: discoveredTo=1800
Universal parameters Shared response and formatting options 7
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: 10 allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to 10. |
seed | int | example: 42 | Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed). |
fields | list | example: atomicNumber,symbol | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: discoveryRecord | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to 10.
default: 10
allowed: 1 – 100
example: count=3
seed int Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
example: seed=42
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=atomicNumber,symbol
exclude list Return all fields except these (comma-separated).
example: exclude=discoveryRecord
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 23
| Field | Type | Description | Example |
|---|---|---|---|
atomicNumber | integer | Proton count, 1–118. | 26 |
symbol | string | IUPAC chemical symbol. | Fe |
name | string | IUPAC English name, spelled as PubChem publishes it. | Iron |
atomicMass | float | Relative atomic mass. For the 34 elements with no IUPAC standard atomic weight this is the mass of the longest-lived isotope, not an abundance-weighted average — check massIsMostStableIsotope before treating it as a measurement. | 55.84 |
massIsMostStableIsotope | boolean | True where the element has no CIAAW standard atomic weight (Tc, Pm and everything from Po upward except Th, Pa and U). Derived by randomapi.dev, not published by PubChem. | false |
group nullable | integer | IUPAC group 1–18; null across the f-block, which IUPAC does not number. Derived from the atomic number, not published by PubChem. | 8 |
period | integer | Period 1–7. Derived from the atomic number, not published by PubChem. | 4 |
block | string | s, p, d or f. Derived from the layout, not published by PubChem. | d |
groupBlock | string | PubChem's own category string, e.g. Transition metal or Noble gas. | Transition metal |
standardState | string | solid, liquid or gas at standard conditions. | solid |
standardStatePredicted | boolean | True for the 9 superheavy elements whose state PubChem records as "Expected to be a …" rather than measured. | false |
electronConfiguration | string | Ground-state configuration; carries PubChem's own "(predicted)" marker where PubChem marks it. | [Ar]4s2 3d6 |
electronegativity nullable | float | Pauling electronegativity; null where PubChem publishes none. | 1.83 |
atomicRadius nullable | integer | Atomic radius in picometres as published by PubChem; null where none. | 194 |
ionizationEnergy nullable | float | First ionization energy in electronvolts; null where none. | 7.902 |
electronAffinity nullable | float | Electron affinity in electronvolts; null where none. | 0.163 |
oxidationStates | string[] | Common oxidation states in PubChem's order; empty where PubChem lists none. | ["+3","+2"] |
meltingPoint nullable | float | Melting point in kelvin; null where none. | 1811 |
boilingPoint nullable | float | Boiling point in kelvin; null where none. | 3134 |
density nullable | float | Density in g/cm³ (gases at STP); null where none. | 7.874 |
cpkHexColor nullable | string | PubChem's CPK colour as "#RRGGBB"; null for the 10 elements PubChem leaves blank. | #E06633 |
yearDiscovered nullable | integer | Discovery year, or null for the 13 elements PubChem records as "Ancient" instead of a year. | 1766 |
discoveryRecord | string | PubChem's literal year-discovered value, e.g. "1766" or "Ancient". | 1766 |
atomicNumber integer Proton count, 1–118.
example: 26
symbol string IUPAC chemical symbol.
example: Fe
name string IUPAC English name, spelled as PubChem publishes it.
example: Iron
atomicMass float Relative atomic mass. For the 34 elements with no IUPAC standard atomic weight this is the mass of the longest-lived isotope, not an abundance-weighted average — check massIsMostStableIsotope before treating it as a measurement.
example: 55.84
massIsMostStableIsotope boolean True where the element has no CIAAW standard atomic weight (Tc, Pm and everything from Po upward except Th, Pa and U). Derived by randomapi.dev, not published by PubChem.
example: false
group integer nullable IUPAC group 1–18; null across the f-block, which IUPAC does not number. Derived from the atomic number, not published by PubChem.
example: 8
period integer Period 1–7. Derived from the atomic number, not published by PubChem.
example: 4
block string s, p, d or f. Derived from the layout, not published by PubChem.
example: d
groupBlock string PubChem's own category string, e.g. Transition metal or Noble gas.
example: Transition metal
standardState string solid, liquid or gas at standard conditions.
example: solid
standardStatePredicted boolean True for the 9 superheavy elements whose state PubChem records as "Expected to be a …" rather than measured.
example: false
electronConfiguration string Ground-state configuration; carries PubChem's own "(predicted)" marker where PubChem marks it.
example: [Ar]4s2 3d6
electronegativity float nullable Pauling electronegativity; null where PubChem publishes none.
example: 1.83
atomicRadius integer nullable Atomic radius in picometres as published by PubChem; null where none.
example: 194
ionizationEnergy float nullable First ionization energy in electronvolts; null where none.
example: 7.902
electronAffinity float nullable Electron affinity in electronvolts; null where none.
example: 0.163
oxidationStates string[] Common oxidation states in PubChem's order; empty where PubChem lists none.
example: ["+3","+2"]
meltingPoint float nullable Melting point in kelvin; null where none.
example: 1811
boilingPoint float nullable Boiling point in kelvin; null where none.
example: 3134
density float nullable Density in g/cm³ (gases at STP); null where none.
example: 7.874
cpkHexColor string nullable PubChem's CPK colour as "#RRGGBB"; null for the 10 elements PubChem leaves blank.
example: #E06633
yearDiscovered integer nullable Discovery year, or null for the 13 elements PubChem records as "Ancient" instead of a year.
example: 1766
discoveryRecord string PubChem's literal year-discovered value, e.g. "1766" or "Ancient".
example: 1766
Documented examples
Build-generated requests and complete responses 5 Ten random elements /api/elements
{
"data": [
{
"atomicNumber": 95,
"symbol": "Am",
"name": "Americium",
"atomicMass": 243.06138,
"massIsMostStableIsotope": true,
"group": null,
"period": 7,
"block": "f",
"groupBlock": "Actinide",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[Rn]7s2 5f7",
"electronegativity": 1.3,
"atomicRadius": 244,
"ionizationEnergy": 5.993,
"electronAffinity": null,
"oxidationStates": [
"+6",
"+5",
"+4",
"+3"
],
"meltingPoint": 1449,
"boilingPoint": 2284,
"density": 13.69,
"cpkHexColor": "#545CF2",
"yearDiscovered": 1944,
"discoveryRecord": "1944"
},
{
"atomicNumber": 73,
"symbol": "Ta",
"name": "Tantalum",
"atomicMass": 180.9479,
"massIsMostStableIsotope": false,
"group": 5,
"period": 6,
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} The noble gases in atomic order /api/elements?groupBlock=noble-gas&order=atomicNumber&count=10
{
"data": [
{
"atomicNumber": 2,
"symbol": "He",
"name": "Helium",
"atomicMass": 4.0026,
"massIsMostStableIsotope": false,
"group": 18,
"period": 1,
"block": "s",
"groupBlock": "Noble gas",
"standardState": "gas",
"standardStatePredicted": false,
"electronConfiguration": "1s2",
"electronegativity": null,
"atomicRadius": 140,
"ionizationEnergy": 24.587,
"electronAffinity": null,
"oxidationStates": [
"0"
],
"meltingPoint": 0.95,
"boilingPoint": 4.22,
"density": 0.0001785,
"cpkHexColor": "#D9FFFF",
"yearDiscovered": 1868,
"discoveryRecord": "1868"
},
{
"atomicNumber": 10,
"symbol": "Ne",
"name": "Neon",
"atomicMass": 20.18,
"massIsMostStableIsotope": false,
"group": 18,
"period": 2,
"block": "p",
"groupBlock": "Noble gas",
"standardState": "gas",
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} Period 2 from lithium to neon /api/elements?period=2&order=atomicNumber&count=8
{
"data": [
{
"atomicNumber": 3,
"symbol": "Li",
"name": "Lithium",
"atomicMass": 7,
"massIsMostStableIsotope": false,
"group": 1,
"period": 2,
"block": "s",
"groupBlock": "Alkali metal",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[He]2s1",
"electronegativity": 0.98,
"atomicRadius": 182,
"ionizationEnergy": 5.392,
"electronAffinity": 0.618,
"oxidationStates": [
"+1"
],
"meltingPoint": 453.65,
"boilingPoint": 1615,
"density": 0.534,
"cpkHexColor": "#CC80FF",
"yearDiscovered": 1817,
"discoveryRecord": "1817"
},
{
"atomicNumber": 4,
"symbol": "Be",
"name": "Beryllium",
"atomicMass": 9.012183,
"massIsMostStableIsotope": false,
"group": 2,
"period": 2,
"block": "s",
"groupBlock": "Alkaline earth metal",
"standardState": "solid",
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} The elements known since antiquity /api/elements?era=ancient&order=atomicNumber&count=20
{
"data": [
{
"atomicNumber": 6,
"symbol": "C",
"name": "Carbon",
"atomicMass": 12.011,
"massIsMostStableIsotope": false,
"group": 14,
"period": 2,
"block": "p",
"groupBlock": "Nonmetal",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[He]2s2 2p2",
"electronegativity": 2.55,
"atomicRadius": 170,
"ionizationEnergy": 11.26,
"electronAffinity": 1.263,
"oxidationStates": [
"+4",
"+2",
"-4"
],
"meltingPoint": 3823,
"boilingPoint": 4098,
"density": 2.267,
"cpkHexColor": "#909090",
"yearDiscovered": null,
"discoveryRecord": "Ancient"
},
{
"atomicNumber": 13,
"symbol": "Al",
"name": "Aluminum",
"atomicMass": 26.981538,
"massIsMostStableIsotope": false,
"group": 13,
"period": 3,
"block": "p",
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} Reproducible ten-element quiz draw /api/elements?seed=7&count=10
{
"data": [
{
"atomicNumber": 117,
"symbol": "Ts",
"name": "Tennessine",
"atomicMass": 294.211,
"massIsMostStableIsotope": true,
"group": 17,
"period": 7,
"block": "p",
"groupBlock": "Halogen",
"standardState": "solid",
"standardStatePredicted": true,
"electronConfiguration": "[Rn]7s2 7p5 5f14 6d10 (predicted)",
"electronegativity": null,
"atomicRadius": null,
"ionizationEnergy": null,
"electronAffinity": null,
"oxidationStates": [
"+5",
"+3",
"+1",
"-1"
],
"meltingPoint": null,
"boilingPoint": null,
"density": null,
"cpkHexColor": null,
"yearDiscovered": 2010,
"discoveryRecord": "2010"
},
{
"atomicNumber": 101,
"symbol": "Md",
"name": "Mendelevium",
"atomicMass": 258.09843,
"massIsMostStableIsotope": true,
"group": null,
"period": 7,
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} GET /api/elements/lookup
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 1
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
element
required
| string | allowed: 1 – 20 example: Fe | Chemical symbol (Fe), English name (iron) or atomic number (26). Case-insensitive. |
element string required Chemical symbol (Fe), English name (iron) or atomic number (26). Case-insensitive.
allowed: 1 – 20
example: element=Fe
Universal parameters Shared response and formatting options 4
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
fields | list | example: atomicNumber,symbol | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: discoveryRecord | Return all fields except these (comma-separated). |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=atomicNumber,symbol
exclude list Return all fields except these (comma-separated).
example: exclude=discoveryRecord
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 23
| Field | Type | Description | Example |
|---|---|---|---|
atomicNumber | integer | Proton count, 1–118. | 26 |
symbol | string | IUPAC chemical symbol. | Fe |
name | string | IUPAC English name, spelled as PubChem publishes it. | Iron |
atomicMass | float | Relative atomic mass. For the 34 elements with no IUPAC standard atomic weight this is the mass of the longest-lived isotope, not an abundance-weighted average — check massIsMostStableIsotope before treating it as a measurement. | 55.84 |
massIsMostStableIsotope | boolean | True where the element has no CIAAW standard atomic weight (Tc, Pm and everything from Po upward except Th, Pa and U). Derived by randomapi.dev, not published by PubChem. | false |
group nullable | integer | IUPAC group 1–18; null across the f-block, which IUPAC does not number. Derived from the atomic number, not published by PubChem. | 8 |
period | integer | Period 1–7. Derived from the atomic number, not published by PubChem. | 4 |
block | string | s, p, d or f. Derived from the layout, not published by PubChem. | d |
groupBlock | string | PubChem's own category string, e.g. Transition metal or Noble gas. | Transition metal |
standardState | string | solid, liquid or gas at standard conditions. | solid |
standardStatePredicted | boolean | True for the 9 superheavy elements whose state PubChem records as "Expected to be a …" rather than measured. | false |
electronConfiguration | string | Ground-state configuration; carries PubChem's own "(predicted)" marker where PubChem marks it. | [Ar]4s2 3d6 |
electronegativity nullable | float | Pauling electronegativity; null where PubChem publishes none. | 1.83 |
atomicRadius nullable | integer | Atomic radius in picometres as published by PubChem; null where none. | 194 |
ionizationEnergy nullable | float | First ionization energy in electronvolts; null where none. | 7.902 |
electronAffinity nullable | float | Electron affinity in electronvolts; null where none. | 0.163 |
oxidationStates | string[] | Common oxidation states in PubChem's order; empty where PubChem lists none. | ["+3","+2"] |
meltingPoint nullable | float | Melting point in kelvin; null where none. | 1811 |
boilingPoint nullable | float | Boiling point in kelvin; null where none. | 3134 |
density nullable | float | Density in g/cm³ (gases at STP); null where none. | 7.874 |
cpkHexColor nullable | string | PubChem's CPK colour as "#RRGGBB"; null for the 10 elements PubChem leaves blank. | #E06633 |
yearDiscovered nullable | integer | Discovery year, or null for the 13 elements PubChem records as "Ancient" instead of a year. | 1766 |
discoveryRecord | string | PubChem's literal year-discovered value, e.g. "1766" or "Ancient". | 1766 |
atomicNumber integer Proton count, 1–118.
example: 26
symbol string IUPAC chemical symbol.
example: Fe
name string IUPAC English name, spelled as PubChem publishes it.
example: Iron
atomicMass float Relative atomic mass. For the 34 elements with no IUPAC standard atomic weight this is the mass of the longest-lived isotope, not an abundance-weighted average — check massIsMostStableIsotope before treating it as a measurement.
example: 55.84
massIsMostStableIsotope boolean True where the element has no CIAAW standard atomic weight (Tc, Pm and everything from Po upward except Th, Pa and U). Derived by randomapi.dev, not published by PubChem.
example: false
group integer nullable IUPAC group 1–18; null across the f-block, which IUPAC does not number. Derived from the atomic number, not published by PubChem.
example: 8
period integer Period 1–7. Derived from the atomic number, not published by PubChem.
example: 4
block string s, p, d or f. Derived from the layout, not published by PubChem.
example: d
groupBlock string PubChem's own category string, e.g. Transition metal or Noble gas.
example: Transition metal
standardState string solid, liquid or gas at standard conditions.
example: solid
standardStatePredicted boolean True for the 9 superheavy elements whose state PubChem records as "Expected to be a …" rather than measured.
example: false
electronConfiguration string Ground-state configuration; carries PubChem's own "(predicted)" marker where PubChem marks it.
example: [Ar]4s2 3d6
electronegativity float nullable Pauling electronegativity; null where PubChem publishes none.
example: 1.83
atomicRadius integer nullable Atomic radius in picometres as published by PubChem; null where none.
example: 194
ionizationEnergy float nullable First ionization energy in electronvolts; null where none.
example: 7.902
electronAffinity float nullable Electron affinity in electronvolts; null where none.
example: 0.163
oxidationStates string[] Common oxidation states in PubChem's order; empty where PubChem lists none.
example: ["+3","+2"]
meltingPoint float nullable Melting point in kelvin; null where none.
example: 1811
boilingPoint float nullable Boiling point in kelvin; null where none.
example: 3134
density float nullable Density in g/cm³ (gases at STP); null where none.
example: 7.874
cpkHexColor string nullable PubChem's CPK colour as "#RRGGBB"; null for the 10 elements PubChem leaves blank.
example: #E06633
yearDiscovered integer nullable Discovery year, or null for the 13 elements PubChem records as "Ancient" instead of a year.
example: 1766
discoveryRecord string PubChem's literal year-discovered value, e.g. "1766" or "Ancient".
example: 1766
Documented examples
Build-generated requests and complete responses 3 By symbol /api/elements/lookup?element=Fe
{
"data": {
"atomicNumber": 26,
"symbol": "Fe",
"name": "Iron",
"atomicMass": 55.84,
"massIsMostStableIsotope": false,
"group": 8,
"period": 4,
"block": "d",
"groupBlock": "Transition metal",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[Ar]4s2 3d6",
"electronegativity": 1.83,
"atomicRadius": 194,
"ionizationEnergy": 7.902,
"electronAffinity": 0.163,
"oxidationStates": [
"+3",
"+2"
],
"meltingPoint": 1811,
"boilingPoint": 3134,
"density": 7.874,
"cpkHexColor": "#E06633",
"yearDiscovered": null,
"discoveryRecord": "Ancient"
},
"meta": {
"endpoint": "elements",
"route": "/lookup",
"params": {
"element": "Fe"
},
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} By name /api/elements/lookup?element=iron
{
"data": {
"atomicNumber": 26,
"symbol": "Fe",
"name": "Iron",
"atomicMass": 55.84,
"massIsMostStableIsotope": false,
"group": 8,
"period": 4,
"block": "d",
"groupBlock": "Transition metal",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[Ar]4s2 3d6",
"electronegativity": 1.83,
"atomicRadius": 194,
"ionizationEnergy": 7.902,
"electronAffinity": 0.163,
"oxidationStates": [
"+3",
"+2"
],
"meltingPoint": 1811,
"boilingPoint": 3134,
"density": 7.874,
"cpkHexColor": "#E06633",
"yearDiscovered": null,
"discoveryRecord": "Ancient"
},
"meta": {
"endpoint": "elements",
"route": "/lookup",
"params": {
"element": "iron"
},
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} By atomic number /api/elements/lookup?element=26
{
"data": {
"atomicNumber": 26,
"symbol": "Fe",
"name": "Iron",
"atomicMass": 55.84,
"massIsMostStableIsotope": false,
"group": 8,
"period": 4,
"block": "d",
"groupBlock": "Transition metal",
"standardState": "solid",
"standardStatePredicted": false,
"electronConfiguration": "[Ar]4s2 3d6",
"electronegativity": 1.83,
"atomicRadius": 194,
"ionizationEnergy": 7.902,
"electronAffinity": 0.163,
"oxidationStates": [
"+3",
"+2"
],
"meltingPoint": 1811,
"boilingPoint": 3134,
"density": 7.874,
"cpkHexColor": "#E06633",
"yearDiscovered": null,
"discoveryRecord": "Ancient"
},
"meta": {
"endpoint": "elements",
"route": "/lookup",
"params": {
"element": "26"
},
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} GET /api/elements/table
The conventional layout: periods 1-7 as rows 1-7, with the f-block lifted out and printed below as rows 8 and 9, columns 3-17.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 1
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
gridValues | enum | default: atomicNumber allowed: atomicNumber | symbol example: symbol | What each occupied grid cell contains. Empty cells are null either way. |
gridValues enum What each occupied grid cell contains. Empty cells are null either way.
default: atomicNumber
allowed: atomicNumber | symbol
example: gridValues=symbol
Universal parameters Shared response and formatting options 4
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
fields | list | example: layout,grid | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: placeholders | Return all fields except these (comma-separated). |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=layout,grid
exclude list Return all fields except these (comma-separated).
example: exclude=placeholders
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 4
| Field | Type | Description | Example |
|---|---|---|---|
layout | object | Grid dimensions and where the f-block strip sits. | {"rows":9,"columns":18,"mainRows":7,"fBlockRows":[8,9],"fBlockColumns":[3,17]} |
grid | object[] | One entry per grid row: the row number and an array of `layout.columns` cells, null in every empty position and the `gridValues` value elsewhere. | [{"row":1,"cells":[1,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,2]}] |
cells | object[] | Every element placed in the grid: atomic number, symbol, name, row, column, group, period, block, PubChem category and CPK colour. | [{"atomicNumber":26,"symbol":"Fe","name":"Iron","row":4,"column":8,"group":8,"period":4,"block":"d","groupBlock":"Transition metal","cpkHexColor":"#E06633"}] |
placeholders | object[] | The two cells the main body leaves behind because the f-block is printed separately — row 6 column 3 stands for elements 57-71, row 7 column 3 for 89-103. | [{"row":6,"column":3,"label":"57–71","block":"f","firstAtomicNumber":57,"lastAtomicNumber":71}] |
layout object Grid dimensions and where the f-block strip sits.
example: {"rows":9,"columns":18,"mainRows":7,"fBlockRows":[8,9],"fBlockColumns":[3,17]}
grid object[] One entry per grid row: the row number and an array of `layout.columns` cells, null in every empty position and the `gridValues` value elsewhere.
example: [{"row":1,"cells":[1,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,2]}]
cells object[] Every element placed in the grid: atomic number, symbol, name, row, column, group, period, block, PubChem category and CPK colour.
example: [{"atomicNumber":26,"symbol":"Fe","name":"Iron","row":4,"column":8,"group":8,"period":4,"block":"d","groupBlock":"Transition metal","cpkHexColor":"#E06633"}]
placeholders object[] The two cells the main body leaves behind because the f-block is printed separately — row 6 column 3 stands for elements 57-71, row 7 column 3 for 89-103.
example: [{"row":6,"column":3,"label":"57–71","block":"f","firstAtomicNumber":57,"lastAtomicNumber":71}]
Documented examples
Build-generated requests and complete responses 2 Atomic numbers in every cell /api/elements/table
{
"data": {
"layout": {
"rows": 9,
"columns": 18,
"mainRows": 7,
"fBlockRows": [
8,
9
],
"fBlockColumns": [
3,
17
]
},
"grid": [
{
"row": 1,
"cells": [
1,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
2
]
},
{
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} Chemical symbols in every cell /api/elements/table?gridValues=symbol
{
"data": {
"layout": {
"rows": 9,
"columns": 18,
"mainRows": 7,
"fBlockRows": [
8,
9
],
"fBlockColumns": [
3,
17
]
},
"grid": [
{
"row": 1,
"cells": [
"H",
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
null,
"He"
]
},
{
…
"generatedAt": "2026-09-15T17:32:36.000Z"
}
} About this API
Coverage & behavior
The full periodic table as JSON, from the US National Library of Medicine's PubChem periodic-table service — a public-domain source, pinned by SHA-256 and re-verified by a committed parity script.
/table is the route most projects actually want: the conventional printed layout as a 9×18 grid plus one placed cell per element with its row, column, group, period, block and CPK colour. The f-block is where naive "18×7" tables break: the 30 lanthanides and actinides are lifted out and printed below as two further rows of 15, and this API returns them that way, with the two placeholder cells the main body leaves behind.
Honest about what PubChem actually publishes. Group, period, block and the grid coordinates are not upstream columns — they are computed here from the atomic number using the standard IUPAC layout and labelled as derivations. PubChem records 13 elements as the literal string Ancient rather than a year, so yearDiscovered is null for those and the upstream string survives in discoveryRecord; the era filter selects them explicitly and the discoveredFrom/discoveredTo filters — which need a number — deliberately never match them. 9 superheavy elements have a predicted standard state upstream ("Expected to be a Solid"); standardState normalises the value and standardStatePredicted tells you it is a prediction. And for the 34 elements with no IUPAC standard atomic weight, atomicMass is one isotope's mass, flagged by massIsMostStableIsotope.
Filters genuinely filter across all 118 rows: groupBlock, block, state, group, period, mass and electronegativity ranges. Elements PubChem leaves blank are excluded from a range filter rather than silently counted as zero — 23 elements have no electronegativity at all.
The list route's order is seeded, so ?order=random&seed=7 is a reproducible quiz draw and ?order=atomicNumber is the canonical order.
Use it for
- Render an interactive periodic table with correct f-block placement and CPK colours
- Reproducible chemistry quiz and flashcard fixtures from a fixed seed
- Look up an element by symbol, name or atomic number in one request
- Filter elements by block, state or electronegativity for teaching material
Frequently asked questions
Does this API give me the periodic table layout, not just a list?
Yes — GET /api/elements/table returns a 9×18 grid of atomic numbers plus every element's row, column, group, period, block and CPK colour, with the f-block on its own two rows of 15.
Where does the element data come from?
PubChem's periodic-table service, run by the US National Center for Biotechnology Information. It is a US-government work with no restrictions on use, including commercial use; the payload is pinned by SHA-256.
Why is yearDiscovered null for iron and gold?
PubChem records 13 long-known elements as the literal string "Ancient" rather than a year. Rather than invent a date, yearDiscovered is null and discoveryRecord keeps the upstream string; ?era=ancient selects exactly those rows.
Are the atomic masses measured values?
For 84 elements yes — they are IUPAC standard atomic weights. For the other 34, which have no standard atomic weight, the figure is the relative atomic mass of the longest-lived isotope; massIsMostStableIsotope is true on exactly those rows.
Can I look up an element by symbol and by name?
/api/elements/lookup?element=Fe, ?element=iron and ?element=26 all resolve to the same record. Anything else is an explicit 404, never a nearest match.
Standards & references
Related APIs
Unit Conversion API REAL DATA
Deterministic unit conversion across 14 categories — length, mass, pressure, energy, power, force, angle, time and more — with exact standard factors.
Random Color API MOCK DATA
Random colors in hex, RGB and HSL with hue and luminosity filters, nearest CSS color names and WCAG contrast text — plus deterministic color-scheme palettes.
NATO Phonetic Alphabet API REAL DATA
The official ICAO/NATO phonetic alphabet — all 36 characters with code words and pronunciations, plus a /spell route that spells out any text.
Check Digit Validator and Calculator API REAL DATA
Validate or compute check digits for Luhn, GTIN/EAN/UPC, ISBN, ISSN, IMEI, ISIN, LEI, VIN, NPI, ABA and ISO 7064 — one cited algorithm per scheme.