The ESO Phase 2 API

ESO has released a Phase 2 Application Programming Interface (API) that can be used to create, modify, or delete observation blocks (OBs), containers and an accompanying ReadMe file that define an observing run. In short, the API uses the lightweight JavaScript Object Notation (JSON) standard as data format to exchange information between the user-dedicated application and the Phase 2 server at ESO.

We strongly encourage ESO users who are planning to programmatically produce large amount of OBs (e.g. Large Program, Surveys runs) to familiarize with the ESO API at the following pages:

and (recommended for testing purposes)

In order to program more conveniently against the API, it is helpful to create small, language-specific bindings to the API. Detailed instructions and practical examples using Python are provided at the pages above.

Note to the users: Users should remember that any new item (e.g. OBs, scheduling containers) created with the API is immediately stored on the ESO database. Hence users are kindly asked to test the API functionalities by programming against the p2 Demo server before using their script on the Phase 2 approved run. This fact would help to preserve the stability and integrity of the ESO database used in operations. Please be reminded that the OBs or any item created inside the demo environment are publicly visible and may be deleted.

The obximport script

In the transition period between P2PP3 and the new web based p2 tool, some users may wish to use OBs from their previous runs (not checked-in during P100 or before) for their upcoming observations, without having to recreate them from scratch in p2.   

Please be aware of the following:

  • Service Mode runs: All OBs that were submitted (check-in) via P2PP3 in P100 or before are visible in p2 under the previous run ID. Those OBs can be re-used and simply copy & pasted from the pre-P101 run to the current run within p2. Please notice that the creation of OBs inside P100 observing runs and earlyer is not supported in p2. Runs younger then P90 are not visible in p2.
  • Visitor Mode runs: OBs belonging to visitor mode runs that were executed at least once during P100 or before are already visible in p2 under the previous run ID. Those OBs can be re-used and simply copy & pasted from the pre-P100 run to the current run within p2.

Users who wants to import a large amounts (> 100 single files) of OBX files or scheduling containers into the database and as such made available in p2 should use the obximport tool. It is a ready-to-run packaged Python program and is described in the following.

The program requires Python 2.7. It will not run on any earlier Python version or on any Python 3 version. It was tested only with CPython.

Installation on UNIX-like systems: Save the obximport python binary on your local disk, make it executable:

$:chmod +x obximport

then print its usage message:

$:./obximport --help


Definition: the obximport script is a Python based program which uses the ESO Phase 2 API to allow users to import large number of OBs into a ESO run. In the context of the API, a Container is defined as any item "containing" one or more objects. More specifically, any ESO run or folder and scheduling container (group/time-link/concatenation) created inside the ESO run is defined as a Container by the API and is uniquely identified in the ESO database by a Container ID.  

Preparation: Please log into the new web application for Phase 2 preparation p2 using your ESO User Portal credentials. Click on specific Container (Run, Folder, Scheduling container) to display the Container infos, including the Container ID of obximport. This number must be memorized since it uniquely identifies the selected Container. The Contained ID will be used to import OBX into the Container itself, being it a ESO run, a folder or a scheduling container.

General usage: The program needs at least one OBX file to import and the -c option with the Contained ID of a Container (see previous sections). After reading the OBX file(s), the program will prompt for a user credentials, i.e. a name to login and a password. It will then proceed with creating OBs into the ESO's database under the run, folder and/or scheduling container identified by the Contained ID.


$:./obximport -u username -c containerId *.obx

Please use ./obximport --help for a full list of options.


Tip: To avoid typing the password over and over again for repeated runs, store it in a file and redirect stdin of obximport from this file, e.g

$:./obximport -u username -c containerId *.obx < password.txt

This works only in combination with the --user -u option.