Livechart Data Download API
This API allows the direct download of data.
At the moment the format provided is CSV (comma separated values). Future developments will
include more formats, and more options to build custom queries.
Examples
The service URL is
nds.iaea.org/relnsd/v1/data? followed by request parameters.
(please note that using 'v0' is the same as using 'v1' )
Here some
examples of data request parameters:
Xe-135 levels
Xe-135 gamma transitions
fields=ground_states&nuclides=all
try it
»
all ground states in the database
fields=cumulative_fy&parents=233u
try
it »
U-233 cumulative fission yields
fields=cumulative_fy&products=135xe
try
it »
cumulative fission yields producing Xe-135
fields=decay_rads&nuclides=135xe&rad_types=e
try it »
electrons (Auger and conversion) from Xe-135 decays
fields=bin_beta&nuclides=135xe&rad_types=bm
try it »
Beta and (anti)neutrino energy distributions from Xe-135 G.S. decays
Attention
- When importing into a spreadsheet, if you want to keep track of the trailing zeros, avoid the
automatic conversion of data types :
0.10 would become 0.1
- "Gamma transitions" and "gamma decay radiations" are different:
- "Gamma transitions" are the electromagnetic transitions between energy levels of the given
nuclide
- "Gamma decay radiations" are the gammas emitted, during the decay process, by the daughter(s) of
the given
nuclide
-
Data do not have a flag for metastable states. Use the fields "energy" or
"p_energy"
to distinguish between Ground State and Metastable.
-
When calling "fields=decay_rads&rad_types=g&nuclides...", be aware of the fields "p_energy" and
"decay". For
the same nuclide there can
be more than one decay mode, and, in case of metastable states, more states than the simple ground
state. This might result in gamma lines having the
same energy, but emitted by different decays
Jupyter lab
The
Livechart API works very effectively with
Python data analysis libraries (
pandas and
plotly in
these examples),
the first step to build models for Machine Learning.
Many examples, including 3D plotting, are detailed in this
Notebook
Attention
There have been cases in which the service returns an
HTTP Error 403: Forbidden
The workaround is to add an user agent to the request.
In
Python:
def lc_read_csv(url):
req = urllib.request.Request(url)
req.add_header('User-Agent',
'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0')
content = urllib.request.urlopen(req)
return content
in
Java:
protected String lc_read_csv(url){
URL murl = new URL(url);
URLConnection conn = murl.openConnection();
conn.setRequestProperty("User-Agent",
"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0");
BufferedReader br = new BufferedReader(
new InputStreamReader(conn.getInputStream()));
String inputLine;
StringBuffer sb = new StringBuffer();
while ((inputLine = br.readLine()) != null) {
sb.append(inputLine);
}
br.close();
return sb.toString();
}
For other languages, add the suggested user agent to the request using the avaliable function
API description
Service URL
The URL of the service is
nds.iaea.org/relnsd/v1/data? followed by a
chain of parameters linked by
&. A parameter is specified as
name=value
Parameters
fields
mandatory
Specifies which fields are fetched. At the moment, a predefined group of fields is avaliable.
Further development will allow the user to specify the list of fields.
Values
ground_states or levels or gammas or decay_rads or
cumulative_fy or independent_fy or bin_beta
Example
fields=cumulative_fy
See below for the description of the fields included in each group.
nuclides
Is mandatory
for ground_states, levels, gammas, decay_rads, and bin_beta
It has no effect on cumulative_fy or independent_fy
Restricts the retrieval to the specified nuclide
In this version of the API, only one nuclide can be specified
Values
nuclides=135xe (mass+element)
or
nuclides=all
allowed only for ground_states.
All ground states are returned
parents
Valid only for cumulative_fy and independent_fy
All the products for the specified parent are returned.
In this API version only one parent can be specified
Values
parents= 232th
or 233u or 235u or 238u
or 237np or 239pu or 241pu or
241am
products
Valid only for cumulative_fy and independent_fy
All the fission yields of this product, for any parent, are returned
In this API version only one product can be specified
Values
products=135xe (mass+element)
rad_types
Only for, and mandatory for,
decay_rads, and bin_beta
Only one value is allowed
Data are returned only for the specified type of radiation
In this API version only one radiation can be specified
Values for decay_rads
a bp bm g e x (α,
β-, β+, γ,
Auger and conversion electron, X-ray)
Values for bin_beta
bp bm (
β-, β+)
Full Example
fields=decay_rads&nuclides=135xe&rad_types=e
metastable_seqno
Only for
bin_beta
Only one value is allowed
Optional, specifies the sequential number for an excited
state
Values
1 2 3 ... (first metastable state, second, third, ... )
Full Example
fields=bin_beta&nuclides=135xe&rad_types=bm
metastable_seqno=1
This would retrieve the spectra for the decay of the 526.5 keV level of Xe-135
Fields content
- Blank space " " means value not given or not known
-
Energies are in keV, and intensities in %
Energies with +X shift
Level energies might include an unknown shift, e.g.
X+120.
To handle these cases, the energy is split in three fields:
energy_shift the X (or Y, Z, ...) part,
energy the numerical part,
ripl_shift the value of X assigned by
RIPL
(Reference Input Parameter Library - levels segment) using data from
Nubase (or blank " " when no assignment is made)
For example:
energy_shift, energy, unc, ripl_shift
X, 1440, , 1200
means that the ENSDF energy is X+1440 , that the uncertainity is left blank, and that RIPL assigns
X=1200. The absolute energy considering RIPL is 2640 keV
ripl_shift is empty when Ripl does not provide any value, then the level
energy cannot be assigned
The above is done for
levels and
ground_states
- The operator field contains AP for approximate, GT for greater than, LT ,...
- The operator, unc, and unit
fields contain
the operator, uncertainty, and units of the previous field, respectively: e.g.
half-life, operator_hl, unc_hl, unit_hl
-
For levels and ground_states, the three most
probable
decay modes are given
decay_1,decay_1_%,unc_1, ..._2, ..._3
-
The gammas set contains summary information on the start and end level of
the
transition.
The start_level_idx and start_level_idx fields
contain a sequential integer, providing a unique identifier for these levels
start_level_idx and start_level_idx can
be matched with
the idx field of the levels set, for the same
nuclide,
to obtain further data about the start and end levels.
-
For traceability, each file has at the end the field extraction date
Data sources
In the following
-
ENSDF: Evaluated Nuclear Strucure Data Files, April 2022 snapshot
The ENSDF_publication_cut-off and ENSDF_authors
fields contain the cut-off date for the publications considered in the ENSDF evaluation, and the authors
of the
ENSDF evaluation, respectively
-
RIPL: Reference Input Parameters Library (levels segment)
-
AM: I.Angeli, K.P. Marinova, Atomic Data and Nuclear Data Tables 99 (2013) DOI:10.1016/j.adt.2011.12.006
-
AME: 2020 Atomic Mass Evaluation AME20
-
N: 2020 Nubase Evaluation NUBASE20
-
NS: Table of Recommended Nuclear Magnetic Dipole Moments: Part I - Long-lived States indc-nds-0794, and
Table of Recommended Nuclear Magnetic Dipole Moments - Part II, Short-lived States
indc-nds-0816, and
Table of Nuclear Electric Quadrupole Moments indc-nds-0833
-
Beta spectra are otained using Betashape
X. Mougeot, Physical Review C 91,
055504
and Erratum Phys. Rev. C 92, 059902
(2015)
Uncertainties
Half-life uncertainity is given in ENSDF notation, referring to the significant digits.
For example
12.1 h 11 means 12.1 h ± 1.1 and
12.1 h 1 means 12.1 h ± 0.1
The Uncertainity of the Half-life in seconds is symmetrised
Field groups
ENSDF_publication_cut-off,
ENSDF_authors, and
extraction date are at the end of each row
ground_states
Properties on the nuclide and its ground state level
name | content | units | source |
---|
z | number of protons | | |
n | number of neutrons | | |
symbol | element symbol | | |
radius | charge radius | fm | AM |
unc_r | | | |
abundance | Abundance | Mole fraction % | N |
unc_a | | | |
energy_shift | unknown energy shift | X, Y, ... | ENSDF |
energy | energy | keV | ” |
unc_e | | | ” |
ripl_shift | energy shift from RIPL | keV | RIPL |
jp | Jπ | | ENSDF |
half_life | Half-life | | ” |
operator_hl | limits on H-l value | AP, GT, LT, ... | ” |
unc_hl | H-l unc in ENSDF style | | ” |
unit_hl | H-l units | | ” |
half_life_sec | H-l in seconds | seconds | ” |
unc_hls | H-l unc, symmetrized | | ” |
decay_{1 2 3} | 1st, 2nd, 3rd decay mode | | ” |
decay_{1 2 3}_% | branching for 100 decays | % | ” |
unc_{1 2 3} | | | ” |
isospin | isospin | | ” |
magnetic_dipole | magnetic dipole | μN | S |
unc_md | | | ” |
electric_quadrupole | electric quadrupole | barn | ” |
unc_eq | | | ” |
qbm | Q-value for β- decay | keV | AME |
unc_qb | | | ” |
qbm_n | β- n | keV | ” |
unc_qbmn | | | ” |
qa | α | keV | ” |
unc_qa | | | ” |
qec | electron capture | keV | ” |
unc_qec | | | ” |
sn | neutron separation energy | keV | ” |
unc_sn | | | ” |
sp | proton separation energy | keV | ” |
unc_sp | | | ” |
binding | binding energy / A | keV | ” |
unc_ba | | | ” |
atomic_mass | atomic mass | μAMU | ” |
unc_am | | | ” |
mass excess | mass excess | keV | ” |
unc_me | | | ” |
me_systematics | mass excess from systematics | | ” |
discovery | year of discovery | | N |
levels
Properties of the excited energy levels of a nuclide
The meaning and source of the fields are the same as the ground_state set. Additional fields are:
- jp_order : 1 indicates the 1st occurrence of that Jπ value, 2 the
2nd occurrence,
etc...
- idx : a sequential integer can that cna be matched with start_level_idx and
end_level_idx in the gamma set
name | content | units | source |
---|
z | number of protons | | ENSDF |
n | number of neutrons | | ” |
symbol | element symbol | | ” |
idx | | | ” |
energy_shift | unknown energy shift | X, Y, ... | ” |
energy | energy | keV | ” |
unc_e | | | ” |
ripl_shift | energy shift from RIPL | keV | ” |
jp | Jπ | | ” |
jp_order | | | ” |
half_life | Half-life | | ” |
operator_hl | limits on H-l value | AP, GT, LT, ... | ” |
unc_hl | H-l unc in ENSDF style | | ” |
unit_hl | H-l units | | ” |
half_life_sec | H-l in seconds | seconds | ” |
unc_hls | H-l unc, symmetrized | | ” |
decay_{1 2 3} | 1st, 2nd, 3rd decay mode | | ” |
decay_{1 2 3}_% | branching for 100 decays | % | ” |
unc_{1 2 3} | | | ” |
isospin | isospin | | ” |
magnetic_dipole | magnetic dipole | μN | ” |
unc_mn | | | ” |
electric_quadrupole | electric quadrupole | barn | ” |
unc_eq | | | ” |
gammas
Properties of the electromagnetic transitions between energy levels of the nuclide
In the following :
- RTPW stands for Reduced Electric (Magnetic) Transition Probabilities in Weisskopf Units
-
Energies are in keV
- intensities are in %
- the source is ENSDF
name | content |
---|
z | number of protons | |
n | number of neutrons | |
symbol | element symbol | |
start_level_idx | start level index | |
start_level_energy | start level energy | |
unc_sle | | |
start_level_jp | start level Jπ | |
end_level_idx | end level index | |
end_level_energy | end level energy | |
unc_ele | | |
end_level_jp | end level Jπ | |
gamma_idx | γ index (within the start level) | |
energy | energy | |
unc_en | | |
relative_intensity | relative intensity | |
unc_ri | | |
multipolarity | multipolarity | |
mixing_ratio | mixing ratio | |
unc_mr | | |
b_e1 | RTPW - E1 multipolarity | |
unc_be1 | | |
b_e2 | RTPW - E2 multipolarity | |
unc_be2 | | |
b_m1 | RTPW - M1 multipolarity | |
unc_bm1 | | |
b_m2 | RTPW - M2 multipolarity | |
unc_bm2 | | |
decay_rads
Properties of the radiations emitted by the daughter(s) of the nuclide that decays
In the following :
-
Energies are in keV
- intensities are in %
- the source is ENSDF
Fields common to all decay radiation types
name | content |
---|
energy | radiation energy | |
unc_en | | |
intensity | radiation intensity | |
unc_i | | |
p_z | z of the parent | |
p_n | n of the parent | |
p_symbol | element of the parent | |
p_energy_shift | energy shift of the parent | |
p_energy | energy of the parent | |
unc_pe | | |
jp | Jπ of the parent | |
half_life | half-life of the parent | |
operator_hl | limits on H-l | |
unc_hl | H-l unc in ENSDF style | |
unit_hl | H-l units | |
half_life_sec | H-l seconds | |
unc_hls | H-l unc, symmetrized | |
decay | decay mode | |
decay_% | branching | |
unc_d | | |
q | Q-value | |
unc_q | | |
d_z | z of the daughter | |
d_n | n of the daughter | |
d_symbol | element of the daughter | |
• α
radiations
name | content |
---|
daughter_level_hl | fed level H-l [s] | |
daughter_level_energy | fed level energy | |
hindrance_factor | hindrance factor | |
unc_hf | | |
• X-ray, electrons
name | content |
---|
type | X for X-ray, AU for Auger, or CE for conversion | |
shell | Siegbahn notation | |
• β radiations
name | content |
---|
mean_energy | mean energy | |
unc_me | | |
intensity_beta | intensity for e- (e+) emission | |
unc_ib | | |
daughter_level_hl | daughter's excited state Half-life [s] | |
daughter_level_energy | daughter's excited state energy | |
max_energy | only for β-, end-point energy | |
unc_me | | |
energy_EC | only for β+, energy available for Electron Capture | |
unc_eec | | |
intensity_EC | only for β+, intensity of EC | |
unc_ie | | |
log_ft | log ft | |
unc_lf | undefined | |
transition_type | | |
(anti_)nu_mean_energy | transition type | |
unc_(ame)nme | (anti) neutrino mean energy | |
• γ radiations
name | content |
---|
start_level_hl | Half-life of the initial level | |
start_level_energy | energy of the initial level | |
end_level_energy | energy of the final level | |
multipolarity | multipolarity of the transition | |
mixing_ratio | mixing ratio | |
unc_mr | | |
conversion_coeff | conversion coefficient (total) | |
unc_cc | | |
bin_beta
• β+/-
and ν / anti ν spectra
Spectra are obtained using
Betashape code
name | content |
---|
p_z | z of the parent | |
p_n | n of the parent | |
p_symbol | element of the parent | |
p_energy | energy of the parent | |
d_z | z of the daughter | |
d_n | n of the daughter | |
d_symbol | element of the daughter | |
bin_en | bin energy | |
dn_de | dn/de | |
unc_dn_de | uncertainty | |
dn_de_nu | dn/de nu or anti nu | |
unc_dn_de_nu | uncertainty | |
extraction_date | date of retrieval | |
Error codes
When no data are retrieved, a numeric code is returned
code | meaning |
---|
0 | the request is vaild, but there are no data fufilling the conditions | |
1 | "fields" parameter is not given | |
2 | "nuclides" parameter is not given but is required for the given "fields" | |
3 | "fields" parameter is misspelled | |
4 | "parents" o "products" not given for fission yields | |
5 | "rad_types" not valid | |
6 | unknown error | |
Feedback
Please address any feedback to
NDS contact point