Hypatia Catalog API v1.0.0


An API key is required to access the API. To get one, create an account or log in.
What is this?
The Hypatia Catalog API allows you to write programs that access the Hypatia Catalog outside of the browser. Let's say that you've written a program in Python to do computational work for your next exoplanet-related discovery, and it takes in data from the Hypatia Catalog as input. You could manually copy and paste data from the plotting tool and get your program to parse the data, but after many requests it can become tedious over time. Instead, with a few simple commands, you can use the API to request the data and it will come to you in an easy to use, machine-readable format.

Should I use this?
Many computational researchers depend on APIs like this one for their work because it allows their code to access or update online data automatically, without going to the web interface by hand. The Hypatia API will allow you to access properties of the star, element abundances, catalog data, and scatter/histogram plots from the command line (outlined below). If you're not planning on writing code, or if you only need a few stellar abundances for a particular star, you may wish to use the interactive plotting tool instead.

What is an API?
An application programming interface (API) allows you to write code that interacts with websites. Most major websites provide an API as a courtesy to developers everywhere. For instance, here is what the API for Spotify looks like.

How do I try it out?
Many programming languages have libraries that can access web APIs. We will focus on the Python programming language and the Requests library for interfacing with APIs. Just like you need to put on socks before putting on shoes, you will need to make sure Python is installed before installing Requests. (We've linked to Requests version 2; you're welcome to use Requests III instead, but keep in mind the syntax may be different.)

Once you've downloaded Python and Requests, type in "python3" in your terminal to get started. For Windows users, Python 3 should be in your Start menu.

We've highlighted some text in yellow like this; as you go through the documentation, all you have to do is copy and paste the commands provided and it will go through the API.

Technical information
If this is your first time using an API and you're using Python and Requests, you may skip this section.

All users are restricted to 1000 requests per hour. Once you log in, the number of requests you have made in the past hour will show up here.
Rate limit information can be accessed through the response headers:
  • X-Rate-Limit-Limit: The number of allowed requests in the current period
  • X-Rate-Limit-Remaining: The number of remaining requests in the current period
  • X-Rate-Limit-Reset: The number of seconds left in the current period
Any requests exceeding the limit will return an HTTP 429 error.

Authentication is via HTTP Basic Auth, using the API key as the username and "api_token" as the password. Logging in to this page on your web browser does not log you in to the API. Many API libraries have HTTP Basic Auth built in, but in case you need to do it manually:
  • Take the string of the API key, followed by :api_token.
  • Then encode it to base 64.
  • Then stick Basic in the front, including the space.
  • Set the header HTTP_AUTHORIZATION to the resulting string and you should be good to go.

Only HTTPS traffic is allowed. In the interest of security, any HTTP traffic will return a 400 error, without redirection to HTTPS.

All inputs are accepted as URL parameters and are optional unless otherwise marked.

All outputs are returned in JSON as long as they are valid (HTTP 200). Client errors (HTTP 4xx) are returned as plain text. Server errors (HTTP 5xx) are returned as the HTML for the "Internal error" page. Make sure your code is able to handle these error responses gracefully.

The API returns the following error codes:
200 = Valid code. Response is provided as JSON.
401 = Invalid API key, or API key not provided.
410 = API no longer in service. Check hypatiacatalog.com or nataliehinkel.com for a new version.
429 = Too many requests. User has exceeded quota.
Other 4xx = Something is wrong with the query. An error message will be left in the response.
503 = Temporarily down for maintenance. Try again later.
Other 5xx = Server error. Check your query; if it looks OK then check www.hypatiacatalog.com to see if the server is up. It may come back later.

GET solarnorm
Returns a list of solar normalizations used by Hypatia.
Inputs
none
Outputs
author Author(s) of the paper referencing the solar normalization.
year Year of the paper referencing the solar normalization.
version Letter following year of the paper referencing the solar normalization.
notes Additional notes as needed.
identifier Used to identify the solar normalization in later API commands (e.g. GET composition).
GET https://hypatiacatalog.com/hypatia/api/v1/solarnorm
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/solarnorm",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
    {
      "notes": "",
      "identifier": "abs",
      "year": 0,
      "version": "",
      "author": "Absolute"
    },
    {
      "notes": "",
      "identifier": "and89",
      "year": 1989,
      "version": "",
      "author": "Anders & Grevesse"
    },
    ...
]


GET element
Returns a list of elements used by Hypatia.
Inputs
none
Outputs
An array with all the elements used in Hypatia, including singly ionized elements.
GET https://hypatiacatalog.com/hypatia/api/v1/element
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/element",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
  "FeH",
  "OH",
  "MgH",
  "AlH",
  "CaH",
  "TiH",
  "CH",
  "LiH",
  "NaH",
  ...
]


