REST API Reference

Below is a list of all public API endpoints. Examples shown are in python (using the requests module). However, any software or command-line tool that can access APIs like this (curl, wget, etc) can also be used.

Basis set names, formats, and reference formats are case insensitive.

Note that the API is read-only, and does not allow for uploading or modifying data.

Note about headers

Additional header information (user agent, email) are optional. However, if you would like to share who you are or what you are doing, feel free to add these fields. We will not use the email for any purpose other than to notify you if your scripts are broken and causing us problems.

Any data collected from user agent or email will not be shared outside of MolSSI, other than in aggregate form.

Specifying Elements

Some endpoints take a string specifying which elements data should be obtained for. string is a comma-separated list of element symbols and/or Z numbers. Ranges can also be used.

Symbols are not case sensitive and can be mixed with Z-numbers.

Examples:
  • H-Ne - for hydrogen through neon (inclusive)
  • 1-10 - same as above
  • C,8,p-17 - carbon, oxygen, phosphorus through chlorine

Elements can also be passed as multiple element parameters

  • ?elements=1&elements=6&elements=n - hydrogen, carbon, nitrogen

/api/metadata

Returns JSON representing the metadata about the basis sets contained in the BSE.

>>> r = requests.get(BASE_URL + '/api/metadata')
>>> print(r.json())
{'3-21g': ...

/api/formats

Returns JSON representing which basis set formats are available, along with a description

>>> r = requests.get(BASE_URL + '/api/formats')
>>> print(r.json())
{'bsedebug': 'BSE Debug', 'cfour': 'CFOUR',...

/api/reference_formats

Similar to /api/formats, but has info about which reference formats are supported

>>> r = requests.get(BASE_URL + '/api/reference_formats')
>>> print(r.json())
{'bib': 'BibTeX', 'json': 'JSON',...

/api/basis/<basis_name>/format/<fmt>

Obtain basis set data. This is the main function of the basis set exchange.

The output is a string, except when <fmt> is json. Basis names are not case sensitive. See /api/metadata for getting a list of basis sets. Formats can be obtained with /api/formats.

For how to pass elements, see Specifying Elements

Several options are available. These are specified as GET paramters

Option Arguments Description
elements String Restrict the output to only certain elements (see Specifying Elements)
version Integer Obtain a specific version of the basis set. Default is latest version
uncontract_general 1,0 or true,false Remove general contractions
uncontract_segmented 1,0 or true,false Remove general and segmented contractions
uncontract_spdf 1,0 or true,false Split apart combined sp, spd, etc, shells
optimize_general 1,0 or true,false Optimize general contractions. See the library documentation
make_general 1,0 or true,false Make the basis set as generally-contracted as possible
header 1,0 or true,false If false, do not print the BSE information header in the output
>>> # Get STO-3G as json
>>> r = requests.get(BASE_URL + '/api/basis/sto-3g/format/json')
>>> print(r.json())
{'name': 'STO-3G', 'names': ['STO-3G'], 'flags': [], 'family': 'sto', 'description': 'STO-3G Minimal Basis (3 functions/AO)',...

>>> # Get 6-31G in nwchem format, getting only hydrogen, carbon, nitrogen, and oxygen
>>> r = requests.get(BASE_URL + '/api/basis/6-31g/format/nwchem/?elements=1,6-8')
>>> print(r.text)
#----------------------------------------------------------------------
# Basis Set Exchange
# Version ...
# https://www.basissetexchange.org
#----------------------------------------------------------------------
#   Basis set: 6-31G
# Description: 6-31G valence double-zeta
#        Role: orbital
#     Version: 1  (Data from Gaussian 09/GAMESS)
#----------------------------------------------------------------------


BASIS "ao basis" PRINT
#BASIS SET: (4s) -> [2s]
H    S
      0.1873113696E+02       0.3349460434E-01
      0.2825394365E+01       0.2347269535E+00
      0.6401216923E+00       0.8137573261E+00
H    S
      0.1612777588E+00       1.0000000
#BASIS SET: (10s,4p) -> [3s,2p]
C    SP
      0.1687144782E+00       0.1000000000E+01       0.1000000000E+01
C    SP
      0.7868272350E+01      -0.1193324198E+00       0.6899906659E-01
      0.1881288540E+01      -0.1608541517E+00       0.3164239610E+00
      0.5442492580E+00       0.1143456438E+01       0.7443082909E+00
...

/api/references/<basis_name>/format/<fmt>

Obtain basis set data. This is the main function of the basis set exchange.

The output is a string, except when <fmt> is json. Basis names are not case sensitive. See /api/metadata for getting a list of basis sets. Formats can be obtained with /api/reference_formats.

For how to pass elements, see Specifying Elements

Several options are available. These are specified as GET paramters

Option Arguments Description
elements String Restrict the output to only certain elements (see Specifying Elements)
version Integer Obtain a specific version of the basis set. Default is latest version
>>> # Get references for aug-cc-pvtz as json
>>> r = requests.get(BASE_URL + '/api/references/aug-cc-pvtz/format/json')
>>> print(r.json())
[{'reference_info': [{'reference_description': 'The cc-pVTZ basis set', 'reference_data'...

>>> # Same as above, but in bibtex
>>> r = requests.get(BASE_URL + '/api/references/aug-cc-pvtz/format/bib')
>>> print(r.text)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
...
@article{balabanov2005a,
    author = {Balabanov, Nikolai B. and Peterson, Kirk A.},
    title = {Systematically convergent basis sets for transition metals. I. All-electron correlation consistent basis sets for the 3d elements Sc-Zn},
    journal = {J. Chem. Phys.},
    volume = {123},
    page = {064107},
    year = {2005},
    doi = {10.1063/1.1998907}
}

@article{dunning1989a,
    author = {Dunning, Thom H.},
    title = {Gaussian basis sets for use in correlated molecular calculations. I. The atoms boron through neon and hydrogen},
    journal = {J. Chem. Phys.},
    volume = {90},
    page = {1007-1023},
    year = {1989},
    doi = {10.1063/1.456153}
}

@article{kendall1992a,
    author = {Kendall, Rick A. and Dunning, Thom H. and Harrison, Robert J.},
    title = {Electron affinities of the first-row atoms revisited. Systematic basis sets and wave functions},
    journal = {J. Chem. Phys.},
    volume = {96},
    page = {6796-6806},
    year = {1992},
    doi = {10.1063/1.462569}
}
...

/api/notes/<basis_name>

Obtain notes about a basis set. Output is plain text.

>>> # Get notes for 6-31g
>>> r = requests.get(BASE_URL + '/api/notes/6-31g')
>>> print(r.text)
Notes from the original BSE
===========================
<BLANKLINE>
The 6-31G basis set uses 6 Gaussian primitives to expand the 1s core of second
period elements.
...

/api/family_notes/<family>

Obtain notes about a family of basis sets. Output is plain text.

>>> # Get notes for the jensen family
>>> r = requests.get(BASE_URL + '/api/family_notes/jensen')
>>> print(r.text)
Notes about the Jensen basis sets
=================================
<BLANKLINE>
Notes from Frank Jensen
-----------------------
<BLANKLINE>
pcseg:  the most recent (2014) segmented contracted version of the pc-n basis sets, defined for H-Kr, for n=0,1,2,3,4
apcseg: the most recent (2014) segmented contracted version of the aug-pc-n basis sets, defined for H-Kr, for n=0,1,2,3,4
...