API's to AAVSO resources

American Association of Variable Star Observers (AAVSO)
Wed, 04/15/2015 - 16:20

The information on how to access AAVSO resources via programming interfaces is a bit scattered across the AAVSO website. I'd like to pull together here in this thread the URL's of these resources. What I've found:

"VSX HTTP GET Specification" in a forum thread
  With this you can get variable star positions and variable type
  eg  http://www.aavso.org/vsx/index.php?view=query.votable&ident=SX+Uma
Get API access to Variable Star Database:  see the documentation for the new inteface
at  https://www.aavso.org/vsp-api

The API to use to fetch photometry is:

AAVSO Extended File Format

List of Standard Calibration Fields of View
Want a list of the filter names currently supported?

What other tools are available? Please add them to this thread!


I'm looking for a couple specific tools:

- Can VSP give me a variable stars coordinates? Something easier than the VSX VOTable output. 

- How can I get comp star spectral types? I'm looking to add DSLR functionality to Transform Applier (TA) and would like to include a feature that checks if the variable star and comps are appropriate candidates for DSLR transformation to BVR by warning if the star types are those with significant spectral features that cannot be transfromed from TB,TG,TR.

- Simbad is another resource that has an API, but it doesn't have a full set of AUID references so is less useful for AAVSO work.




American Association of Variable Star Observers (AAVSO)
Big Thank You!

Hi George,

Thanks for compiling this :). I started building a small app, and this is exactly the info that I needed. And I got it vithout even asking.


American Association of Variable Star Observers (AAVSO)
One-shot query to VSP

This will give you the variable star coordinates, the size of the FOV and the photometry table - albeit in an HTML document:



----- edited ----- 

The link above will list also a color index (B-V). Will that be OK?

----- edited 2 ------

