This repository contains a suite of Jupyter notebooks designed to demonstrate how to explore, query, and retrieve data from the ESO Science Archive using Python. The primary interface used is the astroquery.eso module, which is part of the broader astroquery package developed under the Astropy ecosystem.
These notebooks walk through both introductory and advanced examples that are relevant for a wide range of scientific use cases — from downloading raw and reduced data products, to analyzing spectra and imaging datasets retrieved from ESO facilities at La Silla and Paranal (including the Very Large Telescope - VLT - and the Very Large Telescope Interferometer - VLTI), as well as from submillimeter and radio observatories -- APEX and ALMA.
Whether you're new to archival astronomy or already familiar with ESO's observing systems, these examples provide practical guidance for integrating archive queries into reproducible, scriptable workflows.
ESO_Introduction.ipynb— Introduction toastroquery.esoand its basic functionality (e.g. listing instruments, setting credentials)ESO_Query_*.ipynb— Focused demonstrations of specific search and filtering operations using TAP queries, cone searches, and dataset metadataESO_WorkingExample_*.ipynb— Real-world examples combining archive access with data inspection, plotting, and scientific analysis (e.g. radial velocities, spectral line studies)
To get started, you can load and initialize the ESO archive interface directly in your notebook:
from astroquery.eso import Eso # Import the ESO module from astroquery
eso = Eso() # Create an instance of the ESO class
eso # Display the class instance (e.g. check login status, default settings)
You can try it directly in mybinder, without installing anything.
Once initialized, you can search by program ID, target name, position, or instrument, and download data products directly into your working directory — all from within the notebook environment.
The ESO Science Archive Facility (SAF) is one of the largest ground-based astronomical data repositories in the world. It contains data from ESO telescopes at La Silla, Paranal, and APEX, as well as the submillimeter APEX telescope on Llano de Chajnantor and the ALMA array. The archive includes all raw data from La Silla Paranal Observatory, the corresponding calibrations, and a wide range of processed data products, either generated by ESO or contributed by the community. It also hosts selected external datasets, such as raw WFCAM/UKIDSS data from the UKIRT facility in Hawaii.
As of May 2025, the archive hosts over 4.6 million science products, including:
- 3.8 million products from La Silla, Paranal, and APEX
- 700 000 ALMA products
- 2.3 million spectra (1D extracted, fully calibrated)
- 900 000 imaging products in optical, near-IR, and sub-mm bands
- 500 000 spectral cubes from IFU and radio/mm instruments
- 700 000 catalogue records
Processed data downloaded from the ESO Archive are assigned a Digital Object Identifier (DOI). You can browse the list of available DOIs here.
Access to data follows ESO’s standard data policy: the Principal Investigator (PI) of an observing program has exclusive access to their data during a proprietary period (typically one year), after which the data become publicly available. See the ESO Data Access Policy and FAQ for more information. Browsing the archive does not require authentication, but login is necessary to access proprietary datasets. Use of ESO archival data should be acknowledged in all publications.
There are four main ways to access the vast information in the ESO Archive:
- Raw Data query form - Full access to raw frames and their calibrations.
- Science Portal - Browse and retrieve processed (Phase 3) data.
- Catalogue Query Interface - Access PI-contributed catalogue data.
- Programmatic access page - Direct, scriptable access to raw and processed data, metadata, ambient conditions, and catalogues via Virtual Observatory (VO) protocols.
These notebooks focus on the last method: accessing the archive programmatically using the astroquery.eso module. Note that at present (May 2025), catalogue searches are not supported using the astroquery.eso module. Functionality for querying catalogues will be added in a future release.
The scientific community plays a vital role in expanding and enriching the ESO Science Archive. ESO provides the ESO Phase 3 process, a structured way to submit processed data products, ensuring long-term accessibility and usability across a broad range of astronomical fields. By sharing your own data, you contribute to the collective scientific effort, allowing others to query your datasets (as you are here), and build upon your work. To learn more about the submission process, visit the ESO Phase 3 guidelines.
These examples assume that you have a working Python environment (Python 3.9 or later is recommended) and that you have installed the necessary packages. You can install astroquery (which includes the ESO module) via pip:
> pip install astroqueryOr as part of the astropy module (note however this can be an older release):
> pip install astropyAdditional useful packages used in these notebooks are as follows:
- Jupyter Notebook or Jupyter Lab
- Recommended common libraries:
numpy,matplotlib,astropy,tqdm,pandas - Recommended less common libraries (used in the more advanced analysis scripts):
astral,datetime,coronagraph,PyAstronomy
You can install these dependencies using, for example:
> pip install numpy matplotlib astropy astroqueryUniquely in the Astropy ecosystem, Astroquery is operating with a continuous deployment model. It means that a release is instantaneously available after a pull request has been merged. These releases are automatically uploaded to PyPI, and therefore the latest version of astroquery can be pip installed. The version number of these automated releases contain the "dev" tag, thus pip needs to be told to look for these releases during an upgrade, using the --pre install option. If astroquery is already installed, please make sure you use the --upgrade (or -U) install option as well.
You can access this file as an interactive jupyter notebook, which you can download and run on your machine (instructions). To interact with the jupyter notebook (if you have download it): move up and down the various cells using the arrow keys, execute the code by pressing CTRL+ENTER; you can also modify the code and execute it at will.
Please note that this notebook uses Python version 3.9.21 and Jupyter Notebook version 6.4.10. Compatibility with other versions cannot be guaranteed.
Contributions are welcome! If you'd like to contribute, please fork the repository and submit a pull request with your improvements.
This project is licensed under the MIT License - see the LICENSE file for details.