Introduction

The HITRAN Application Programming Interface (HAPI) [1] is a set of routines in Python which aims to provide remote access to functionality and data provided by HITRANonline. At the present time, the API can download, filter and process line-by-line transition data.

The main purpose of this API is to extend the functionality of the main site, in particular, for the calculation of spectra using several types of line shape, including the flexible HT (Hartmann-Tran) profile [2] and optionally accounting for instrumental functions. Each feature of the API is represented by a Python function taking a set of arguments which describe the parameters defining the task.

The current version of HAPI and user manual is available for download using the following links:

This version of HAPI can also be directly installed into a Python environment using:

pip install hitran-api

Please note that from 1 January 2023, an API-key will be required for downloading data and using the HAPI software. API-keys are free to obtain and can easily be added to HITRAN user accounts by following the details given in the HITRAN2020 paper [3] or following instructions provided in the first video tutorial.

In addition, the HAPI project and version history are available on Github:

HAPI is described in Ref. [1], and futher suggestions and comments are welcome. Users are advised to contact Dr. Roman Kochanov.
 

Citation

If you use HAPI in your research or software development, please cite it using the following reference:

To make a reference to particular version of HAPI, use corresponding DOI from the Zenodo community in addition to the reference given above.
 

License

MIT License

Copyright ©, 2018 HITRAN team (http://hitran.org).


Features

Some of the prominent current features of HAPI are:

  1. Downloading line-by-line data from the HITRANonline site to a local machine;
  2. Filtering and processing the data in SQL-like fashion;
  3. Conventional Python structures (lists, tuples, and dictionaries) for representing spectroscopic data;
  4. Compatibility with a large set of third-party Python libraries to work with the data;
  5. Python implementation of the HT profile [2, 4, 5, 6] which can be used in spectral simulations. This line shape can also be reduced to a number of conventional line profiles such as Gaussian (Doppler), Lorentzian, Voigt, Rautian, Speed-dependent Voigt and speed-dependent Rautian;
  6. Python implementation of the total internal partition sums algorithm, TIPS-2021 [7] which is used in the calculation of the temperature dependence of HITRAN [3] transition intensities. The older software TIPS-2011 [8] and TIPS-2017 [9] is also available;
  7. High-resolution spectral simulation accounting for pressure, temperature and optical path length. The following spectral functions can be calculated:
    1. absorption coefficient
    2. absorption spectrum
    3. transmittance spectrum
    4. radiance spectrum
  8. Spectral calculation using a number of instrumental functions to simulate experimental spectra;
  9. Possibility to extend the user's functionality by adding custom line shapes, partition sums and apparatus functions.
     

HAPIEST

The HITRAN Application Programming Interface and Efficient Spectroscopic Tools (HAPIEST) project is currently in development. The aim of HAPIEST is to provide a graphical user interface for HAPI that allows a user unfamilar with Python to download, filter and plot HITRAN data at the touch of a button. The HAPIEST project is still in the alpha stage, with details and downloads available on Github:

References

[1] R.V. Kochanov, I.E. Gordon, L.S. Rothman, P. Wcislo, C. Hill, J.S. Wilzewski, HITRAN Application Programming Interface (HAPI): A comprehensive approach to working with spectroscopic data, J. Quant. Spectrosc. Radiat. Transfer 177, 15-30 (2016) [Link to article] [ADS].

[2] N. H. Ngo, D. Lisak, H. Tran, J.-M. Hartmann, An isolated line-shape model to go beyond the Voigt profile in spectroscopic databases and radiative transfer codes, J. Quant. Spectrosc. Radiat. Transfer 129, 89-100 (2013). [Link to article] [ADS]

[3] I. E. Gordon, L. S. Rothman, R. J. Hargreaves, R. Hashemi, E. V. Karlovets, F. M. Skinner, et al., "The HITRAN2020 molecular spectroscopic database", J. Quant. Spectrosc. Radiat. Transfer 277, 107949 (2022). [link to article]

[4] H. Tran, N. H. Ngo, J.-M. Hartmann, Efficient computation of some speed-dependent isolated line profiles, J. Quant. Spectrosc. Radiat. Transfer 129, 199-203 (2013) [Link to article] [ADS]

[5] H. Tran, N. H. Ngo, J.-M. Hartmann, Erratum to "Efficient computation of some speed-dependent isolated line profiles", J. Quant. Spectrosc. Radiat. Transfer 134, 104 (2014) [Link to article] [ADS]

[6] J. Tennyson, P. F. Bernath, A. Campargue et al., Recommended isolated-line profile for representing high-resolution spectroscopic transitions (IUPAC Technical Report), Pure Appl. Chem. 86, 1931-1943 (2014) [Link to article] [ADS]

[7] R. R. Gamache, B. Vispoel, M. Rey, A. Nikitin, V. Tyuterev, O. Egorov, et al., "Total internal partition sums for the HITRAN2020 database", J. Quant. Spectrosc. Radiat. Transfer 271, 107713 (2021). [link to article] [ADS]

[8] A. L. Laraia, R. R. Gamache, J. Lamouroux, I. E. Gordon, L. S. Rothman, Total internal partition sums to support planetary remote sensing, Icarus 215, 391-400 (2011). [Link to article] [ADS]

[9] R. R. Gamache, C. Roller, E. Lopes, I. E. Gordon, L. S. Rothman, et al., Total internal partition sums for 166 isotopologues of 51 molecules important in planetary atmospheres: Application to HITRAN2016 and beyond, J. Quant. Spectrosc. Radiat. Transfer 203, 70–87 (2017). [Link to article] [ADS]