Just wondered, the link you initially posted ( http://www.aavso.org/cgi-bin/vsp.pl?chartid=13221ASP&delimited=yes ) will list B and V magnitudes. You can also simply subtract them to get your color index. So the only real advantage for the one I posted is that it also lists the coordinates of the variable. 

Astronomical Society of South Australia (ASSAU)
VSX VOTable reader

Hi George

I've written a VSX VOTable reader in Java for VStar. It's not currently used but I'll switch to it at some stage. It's here if you want to have a look:


This would certainly give you what you need (spectral types, coordinates).

If you want help translating this to Python, let me know.


American Association of Variable Star Observers (AAVSO)
VOTable reader

Thanks David,

That is good looking code and certianly the right way to handle the XML of the VOTable query.

I'm working with an old platform: Borland C++ Builder (BCB5)  and some delphi packages. I can parse the XML but have opted to make the assumption that the order of fields is stable and so, for example, grab the contents of 4th <TD> field for the coordinates. 

Not very pretty. Let me study your code to see if I can port it to C++ 






American Association of Variable Star Observers (AAVSO)


I can parse the XML but have opted to make the assumption that the order of fields is stable and so, for example, grab the contents of 4th <TD> field for the coordinates. 


Interesting. I also like to dabble in programming and pulling data from the web via HTTP GET. This raises some questions regarding how AAVSO views such "3rd party interfaces".

Does AAVSO have a policy regarding maintaining formats and order of fields in tables? Somehow I think not, since it appears many outside parties do programming for AAVSO, not so much in-house? This might make it difficult to enforce a rigid, unchanging standard?

How could changes to tables be announced to the community? I haven't seen much regarding that on the forums or website. It looks like the current status is - wait until an API "breaks", then go track down what changes caused it?

I don't really have much of an idea how many outside applications interface with AAVSO data.



Astronomical Society of South Australia (ASSAU)

Hi Mike

This forum was established for exactly the kind of communication you mention. It's interesting to look at the first post to the forum:


By the way, the VOTable issue mentioned by George has a solution, suggested in my reply to one of his posts in this topic.

Matt and others have posted here regarding impending changes to AID fields etc and we've discussed issues relating to CSV formatting (e.g. use of quoted fields) which have since been resolved. The VSX and VSP APIs seem fairly stable and changes to file formats are documented (i.e. the web pages updated), even if not always widely disseminated. Is there a well-defined change process? Sara or Matt may want to comment further.

My impression is that there's actually an even split between internal and external tools, perhaps even more internal (think about Zapper, SeqPlot, SunEntry, LCG, ...). It may be true that more external apps have cause to use HTTP-based APIs though.


American Association of Variable Star Observers (AAVSO)
Notes on parsing the VSP API XML output

For those who are going to read and parse the XML output of the new VSP API by scanning, there are a few wrinkles to keep in mind.

This is repost; it really belongs in this thread.

You need to keep track of
(1) what level you are in the XML stream and
(2) that you are not guarenteed the order of elements you find within a level.

For instance, from https://www.aavso.org/apps/vsp/api/chart/X15296BK/?format=xml
What if band comes after the mag and error? It doesn't here, but it could by XML rules. You wouldn't know which filter the mag belongs to until you finish that level defined by the list-item start and stop.

Further, some tagnames appear at multiple levels. Eg, "auid" appears at the root level, the star's auid, and in the phtometry level, the auid's of the comp stars. Same with "ra" and "dec"

XML scanners will offer the elements/tags it finds in sequence, offering tagType, tagName and tagContent fjor each. tagTypes are  tagStart, tagContent and tagEnd. tagNames will be the string in <>'s (eg "band"). And tagContent will be the value (eg "V")

The way I am doing it is to watch for a tagStart with the tagName of "list-item". That tells me I've moved up one level. Level 1 is photometry and level 2 is bands. While in a level I look for tagContent and collect the expected data for that level, but I don't do anything with it until I see the tagEnd, tagName of "list-item". Then I know its safe to act on the collected data, in this case assigning the comp's V mag and error.

I've been going through this coding for TA, PhotomCap and VPhot. Ignoring these subtleties could cause very hard to debug errors in your data.



American Association of Variable Star Observers (AAVSO)

Thanks George for the advice.
I have updated the LesvePhotometry to parse the XML output as you suggested. At the same time I modified the  parser to read right ascension and declination as decimal degrees.


American Association of Variable Star Observers (AAVSO)
VOTable standard

Hello all,

I'm not a programmer, but I have had some contacts with VOTable. I have found it to be a Good Thing when we are talking about self-descriptive data formats. And because it is used very widely in professional astronomy, there are usable standard-like guidelines or definitions available, e.g the following one:


If/when AAVSO API(s) are compatible with such definitions, there are plenty of tools that would really benefit. Isn't it a final goal to have AAVSO resources linkable to Virtual Observatory?

George, IMHO Simbad is The Source (hehe.. many would argue for sure ;-) ). AUID is just a name (as it looks to me) like one of the tens for some stars (visible e.g. in Simbad). While it is more convenient to use names in manual way (well, "I used comp star 329.354625, +44.235031" ;-) ...), decent (accurate and precise enough to be "unique") coordinates are IMHO much more general way to describe a star. Fortunately, coordinates are getting better and better. When I'm doing photometry of open clusters or just generally variable stars (not for AAVSO), I use always WCS+coordinates to identify my (or all stars in FOV) targets and that works just fine. Coordinates just happen to be tied to names in UCAC#, 2MASS, USNIO, HD etc etc catalogues.. When one wants additional data from Simbad, AUID could be solved to coordinates (using e.g. an AAVSO API?) and using those coordinates, sending required query to Simbad to retrieve some or many useful info bits.

Just a remark: spectral class in Simbad can not be trusted always. That may change in/after Gaia era (Gaia provides also plenty of spectroscopy) but probably is not going to happen for bright(er) stars and not before 5+(?) years. At the moment, I personally believe that having good photometry (APASS and Simbad for brighter stars?) in few filters would be (much) better approach.

Best wishes,

American Association of Variable Star Observers (AAVSO)

"better" is such a dangerous thing to wave in front of programmers.

