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:

fields=levels&nuclides=135xe try it »

Xe-135 levels

fields=gammas&nuclides=135xe try it »

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

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 1^st occurrence of that J^π value, 2 the 2^nd occurrence, etc...
idx : a sequential integer can that cna be matched with start_level_idx and end_level_idx in the gamma set

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

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

• α radiations

• X-ray, electrons

• β radiations

• γ radiations

bin_beta

• β^+/- and ν / anti ν spectra

Spectra are obtained using Betashape code

Error codes

When no data are retrieved, a numeric code is returned

Feedback

Please address any feedback to NDS contact point