AAVSO Target Tool 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 AAVSO Target Tool API allows you to write programs that access the AAVSO Target Tool outside of the browser. Let's say that you've written a program in Python to do computational work for your observations, and it takes in data from the AAVSO Target Tool as input. You could manually copy and paste data from the table 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 astronomers 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 AAVSO Target Tool API will allow you to access targets and visibility information from the command line (outlined below). If you're not planning on writing code, or if you only need to look up a few targets, you may wish to use the interactive table 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 details
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 filtergraph.com/aavso or aavso.org 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 filtergraph.com to see if the server is up. It may come back later.

GET telescope
Gets latitude, longitude and other data of the current telescope.
Inputs
none
Outputs
latitude Latitude of telescope. South is negative, North is positive.
longitude Longitude of telescope. West is negative, East is positive.
targetaltitude Minimum altitude that the telescope can observe in degrees relative to the horizon.
sunaltitude Altitude of sun at dusk and dawn in degrees.
GET https://filtergraph.com/aavso/api/v1/telescope
Authentication: Basic (username: your-api-key-here, password: api_token)

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

Result:
{'latitude':36.1661111111,'longitude':-86.7838888889,'targetaltitude':20,'sunaltitude':-5}


POST telescope
Sets latitude, longitude and other data of the current telescope.
Inputs
latitude Latitude of telescope. South is negative, North is positive.
longitude Longitude of telescope. West is negative, East is positive.
targetaltitude Minimum altitude that the telescope can observe in degrees relative to the horizon.
sunaltitude Altitude of sun at dusk and dawn in degrees.
Outputs
latitude Latitude of telescope. South is negative, North is positive.
longitude Longitude of telescope. West is negative, East is positive.
targetaltitude Minimum altitude that the telescope can observe in degrees relative to the horizon.
sunaltitude Altitude of sun at dusk and dawn in degrees.
POST https://filtergraph.com/aavso/api/v1/telescope
Authentication: Basic (username: your-api-key-here, password: api_token)

Python code:
import requests
API_KEY = "your-api-key-here"
data = {'latitude':36.1661111111,'longitude':-86.7838888889}
entry = requests.post("https://filtergraph.com/aavso/api/v1/telescope",auth=(API_KEY,"api_token"),data=data)
print(entry.json())

Result:
{'latitude':36.1661111111,'longitude':-86.7838888889,'targetaltitude':20,'sunaltitude':-5}

GET nighttime
Gets nighttime period following a specified time for a specified location. All times are UTC.
Inputs
latitude Latitude of telescope. South is negative, North is positive. If not provided, the user's settings are assumed.
longitude Longitude of telescope. West is negative, East is positive. If not provided, the user's settings are assumed.
sunaltitude Altitude of sun at dusk and dawn in degrees. If not provided, the user's settings are assumed.
time Time of interest as a UTC timestamp. If not provided, the current time is assumed.
Outputs
status One of the status codes below.
sunset If relevant, the sunset time as a UTC timestamp.
sunrise If relevant, the sunrise time as a UTC timestamp.
Status codes
SUN_IS_UP Sun is currently up; next sunset and the following sunrise are listed
SUN_IS_DOWN Sun is currently down; next sunrise is listed
SUN_IS_ALWAYS_UP 24 hour darkness; typically seen near the poles in winter
SUN_IS_ALWAYS_DOWN 24 hour daylight; typically seen near the poles in summer
SUN_ENTERS_ALWAYS_DOWN Sun is about to set into 24 hour darkness; sunset time is listed
SUN_EXITS_ALWAYS_DOWN Sun is about to rise after 24 hour darkness period; sunrise time is listed
GET https://filtergraph.com/aavso/api/v1/nighttime
Authentication: Basic (username: your-api-key-here, password: api_token)

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

Result:
{'status': 'SUN_IS_UP', 'sunrise': 1526553112, 'sunset': 1526518490}
At the time this was run: the sun was up, the sunset time was 7:54pm and the sunrise time was 5:31am the very next day.