I use the python astroquery library to access APASS from ViZieR.  If you think this might be better for you, let me know and I'll send you some sample code.





Vereniging Voor Sterrenkunde, Werkgroep Veranderlijke Sterren (Belgium) (VVS)
APASS API via astroquery

Accessing APASS through astroquery is - for me personally - not only better, it might even be perfect.
Would be grateful for any sample code you can send my way.


American Association of Variable Star Observers (AAVSO)
Programatic access to Chart table Data


I'm new to AAVSO and Photometry of variables and have built an app that  takes my observation data, enters it in a DB and generate light curves as well as an output file for AAVSO entry. 

I'm able to get finder charts and associated photometry table to help me find the star in question as well as comparison stars.

What  I was wondering is there an API  that  would give me a one line output (CSV?)  of the chart table that  matches the star label  number  that's found on the star chart? I don't know how this table is generated and my request may not be possible.

At the present I have my program ask for the Table for a specific variable star and then extract the info I want out of the HTML page that  is returned. The process is a bit of a kludge. A simple CSV file with the data in it would be great.

American Association of Variable Star Observers (AAVSO)

  When I started out learning about  Variable Star Observation, last month, I downloaded the VSX data from the web page as a CSV file and dumped it into my SQL DB. I noticed today that there is an option to extract last weeks changes from the VSX DB. I'm wondering if there is an API that  I could use to get the VSX data in a xml or csv form directly rather than going to the site manually and pulling the data.  If this were possible it would make it easy to keep my DB up to date. 



Vereniging Voor Sterrenkunde, Werkgroep Veranderlijke Sterren (Belgium) (VVS)

Hi Max,

The VOTable interface for VSX has not been maintained since it was created.  It never made the distinction between minimum magnitude or amplitude and didn't cater for different passbands or "fainter than" values.  I encourage the use of the VSX API instead: https://www.aavso.org/vsx/index.php?view=api.object&ident=pmak+v33.


American Association of Variable Star Observers (AAVSO)
Recommendation to VSX: if

Recommendation to VSX: if this interface really isn't maintained and if it delivers clearly wrong data, then let's start maintaining it or kill it.

American Association of Variable Star Observers (AAVSO)
VSX API documentation?

I've been using the votable interface for years and didn't even realize there was another option. A cursory search of the forums and the AAVSO site didn't turn up any documentation but I didn't spend a lot of time on it. I'm retrieving all variables within x arcminutes of a given position, rather than looking up a specific object.

Shawn (DKS)

American Association of Variable Star Observers (AAVSO)

Hi Patrick,

Thank you for the information!

This way is obviously simpler.

Best regards,


Vereniging Voor Sterrenkunde, Werkgroep Veranderlijke Sterren (Belgium) (VVS)
VSX API documentation

The VSX API is not "official" yet, but here is some documentation (some of it may be changed in the future).  There are two versions: object and list.  The general URL is:



The output format for both API's is given in https://www.aavso.org/vsx/index.php?view=api.xsd, unless specific formating parameters are used, see below.

The object API has one specific parameter: ident, the name of the object(s) requested (this may be a list delimited by commas).  These may be aliases, AUID's.  The name need not be spelled exactly as in VSX (e.g. spaces are not necessary, no distinction between V999 and V0999 ...).  Wildcard characters are not interpreted.
Note: a space in a URL is denoted as a plus sign (+), the + in the name (e.g. when the name contains the position of the object) needs to be URL encoded as %2B.

Example: https://www.aavso.org/vsx/index.php?view=api.object&ident=HIP39986

The list API has several specific parameters:

- fromra=, tora=, fromdec=, todec=: limiting values of right ascension and declination (epoch 2000) in degrees
- ra=, dec=, radius=: search for objects in an area with given right ascension and declination (epoch 2000) as center and radius in degrees
- tomag=: brightest magnitude needs to be brighter than the value given

Parameters used in both API's:
- att: use attributes instead of individual elements in the xml
- format=json: output format is json, not xml
- auid: only list objects with an AUID