# The Open Exoplanet Catalogue is an XML database kept current by hand and by import

> The Open Exoplanet Catalogue is a database of all discovered extra-solar planets, published as XML files that new entries usually reach within 24 hours of an announcement. Its distinguishing detail is a mixed maintenance model, where high profile discoveries are entered by hand and everything else is imported from the NASA Exoplanet Archive.

**OpenExoplanetCatalogue/open_exoplanet_catalogue** — The main data repository for the Open Exoplanet Catalogue

- Repository: https://github.com/OpenExoplanetCatalogue/open_exoplanet_catalogue
- Website: http://openexoplanetcatalogue.com
- Stars: 1,135 · Forks: 225
- Language: Python
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/openexoplanetcatalogue-open-exoplanet-catalogue

## A single record of every discovered planet

The Open Exoplanet Catalogue is a database of all discovered extra-solar planets, and the operational claim in the readme is the one that matters for anyone planning to use it: new planets are usually added within 24 hours of their announcement.

That claim is what separates a catalogue from an archive. The NASA Exoplanet Archive is a separate database, and pulling from it means depending on it. The catalogue is a set of files you can download, mirror, diff and pin.

The project is a community effort maintained by Hanno Rein, with the project's website at openexoplanetcatalogue.com and a paper describing it on arXiv. The readme asks for corrections and additions through pull requests or by email, and it says directly that the catalogue is a community project, with questions about git or the database going to the contributors.

Two audiences are being served. There is the researcher who wants the whole known population in one file to run statistics over, and there is the developer who wants a list of planets in a form their own tool can read, which is why a companion repository of simple comma or tab separated tables exists for the second case. The main repository is the canonical form and the tables are the convenience form.

The data lives in the systems/ directory, with a separate systems_kepler/ directory, and the repository also carries a template.xml, which is the skeleton a new entry is written against, and an oec.xsd, which is the XML schema the data is validated against. That last file is the most important thing in the repository for a programmatic user, because it is where the actual structure is defined.

## Two maintenance paths, and the continuity repository

The status update at the top of the readme is the most honest thing in it, and it describes a hybrid workflow.

Since June 2020 the maintainer has been maintaining the catalogue more actively again. The plan is to manually enter data for time sensitive and high profile discoveries, and, because of the large number of planets that get discovered these days, to import data from the NASA Exoplanet Archive for all other planets. The readme points to the oec_continuity repository for details of that arrangement.

So the catalogue has two provenance paths, and a user of the data should know which one a given record came from. A high profile discovery, the kind where a paper is being written and the numbers are being discussed, is entered by the maintainer who read the paper. The long tail is imported from the NASA archive, where the data has already been through a different curation process.

That distinction explains a property of the dataset that you will notice when you use it. Fields are not uniformly populated. A planet whose discovery paper reported a transit depth and a stellar radius will have those, and a planet detected by radial velocity alone will have different fields, and the import path may carry different coverage again. The schema is fixed, but the fill level is a function of the physics of the discovery and of where the record came from.

For a statistician this is not a defect, it is the nature of the field: not every planet has every measurement, and the missing values carry information. For a pipeline that expects a rectangular table, it is a problem, and the honest answer is that no catalogue of heterogeneous observations will give you one.

The readme's own request, to keep watching out for errors and submit pull requests, is the mechanism for the hand entered half. The imported half is only as good as the upstream archive and the import logic, and the oec_continuity repository is where that logic lives.

## The data model: systems, stars, binaries and planets

The readme documents every tag in the catalogue in a table with four columns: the tag, what it can be a child of, a description and a unit. The structure is worth understanding because it is not flat.

The system tag is the root container for an entire planetary system. The star tag is the container for a single star and can be the host of one or more planets, the circum-stellar case. The binary tag represents a pair, and the table is precise that a binary consists of either two stars, one star and one binary, or two binaries, and that a binary can also host planets, the circum-binary case. The planet tag is the container for a single planet, and the note on it is worth reading: a planet is a free floating, or orphan, planet if it is a child of system, which is how a planet with no host star is expressed.

So the hierarchy nests in a way that reflects the physics: a system contains stars, binaries and planets, and a binary can contain further stars or binaries and planets of its own. A circumbinary planet is a planet whose parent is a binary, and the example code in the readme queries for exactly that case.

The measurement tags attach to different parents. The distance from the Sun in parsecs is a property of the system, the right ascension and declination are too, and the epoch for the orbital elements belongs to the system as well, with the comment that the mean longitude and mean anomaly are the same for all planets in one system. The orbital elements, semimajor axis, separation, position angle, eccentricity, periastron, longitude, mean anomaly, ascending node, inclination, impact parameter and the period in days, are properties of a planet or of a binary, with the tag able to occur multiple times with different units for the separation, which does not imply a specific orbital configuration the way the semi-major axis does. The physical parameters, mass, radius, temperature, age and metallicity, attach to a planet or a star, and the units change accordingly: mass and radius in Jupiter masses and Jupiter radii for a planet and in solar masses and solar radii for a star, temperature in Kelvin, age in Gyr and metallicity as a logarithm relative to solar.

The brightness tags, magB and magV, can appear on a binary, a star or a planet, and the name tag can be used multiple times for an object with several names.

## Reading the catalogue from Python with nothing installed

