How to Use the System Aliases Service

The Exoplanet Archive's System Aliases lookup service is designed to return a complete list of all names associated with all objects in a given exoplanetary system. For example, a query on any of the TRAPPIST-1 planets returns a file listing all aliases for all seven planets in the system, as well as the host star. The output file is delivered in a structured JSON format.

This page describes how to compose a query in a web browser or wget command-line interface.

Building a Query

In the following steps, we will build a query to return a list of all names associated with an object that are recognized by the Exoplanet Archive. The query can be entered in a web browser's address bar.

  1. Start with the base URL: https://exoplanetarchive.ipac.caltech.edu/cgi-bin/Lookup/nph-aliaslookup.py?objname=

  2. Add the name of the object. The following example uses a target from the Gaia DR2 catalog, which is entered as Gaia DR2 2127941757262806656 b:

    https://exoplanetarchive.ipac.caltech.edu/cgi-bin/Lookup/nph-aliaslookup.py?objname=Gaia DR2 2127941757262806656 b

    Queries are case-insensitive and the service recognizes most permutations of a planet or host name. For example, entering Kepler-22, Kepler22, or Kepler 22 will return the same output.

    Note: Web browsers convert spaces and special characters to URL-encoded characters. For example, a space will be converted to %20. The query will continue to work after it's encoded, though it may be a challenge to edit. The following reference webpage may help.

  3. Run the query in your web browser and view the results: https://exoplanetarchive.ipac.caltech.edu/cgi-bin/Lookup/nph-aliaslookup.py?objname=Gaia DR2 2127941757262806656 b

    Alternate method: To run the query on the command line using wget, put double quotation marks (") around the URL, add -O, and then the name of the output file (also in double quotations). In the example below, the output file will be named gaia-dr2-2127941757262806656b.json. To learn more about wget, see the wget help document.

    wget "https://exoplanetarchive.ipac.caltech.edu/cgi-bin/Lookup/nph-aliaslookup.py?objname=Gaia DR2 2127941757262806656" -O "gaia-dr2-2127941757262806656b.json"

  4. Review the output file.

    The manifest at the top of the output file identifies the object by its default name in the Exoplanet Archive. For our example, the object name we used in the query, Gaia DR2 21279417572628006656 b, shows up as an alias for Kepler-22 b. If you were to search for the object's data in the archive, such as in the System Overview pages and Planetary Systems interactive table, you would search for it as Kepler-22 b.

    The output also includes all aliases for the system host and all of its planets (in our example, there is only one planet). To find the default name for each planet or host, look for the line that starts with "default_name":.

What if your query doesn't work?

The System Aliases service does its best to identify all possible variations of an object name. When the archive's list of aliases does not match what you've entered in your query, the service returns the following error message:

We suggest trying another variation of the name. If you think an object name alias is missing from the archive, please let us know by submitting a Helpdesk ticket.

 

Last updated: 29 August 2022