Home   |     Overview and Holdings    |    Documentation    |    Helpdesk      

Exoplanet Archive Application Programming Interface (API)

The Exoplanet Archive data are accessed primarily through a Web interface, but users who have some programming knowledge may write scripts that automate specific search queries. These queries must follow a structure that is compatible with the Exoplanet Archive's application programming interface (API). This page provides information on using the API to automate data retrieval.

Skip to:

Data Available Through the API

Query Syntax

Build a Sample Query

Default Table Columns

Examples of Valid Queries

Troubleshooting

Data Available Through the API

Currently, the Exoplanet Archive allows the following data tables to be accessed through the API:

Data Common Name API Name
(What to use in queries)
All planets and hosts in the archive Planets and Hosts exoplanets
All Kepler planet candidates Kepler Candidates keplercandidates

Query Syntax

The Exoplanet Archive's API is based on the Structured Query Language (SQL), but only a subset of the SQL functionality is available to the user. Specifically, the user supplies fragments of a simple SQL SELECT statement and the full query is constructed from these (after syntax/content checking). These fragments are given as standard HTTP Web service parameter values, as described below.

An Exoplanet Archive API query can be submitted through a Web browser or entered as a wget command in a command-line interface (CLI). All queries must begin with the following base URL:

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?

Additional search parameters are appended to the base URL and can be customized to specify the type of information to be returned. The parameters are structured in a keyword-value pair format and separated by an ampersand (&). Parameters may be listed in any order, and all are optional except the table parameter.

The following table describes the allowed parameters and their usage:

Keyword Description Value Syntax and Examples
Table Specifies which table to query (Planets and Hosts or Kepler Candidates).

Note: This is a required parameter.

 For Planets and Hosts: &table=exoplanets

For Kepler Candidates: &table=keplercandidates
Columns Specifies which columns within the chosen table to return. Columns must use a valid column name.

One column: select=columnname

Multiple columns:

&select=columnname1,columnname2,columnname3

To return all possible columns for the specified table, use &select=* (Note that this may return several hundred columns.)

Note: Column name text is not case-senstive. For example, "dec," "DEC," "Dec" and "dEC" are all acceptable.

Where Specifies which rows to return. Use this to search for a range of values, such as rows with a declination greater than 0. Parameters must use a valid column name.

Only return rows with a parameter greater than a given value: &where=parameter>value

  • Example: &where=dec>0

Only return rows with a parameter less than a given value: &where=parameter<value

  • Example: &where=dec<0

Only return rows containing a specific string of text: &where=parameter+like+'searchstring'

  • Example: &where=plnthostname+like+'Gliese+876'

Note: If you are searching for null values in the column data, use is instead of like and remove the single quotation marks.

  • Example: &where=plnthostname+is+null
Order Controls the order the rows are returned.
Acceptable keywords are order, order_by, and orderby, followed by the column names in your preferred order. Separate column names with commas.
  • Example: &order=dec

Rows are listed in ascending order by default, based on the values within the row. For example, if the column Dec is selected, the rows with the lowest Dec values are always at the top of the list.

To list results in descending order, add a plus (+) and desc to the statement, as in:

  • &order=dec+desc
File Format Specifies the preferred file format of the output file. There are three options:

For IPAC Table Format/ASCII, any of the following entries are allowed and return the same results:

  • &format=ascii
  • &format=ipac
  • &format=ipac-ascii
  • &format=ipacascii
  • &format=ipac_ascii

For XML/VOTable:

  • &format=xml
  • &format=votable
  • &format=vo-table
  • &format=vo_table

Note: File format names are not case-sensitive, so &format=IPAC is the same as &format=ipac.

Build a Sample Query

The following procedure will build a query to return Exoplanet Archive data from a Web browser.

  1. Start with the base URL:

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?

  2. Add the text that specifies which data table to query (e.g. Planets and Hosts or Kepler Candidates). In this example, we select Planets and Hosts, which is the exoplanets table:

    3. http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets

  3. Add the names of the column(s) in the table to be returned. If there are multiple selections, separate each with a comma. In this example, we select the Planet Host Name (pl_hostname), RA (ra) and Dec (dec). Note the separator between the table and column parameters is an ampersand (&).

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec

  4. Add the parameter to order the rows by Dec in ascending order (lowest value at the top).

    5. http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec

  5. Add the preferred output file format. In this example, the output will be IPAC Table Format (ASCII).

    http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii

  6. Run the query in a Web browser and view the results:

    7. http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii

    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 planets.txt. To learn more about wget, see the wget help document.

    wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=pl_hostname,ra,dec&order=dec&format=ascii" -O "planets.txt"


Data Column Names


Examples of Valid Queries

Here are some additional examples of working queries.

The following is an example of a Web-based query:

http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&select=hd_name,st_mass&format=ascii

The following is an example of a wget query:

wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=csv" -O "defaults.csv"

Troubleshooting

The Exoplanet Archive's API is based on the Structured Query Language (SQL), so make sure your queries follow some basic guidelines, including:

  • Always specify a table (exoplanets or keplercandidates)

  • Always separate multiple keyword-value pairs with an ampersand (&)

  • Avoid using spaces to separate keyword-value pairs (i.e. after the &). Instead, use plus signs (+) as separators.

  • Never use the following keywords or symbols for parameter values because they are not allowed: delete, drop, select and ; (semicolon).

Here are some additional issues you may encounter and their suggested fixes:

Problem: The output is delivered in CSV format instead of the specified file format.

Possible Solution: Check that there are no spaces before the &format= parameter, which invalidates the statement and thus returns the default file format, which is CSV.


Problem: You receive the following error message: ERROR Error Type: UserError - "table" parameter Message: "" is not a valid table.

Possible Solution: Your query doesn't specify which data table -- all Planets and Hosts in the archive (exoplanets) or all Kepler Candidates (keplercandidates). Add the appropriate parameter, beginning with &table=. Also, check that the parameter doesn't have a typo, such as "tble" vs. "table."


Problem:You receive the following error: ERROR Error Type: SystemError Message: -201:0:A syntax error has occurred.

Possible Solution: Check that the values for &select= are separated by commas, and not spaces. For example, uniqueid ra dec is invalid, and uniqueid,ra,dec is valid. Also, if you are selecting all columns, check that the parameter is select=* and not select=select*.


Problem: Your query works in a Web browser, but not when submitted on the command line as a wget command.

Possible Solution: Make sure the query (the URL and appended parameters) is contained by double quotation marks ("). For example:

  • Correct:    wget "http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=keplercandidates&format=csv" -O "defaults.csv"

  • Incorrect:    wget http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=keplercandidates&format=csv -O "defaults.csv"

NASA IPAC NExScI Caltech

      Home   |     Overview and Holdings    |    Documentation    |    Helpdesk