The access story is the strongest part of the project, because it removes every reason to write a downloader.

The readme says it is very easy to access the catalogue using Python, and that the snippet is short, and that no download, no installation and no external libraries are required. The mechanism is that the data is fetched as a gzipped XML file from a companion repository, oec_gzip, and parsed with the standard library:

```python
import xml.etree.ElementTree as ET, urllib.request, gzip, io
url = "https://github.com/OpenExoplanetCatalogue/oec_gzip/raw/master/systems.xml.gz"
oec = ET.parse(gzip.GzipFile(fileobj=io.BytesIO(urllib.request.urlopen(url).read())))
 
# Output mass and radius of all planets 
for planet in oec.findall(".//planet"):
    print([planet.findtext("mass"), planet.findtext("radius")])
```

The queries that follow in the readme show the hierarchy in use, including finding all circumbinary planets with a path of .//binary/planet, and printing the distance to each system together with its planet count by finding the system elements and counting their planet children.

Two details make this pattern production worthy rather than a toy. The URL points at the raw gzipped file, so the payload is compressed on the wire, and it points at the master branch of a dedicated mirror repository, which means the data is versioned by git and the file is fetched without an API. The parsing is done with ElementTree and XPath style paths, so a query is a path expression rather than a hand written traversal.

The readme also shows the Python 2 variant of the same snippet, using urllib rather than urllib.request and the print statement syntax, which is a small sign of the age of the example. The Python 3 form is the one to use.

## The surrounding tooling, and what the licence really says

The repository has a few supporting pieces that show how the data is produced and checked.

There is a cleanup.py, which suggests a script that normalises or tidies the XML after editing, and simbad_extractor.py, which points at the SIMBAD astronomical database as a source for identifiers or coordinates. There are three statistics files, statistics.json plus one for the NASA Exoplanet Archive and one for the ExoplanetEU catalogue, which are presumably counts computed over the data and over the comparison sources. There is oec_paper.pdf, the paper itself, checked in alongside the data. The CI configuration is a .travis.yml.

The licence is where a careful reader has to pause, because the two sources disagree in a small but meaningful way. The readme has an MIT badge and states that the database is licensed under an MIT license, which basically says you can do everything with it, and it is linked to the MIT text. The repository's licence metadata, however, is listed as unknown, and the top level listing shows a LICENSE file is not among the entries. So the licence claim comes from the documentation rather than from a licence file in the repository, and a user who needs a licence file for compliance has to ask for it.

The attribution request is the other thing to note. If you use the catalogue for a scientific publication, the readme asks you to include a reference to the catalogue on GitHub or to the arXiv paper, with the paper identifier linked from the badge. That is a request rather than a licence condition, and it is the sort of thing that is easy to honour and awkward to retrofit, so it is worth handling at the start.

For a data project, the practical pairing is the catalogue for the canonical XML and the oec_tables repository for the flat comma or tab separated form, and the oec_gzip repository for the compressed file your code fetches. Three repositories, three access patterns, and the readme only names two of them, which is itself a small gap in the documentation.

## Conclusion

The catalogue suits an astronomer or a data scientist who needs a single flat record of the known exoplanet population with orbital elements and physical parameters in one place, and it suits anyone who wants to fetch the data without a pipeline. It is the wrong choice if you need the data to be uniform and machine guaranteed, because the maintenance is split between a maintainer entering discoveries by hand and an import from another archive, so a field can be present for one planet and absent for another, and a poor match for a project that needs a stable schema version, since the tag list is documented in the readme and an XSD file rather than versioned. Before using it, read the tag table to see which measurements are optional, and cite the catalogue or its arXiv paper if your work is published.

## FAQ

### What is the Open Exoplanet Catalogue?

It is a database of all discovered extra-solar planets, published as XML, with new planets usually added within 24 hours of their announcement. High profile and time sensitive discoveries are entered by hand and the rest is imported from the NASA Exoplanet Archive.

### How do I read the catalogue in Python without installing anything?

Fetch the gzipped systems.xml file from the oec_gzip repository and parse it with the standard library, using xml.etree.ElementTree and gzip. The readme gives a snippet that prints planet masses and radii, finds circumbinary planets, and counts planets per system.

### How is the exoplanet data structured?

The system tag is the root container for a planetary system, and it can contain stars, binaries and planets. A binary can itself contain stars, binaries and planets, which is how circum-binary planets are expressed, and a planet directly under a system is a free floating planet. The readme documents every tag with the parents it can have and its unit.

### What licence does the Open Exoplanet Catalogue use?

The readme states the database is licensed under an MIT licence and links the MIT text, though the licence field on the repository is listed as unknown. If you use it in a publication, the readme asks you to cite the catalogue on GitHub or the arXiv paper with identifier 1211.7121.

## Sources

- [Issues](https://github.com/OpenExoplanetCatalogue/open_exoplanet_catalogue/issues)
- [OpenExoplanetCatalogue/open_exoplanet_catalogue on GitHub](https://github.com/OpenExoplanetCatalogue/open_exoplanet_catalogue)
- [Project website](http://openexoplanetcatalogue.com)
- [README](https://github.com/OpenExoplanetCatalogue/open_exoplanet_catalogue/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openexoplanetcatalogue-open-exoplanet-catalogue