GET targets
Get information about targets in the Target Tool database.
Inputs
obs_section An array with observing sections of interest. You may use one or more of: ac,ep,cv,eb,spp,lpv,yso,het,misc,all. Default is ['ac'] (Alerts & Campaigns).
observable If true, filters out targets which are visible at the telescope location during the following nighttime period. Default is false.
orderby Order by any of the output fields below, except for observability_times and solar_conjunction.
reverse If true, reverses the order. Default is false.
latitude Latitude of telescope. South is negative, North is positive. If not provided, the user's settings are assumed.
longitude Longitude of telescope. West is negative, East is positive. If not provided, the user's settings are assumed.
targetaltitude Minimum altitude that the telescope can observe in degrees relative to the horizon. If not provided, the user's settings are assumed.
sunaltitude Altitude of sun at dusk and dawn in degrees. If not provided, the user's settings are assumed.
time Time of interest as a UTC timestamp. If not provided, the current time is assumed.
Outputs
star_name Name of the star as it appears in the Target Tool.
ra Right ascension. Note this returns decimal degrees, not DMS.
dec Declination. Note this returns decimal degrees, not DMS.
var_type Variable type.
min_mag Minimum magnitude.
min_mag_band Minimum magnitude band.
max_mag Maximum magnitude.
min_mag_band Maximum magnitude band.
period Period in days.
obs_cadence Observing cadence in days.
obs_mode Observing mode: Photometry, Visual, Spectroscopy, All
obs_section Observing section: one or more of Alerts / Campaigns, Cataclysmic Variables, Eclipsing Variables, Short Period Pulsators, Long Period Variables, Young Stellar Objects, High Energy Targets, Exoplanets, Miscellaneous, None.
filter Filters: one or more of B, V, R, I, U, J, H, Vis, Visual, Spectroscopy, All
other_info Info manually supplied by AAVSO about this target. Targets may be formatted with a URL, which is enclosed in double brackets along with a description: [[Alert Notice 631 https://www.aavso.org/aavso-alert-notice-631]]
last_data_point Last observation made in UTC.
priority If true, designates a high priority target.
constellation Constellation area where the target is located.
observability_times Visibility events for the target in UTC, given telescope information and assuming target is not near solar conjunction. Provided in pairs of status code and UTC timestamp.
solar_conjunction If true, target is near solar conjunction.
Status codes
TARGET_RISES Time when the target becomes visible.
TARGET_SETS Time when the target is no longer visible.
TARGET_IS_ALWAYS_UP Target will be visible throughout the next nighttime period. If the sun is down, target will be visible for the rest of the current nighttime period.
TARGET_IS_ALWAYS_DOWN Target will not be visible during the next nighttime period.
GET https://filtergraph.com/aavso/api/v1/targets
Authentication: Basic (username: your-api-key-here, password: api_token)
        
Python code:
import requests
API_KEY = "your-api-key-here"
entry = requests.get("https://filtergraph.com/aavso/api/v1/targets",auth=(API_KEY,"api_token"),params={'obs_section':['all']})
print(entry.json())

Result:
{'targets':[
   ...,
   {'constellation': 'Cyg',
        'dec': 50.24142,
        'filter': '',
        'last_data_point': 1518435383,
        'max_mag': 5.6,
        'max_mag_band': 'V',
        'min_mag': 10.1,
        'min_mag_band': 'V',
        'obs_cadence': 3.0,
        'obs_mode': 'All',
        'obs_section': ['None'],
        'observability_times': [['TARGET_RISES', 1526524965]],
        'other_info': '',
        'period': None,
        'priority': False,
        'ra': 291.13779,
        'solar_conjunction': False,
        'star_name': 'CH Cyg',
        'var_type': 'ZAND+SR'},
    {'constellation': 'Oph',
        'dec': -24.9655,
        'filter': 'All',
        'last_data_point': 1501308179,
        'max_mag': 14.1,
        'max_mag_band': 'V',
        'min_mag': 22.0,
        'min_mag_band': 'V',
        'obs_cadence': 3.0,
        'obs_mode': 'All',
        'obs_section': ['None'],
        'observability_times': [['TARGET_RISES', 1526534623],
            ['TARGET_SETS', 1526551958]],
        'other_info': '',
        'period': None,
        'priority': False,
        'ra': 264.94208,
        'solar_conjunction': False,
        'star_name': 'Nova Oph 2017',
        'var_type': 'N'},
    ...
    ]
}

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