GET catalog
Returns a list of catalogs used by Hypatia.
Inputs
none
Outputs
author Author(s) of the paper referencing the solar normalization.
year Year of the paper referencing the solar normalization.
version Letter following year of the paper referencing the solar normalization.
override_name Used to override the name of the paper as needed.
li Returns true for the lithium versions of Luck et al. 2007 and 2015.
id Used to identify the catalog in later API commands (e.g. GET data).
GET https://hypatiacatalog.com/hypatia/api/v1/catalog
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/catalog",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
[
  {
    "author": "Adamow et al.",
    "override_name": null,
    "li": false,
    "version": "",
    "year": 2014,
    "id": 514
  },
  {
    "author": "Luck et al.",
    "override_name": null,
    "li": true,
    "version": "",
    "year": 2015,
    "id": 515
  },
  ...
]


GET star
Returns data for each star in the Hypatia database as well as its planets. Multiple stars can be submitted at once.
Inputs
hip The Hipparcos ID of the star. Multiple IDs can be submitted.
hd The Henry Draper ID of the star. Multiple IDs can be submitted.
2MASS The 2MASS ID of the star. Multiple IDs can be submitted.
Note: Only one of hip, hd, or 2mass needs to be submitted. Submit multiple IDs to look up multiple stars. IDs can be a mix of hip, hd and 2mass if needed.
Outputs
status Returns "found" if the star is found and "not-found" if the star is not found.
bd,dist,teff,logg,disk,bmag,ra,ra_proper_motion,spec,2MASS,hip,vmag,bv,dec_proper_motion,hd,dec,u,v,w,x,y,z The property of the star as mentioned in the Hypatia Catalog.
planets Returns each planet hosted by the star. For each planet we get these variables: name,p,p_err,m_p,m_p_err,e,e_err,a,a_err
GET https://hypatiacatalog.com/hypatia/api/v1/star?hip=12345&hip=56789&hip=113044
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"hip": [12345,56789,113044]}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/star",auth=(API_KEY,"api_token"),params=params)
print(entry.json())

Result:
[
  {
    HIP 12345 wasn't found
    "hip": 12345,
    "status": "not-found"
  },
  {
    HIP 56789 was found and has no planets
    "bd": "B+47 1894",
    "dist": 99.206,
    "teff": 6829.0,
    "logg": null,
    "planets": [], no planets
    ...
    "hip": 56789, there's the HIP
    ...
    "status": "found", there's the status
    ...
  },
  {
    HIP 113044 was found and has one planet
    "bd": null,
    ...
    "planets": [ one planet found
      {
        "e_err": 0.078,
        "p": 1311.0,
        "m_p_err": 0.13,
        "e": 0.07,
        "name": "b",
        "a": 2.56,
        "p_err": 49.0,
        "m_p": 1.26,
        "a_err": 0.17
      }
    ],
    ...
    "hip": 113044, there's the HIP
    ...
    "status": "found", there's the status
    ...
  }
]


GET composition
Returns a list of compositions for a given element, star, and solar normalization, and computes the median and mean value for that group. More than one group can be supplied by submitting the groups one after the other: element, star, solar normalization, element, star, solar normalization, etc. Alternatively, you can submit element, star, element, star, etc., in which case Lodders et al. 2009 is assumed.
Inputs
element Name of the element, case insensitive. You may include or omit the trailing H.
star Hipparcos ID of the star.
solarnorm Identifier for the solar normalization. See GET solarnorm for solar normalization identifiers.
Note: There should be the same number of elements, stars, and (if included) solar normalizations. If solar normalizations are omitted, Lodders et al. 2009 is assumed for all compositions.
Outputs
hip The Hipparcos ID for the star in the group.
element The element for the group.
solarnorm The solar normalization for the group.
all_values All values referencing this group as well as their corresponding catalogs.
median The median value and any catalogs that reference it. More than one catalog may be returned in case of a tie.
mean The mean value.
GET https://hypatiacatalog.com/hypatia/api/v1/composition?hip=98355&element=ca&solarnorm=asp05
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"hip": 98355, "element": "ca", "solarnorm": "asp05"}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/composition",auth=(API_KEY,"api_token"), params=params)
print(entry.json())

Result:
[
  {
    "hip": 98355,
    "solarnorm": "asp05",
    "all_values": [
      {
        "catalog": {
          "author": "Edvardsson et al.",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 1993,
          "id": 584
        },
        "value": -0.49
      },
      ...
    ],
    "median": [
      {
        The median value is -0.49. Since two catalogs have this value, both values are returned
        "catalog": {
          "author": "Edvardsson et al.",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 1993,
          "id": 584
        },
        "value": -0.49
      },
      {
        "catalog": {
          "author": "Bensby et al. 2014]",
          "override_name": null,
          "li": false,
          "version": "",
          "year": 2014,
          "id": 537
        },
        "value": -0.49
      }
    ],
    "element": "caH",
    "mean": -0.457 there's the mean
  }
]


GET data
Returns scatter plot and histogram raw data for each graph on the Hypatia Catalog, as though it were submitted on this website. As a demonstration, try submitting this without any query variables; you will receive the X and Y coordinates of each point on the [Si/H] vs [Fe/H] default plot. Similarly, if you submit mode=hist, you will receive the default histogram provided by "Stars With/Without Planets".
Inputs
mode If mode is set to hist, returns a histogram provided by "Stars With/Without Planets". filter1_1 The first filter. This field can be a stellar property, planet property, or numerator for the element ratio. Stellar and planet properties are listed in GET star. Element ratios are listed in GET element; it is case sensitive and the trailing H should be omitted.
filter1_2 The denominator for the element ratio, if one is given for filter1_1. Leave blank for H.
filter1_3 Minimum value for the filter.
filter1_4 Maximum value for the filter.
filter2... Same for the second filter.
filter3... Same for the third filter.
xaxis1, xaxis2 X axis for the scatter plot or histogram. Follows the same pattern as filter1_1 and filter1_2. If omitted, [Fe/H] is assumed.
yaxis1, yaxis2 Y axis for the scatter plot. Follows the same pattern as filter1_1 and filter1_2. If omitted, [Si/H] is assumed.
zaxis1, zaxis2 Z axis for the scatter plot. Follows the same pattern as filter1_1 and filter1_2.
statistic Choose whether to return the median or the mean. If omitted, median is assumed.
cat_action Choose whether to allow or exclude given catalogs. If omitted, exclude is assumed.
catalogs Catalog IDs to allow or exclude. See GET catalogs to choose catalog IDs.
star_action Choose whether to allow or exclude given stars. If omitted, exclude is assumed.
star_list Stars to allow or exclude.
star_source Choose wheter stars are Hipparcos IDs or Henry Draper IDs. If omitted, hip is assumed.
normalize Normalizes the histogram.
solarnorm Solar normalization identifier. See GET solarnorms to choose a solar normalization. If omitted, Lodders et al. 2009 is assumed.
Outputs
solarnorm Information about the given solarnorm.
count Number of stars or planets in the query.
labels Labels for each axis in the query.
values If a scatter plot, return all the Hipparcos IDs, X/Y/Z coordinates, and values for each filter provided.
all_hypatia If a histogram, return the values of each bin for all Hypatia stars.
exo_hosts If a histogram, return the values of each bin for only the Hypatia stars that host planets.
edges If a histogram, return the edges for each bin.
GET https://hypatiacatalog.com/hypatia/api/v1/data
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/data",auth=(API_KEY,"api_token"))
print(entry.json())

Result:
{
    "count": 5584,
    "solarnorm": {
      "notes": "",
      "identifier": "lod09",
      "year": 2009,
      "version": "",
      "author": "Lodders et al."
    },
    "labels": {
      "xaxis": "[Fe/H]",
      "yaxis": "[Si/H]"
    },
    "values": [
      {
        "hip": 111944,
        "xaxis": -0.195,
        "yaxis": 0.06
      },
      {
        "hip": 92512,
        "xaxis": -0.51,
        "yaxis": -0.18
      },
      ... 
    ]
}
GET https://hypatiacatalog.com/hypatia/api/v1/data?mode=hist
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
params = {"mode":"hist"}
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/data",auth=(API_KEY,"api_token"), params=params)
print(entry.json())

Result:
{
    "solarnorm": {
      "notes": "",
      "identifier": "lod09",
      "year": 2009,
      "version": "",
      "author": "Lodders et al."
    },
    "count": 6156,
    "exo_hosts": [
      0,
      0,
      0,
      ...
    ],
    "all_hypatia": [
      2,
      3,
      6,
      ...
    ],
    "labels": {
      "xaxis": "[Fe/H]",
      "yaxis": "Number of Stellar Systems"
    },
    "edges": [
      -2.5,
      -2.3225,
      -2.145,
      ...
    ]
}


ASCII tables
If you wish to convert JSON data to ASCII tables, we recommend using the astropy library, which contains tools for writing ASCII tables. A word of warning: many of the queries provided by the Hypatia API don't have the same number of columns for each row. For instance, if you submit a request for multiple stars and one of those stars has planet information in the catalog, it won't fit neatly into one table. In order for the astropy ASCII table functions to work, each row has to have the same number of columns.

Here is how to convert the default Hypatia scatter plot (x=[Fe/H], y=[Si/H]) to an ASCII table, assuming that astropy is installed:

import requests
from astropy.io import ascii

API_KEY = "your-api-key-here"
entry = requests.get("https://hypatiacatalog.com/hypatia/api/v1/data",auth=(API_KEY,"api_token"))
json = entry.json()
ascii.write(json['values'],format="fixed_width_two_line",formats={"xaxis":"%.2f","yaxis":"%.2f"})
  
Result:
   hip xaxis yaxis
------ ----- -----
111944 -0.20  0.06
 92512 -0.51 -0.18
 85805 -0.10  0.12
 88839 -0.00  0.09
 88788  0.04  0.23
  7539  0.19  0.22
 56278  0.06  0.07
 56363  0.40  0.46
 56572  0.26  0.34
 56884 -0.07 -0.07
...


Reference
This API is modeled on the Toggl API.
Further reference: here and here