Exoplanet Archive Application Programming Interface (API) User Guide

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.

There is an alternate method of customizing an interactive table by directly modifying the table's URL to specify which columns/parameters to display. That approach is described in the Pre-filtering Tables help document.

To see some pre-generated queries of common use cases (e.g. "all confirmed planets in the Kepler field") that can be copied and pasted into a command-line interface or web browser, see the API Queries page.

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:

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 (see the table above for a full list of tables)

Note: This is a required parameter.

For Confirmed Planets: &table=exoplanets

For KOI Q1-16: &table=q1_q16_koi

Columns

Specifies which columns within the chosen table to return. Columns must use a valid column name. If this keyword is not included in the query, all default columns are returned.

One column: &select=columnname

Multiple columns:

&select=columnname1,columnname2,columnname3

Distinct values can also be specified:

&select=distinct 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=pl_hostname like 'Kepler-22'

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=pl_hostname 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 desc to the statement, as in:

Example: &order=dec desc

Cone Search

Specifies an area of the sky to search for all objects within that area.

Right Ascension (ra), Declination (dec) and radius (radius or rad) must be listed with their respective coordinates or units. The units must be included in the radius specification (degrees, minutes, arcsecs) with a space preceding the unit name.

Example: &ra=291&dec=48&radius=1 degree

File Format

Specifies the preferred file format of the output file. There are four options:

Build a Sample Query

Add the text that specifies which data table to query (e.g. Confirmed Planets, Kepler Objects of Interest or Threshold-Crossing Events). In this example, we select Confirmed Planets, which is the exoplanets table:

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 (&).

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.

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

Wildcards may be used in API where clauses, but must take the form "%25".
The following example returns all rows in the exoplanets table whose pl_hostname begins with "Kepler."http://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=exoplanets&format=ipac&where=pl_hostname like 'Kepler%25'&order=pl_hostname

Date fields may be filtered in API where clauses using the SQL to_date() function.
The following example returns all rows in the q1_q8 table with a KOI vet date that is after February 10, 2013.

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 notselect=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: