⚠️ Work in Progress — Updated: 22 August 2025
These notebooks are under active development. While we aim for accuracy, we cannot guarantee that everything in this repository currently works as intended.
Some functionality depends on features ofastroquerythat are only available in the ESO astroquery fork.
Until these changes are merged into a stable release, please installastroquerydirectly from that branch to ensure compatibility.
Features, functions, and outputs may change without notice. Please report any issues via GitHub.
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.
All notebooks live under examples/ and are grouped by purpose:
examples/
├── simple/ # 🌱 Minimal, single‑feature recipes (copy/paste friendly)
├── advanced/ # 🚀 Scenario‑driven workflows combining multiple functions
└── case_studies/ # 🌌 Curated case studies for specific Phase 3/data collections
See detailed indexes inside each folder:
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)A simple overview script can be found in examples/simple/00_introduction.ipynb.
Tip: You can try all the examples directly in
, 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:
Split over:
- 2.3 million spectra (1D extracted, fully calibrated)
- 950 000 imaging products in optical, near-IR, and sub-mm bands
- 650 000 spectral cubes from IFU and radio/mm instruments
- 670 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 notebooks may use newer astroquery.eso features. As such it is recommended to install the latest pre-release version of astroquery from the ESO GitHub repository, available on the ESO GitHub. This can be done using pip:
# optional: create an isolated env
conda create -n astroquery_eso python=3.13 -y
conda activate astroquery_eso
# install the latest astroquery from GitHub
python -m pip install --upgrade pip
pip install "git+https://github.com/eso/astroquery.git"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.
These notebooks were tested with:
- Python 3.13.5
astroqueryfrom the ESO astroquery fork- Common scientific libraries:
numpy,matplotlib,astropy,requests,tqdm
Other recent Python 3 versions may work, but compatibility is only guaranteed with the tested environment above.
Contributions are welcome!
If you'd like to contribute, please fork this repository and submit a pull request with your improvements.
This project is licensed under the MIT License - see the LICENSE file for details.