1. Home

VSP API

The Variable Star Plotter (VSP) API provides a RESTful interface to VSP, allowing application developers to write programs that obtain charts and photometry data from the AAVSO. This document outlines how to use the VSP API. It does not assume the reader is familiar with REST practices; however it does assume that you know how to make an HTTP request, as well as how to handle JSON or XML data, in your language of choice.

Using the API

Making Requests

All uses of the VSP API are made by performing an HTTP request.

Creating a New Chart

You can create a new chart by specifying the field using the name of a star or a specific RA and declination. You do this by specifying parameters in the URL query string. For example:

https://app.aavso.org/vsp/api/chart/?star=SS+Cyg&fov=60&maglimit=14.5

will give you a chart for SS Cygni, with a 60 arcmin field of view and a magnitude limit of 14.5.

The available parameters are described below. Fields with a * are required:

  • star*: name of the star to plot. You must provide EITHER the star parameter OR ra and dec parameters (see below)
  • ra*: right ascension
  • dec*: declination
  • fov*: field of view, in arcminutes.
  • maglimit*: magnitude limit for the chart; stars fainter than the maglimit will not be plotted.
  • title: custom title to display on the chart
  • comment: comment to display at the bottom of the chart
  • resolution: chart resolution in pixels per inch (ppi). Defaults to 150
  • north: chart north/south orientation. Must be either "up" or "down". Defaults to "up"
  • east: chart east/west orientation. Must be either "right" or "left". Defaults to "right"
  • other: other variable stars to mark on the chart. Omit or leave blank for none, "gcvs" for GCVS variables, "all" for all variables
  • dss: plot a DSS chart. "on" plots a DSS chart; any other value does not
  • lines: draw lines for all magnitude labels. "on" draws lines, any other value does not
  • special: plot a special chart. Omit or leave blank for normal charts; other options are "dslr" for DSLR chart, "binoc" for Binocular chart, "std_field" for a Standard Field chart

Chart ID

If you already have a ChartID, you can obtain the chart by simply adding the chart ID to the endpoint URL. For example, if you want the chart 1000ABC you would use

https://app.aavso.org/vsp/api/chart/X15223Z/

Note that the trailing slash is REQUIRED.

Output

A sample output in JSON is shown below:

{
    "star": "SS Cyg",
    "auid": "000-BCP-220",
    "ra": 325.67892,
    "dec": 43.58608,
    "fov": 60.0,
    "maglimit": 14.5,
    "title": "",
    "comment": "",
    "special": null,
    "dss": false,
    "chartid": "X15223Z",
    "image_uri": "https://www.aavso.org/apps/vsp/chart/X15223Z.png",
    "resolution": 150,
    "photometry": [
        {
            "auid": "000-BCP-115",
            "comments": null,
            "label": 142,
            "ra": "21:42:37.62",
            "dec": "44:04:42.0"
            "bands": [
                {
                    "band": "V",
                    "mag": 5.11,
                    "error": 0.0
                }
                ... (more bands)
            ]
        }
        ... (more field stars)
    ]
}

Many of the results correspond to the parameters used to create the chart; see "Creating a New Chart" above. Other fields:

"auid": if the chart is plotted based on a star, this is the AUID of that star

"image_uri": URL where you can access the final rendered chart, in PNG format.

"photometry": this is a list of all the photometry stars in the field. Each star is an object describing that field star, including its AUID, RA and Declination coordinates, label, and any comments. It also includes a list of bandpass measurements for the star; this will generally include at least the V magnitude, as well as any other measurements available for that star.

You can also see the full output for a chart by using the Browsable API (see below)

Output Formats

The VSP API supports multiple output formats. This allows you to use whatever format is most natural for your programming environment.

There are two methods to specify your output format:

HTTP Accept: Header

You can specify the output format by sending an Accept header as part of the HTTP request. For example, with the following header:

Accept: application/xml

the API will respond with XML-encoded data

Query string parameter

You can specify the format using a parameter as part of the URL's query string. Use the parameter format with the name of the format you'd like. For example:

https://app.aavso.org/vsp/api/chart/X15223Z/?format=json

Will return the data in JSON format

The VSP API currently supports three output formats:

JSON

  • Accept: application/json
  • format=json

Data is returned in Javascript Object Notation.

XML

  • Accept: application/xml
  • format=xml

Data is returned in Extensible Markup Language.

Browsable

  • Accept: text/html
  • format=api

This format provides a browsable API that is easy view in your browser. This format is not intended to be used by programs, but rather provides a human-readable output to allow developers a simple way to explore the API. If you visit a resource URL in your web browser, you will see this format by default.

Tags
developers
API