TNS - Getting started



Japanese (partial) translation


As of January 1, 2016, the Transient Name Server (TNS) is the official IAU
mechanism for reporting new astronomical transients (ATs) such as supernova
candidates. Once spectroscopically confirmed, new supernova discoveries are
officially designated a SN name (of the form SN 2016A and so on, as before).
This is a continuation of the IAU naming scheme for supernovae which was
handled by the Central Bureau for Astronomical Telegrams until the end of 2015, 
and has been approved as the official IAU naming scheme by the IAU Executive 
Committee from 1st January 2016.

Variable stars and CVs, including in particular Galactic nova candidates, should
be reported in the same manner done prior to January 2016, and should not be
submitted to the TNS.

This service is provided by the IAU supernova working group, free of charge to
registered users, who can also choose to receive automated email alerts
regarding new discoveries.

If an event is not already known at the reported coordinates, a new name
is provided and this will serve as the formal unique designation of the

If an object already exists in the system at the reported location, the AT
report and its details will be formally saved (and associated with the existing
object), and the object's (existing) designation will be reported back.

A name of the form, e.g. 2016ab, defines the object uniquely. Before it is
spectroscopically classified it will have a prefix of "AT". If classified as a
SN of whichever type, the prefix changes to "SN".

[ Top ]

Registration, reporting methods

Submitting reports of any kind requires registration for a user account. This
registration will be open to all professional astronomers as well as to

To register, go to Login / Create new account.

AT reports (AT reps) and Classification reports (Class reps) can be submitted to
the TNS either by interactive forms (for individual users; this replicates
exactly the previous system) or via the Bulk reports method - submission of
JSON-formatted data or TSV lists in an automated way from defined machines
(we call "BOTS") of e.g. the various involved surveys.

[ Top ]

Email notifications

A registered user can define the notifications he/she wishes to receive from the
system. In the MY ACCOUNT page it is possible to specify if you wish to receive
immediate notifications or either a daily digest, for discovery and/or
classification reports, with the option to define a magnitude cut.
It is also possible to choose to receive immediate notifications whenever a new
transient is found to be coincident with sources of external catalogs. Currently
the KEGS catalog is active; additional catalogs will be added over time.

[ Top ]

Report forms

The interactive forms open from the REPORTS menu item, where there are two
 tabs, for the AT report and the Classification report forms.

Mandatory fields are marked with red asterisks.

AT rep: After the header section, a photometry section exists, where a last
non-detection should be specified, followed by specification of the discovery
photometry point (mandatory). Additional photometry points may be provided, as
well as any "related files" to go along with the AT rep (finding chart,
discovery image etc…).

If an instrument/filter/flux units are not found in the pop-down lists, The
value "Other" should be chosen, and the details should be described in the
following Comments field (e.g. Instrument=XXX, filter=XXX). The same holds for
the Class rep form.

Class rep: It is mandatory to provide at least one spectrum (for supporting the
classification); additional ones may be uploaded as well, and also here, any
relevant related files.

[ Top ]

API - Bulk reports

The Bulk API method allows for submission of AT or Class reports to the TNS via
JSON-formatted data or TSV (Tab-Separated-Values) lists in an automated way
from defined machines (BOTS) of e.g. the various contributing surveys.

The Bulk reports are being processed as promptly as possible in an
asynchronous mode, dependent on the actual incoming queue of reports and 
the server’s available resources.

We have set up on our SANDBOX site an API TEST FORM webpage where it is
possible to experiment with submission of reports using a dedicated form.

The development of the required codes and the experimentation with submission
of bulk reports should be done only against the SANDBOX environment.

Only after verifying that your JSON/TSV reports are submitted and 
processed in acorrect manner should you direct the submission of your 
reports to the real site.


A detailed manual of the Bulk API in pdf format can be obtained here.

Our PHP sample code can be downloaded from here.

A Python sample code, kindly provided by Ken Smith, can be downloaded from here.

Templates of the TSV lists are up on the SANDBOX BULK page.

[ Top ]


API - Change proprietary period

This API serves for updating the prop. period end date of reported entries, for
switching an AT report and/or classification report and/or spectra to public,
either on the same day or some future date (back-dating is not possible).
Only a bot that is associated with the group that submitted the report
(AT/Classification/spectra) can request to perform such a change to the prop.
period end date.


A detailed manual of the APIs in pdf format can be obtained here.

Our PHP Change prop. period sample code can be downloaded from here.

[ Top ]


API - Search/Get objects

The Search API serves for listing the object names (objname & prefix) satisfying
given search criteria.

The Get Object API retrieves object details per given object name, including its
associated photometry and/or spectra if requested.

Retrieving specific files (e.g. spectra ascii/FITS files) is possible via the
Get File API.


A detailed manual of the APIs in pdf format can be obtained here.

Our PHP Search/Get objects sample code can be downloaded from here.

[ Top ]


Groups, Proprietary period

Every registered user can create a new group (GROUPS menu item). Details of
the group should be filled in, including up to three group owners. Upon approval
of the group by the TNS administrators, users can ask to join the group, for the
group's owners to approve. A group can then be specified as the "source group"
for a reporting (Discovery/Classification), or be specified for sharing
private/proprietary data only among it's members as described below.

For both the AT rep and Class rep it is possible to request a proprietary

The data will then be visible and accessible only to members of the defined
"source group" and/or "associated groups".

For an AT rep, requesting a proprietary period means that the object is created
but will not be visible to non-members of the relevant group/s, unless other
people/surveys report the same event without requesting a proprietary period, or
one that expires sooner.

For Class reps, it is possible to request a proprietary period separately for
the classification itself (typing+redshift), or for the uploaded spectrum/a.

[ Top ]


"Discoverer" / "Classifier"

With respect to the proprietary period options just mentioned, the formal
"discoverer" of a transient is defined to be the reporter/s whose discovery report
first turns to public (or was immediately so). Likewise for "classifier".

[ Top ]


Search page

From the SEARCH page it is possible to perform all sorts of queries on the existing objects.

E.g. clicking the "Unclassified ATs" checkbox will list all reported ATs
that are not yet classified.

For each entry (object) in the retrieved list it is possible to open up
sub-tables displaying the related AT/Class reps and the spectrum/a if exist
for the object. Clicking on an object name directs to the Object page (e.g., where the details of the
object are shown, as well as interactive spectra plots.

Clicking on the icons under the Reps and Class columns link to the formal
"certificate" of the discovery and classification, respectively. This
replaces the former supernova CBET telegrams, and should be indexed by NED
and ADS. Links of the form or lead to
these certificates, which are available free of charge to anyone.

Note the additional query options under the "Advanced search" section, and
also the possibility to define which columns to display or hide.

[ Top ]


Statistics page

Our STATISTICS page, linkable from the TNS homepage, consists of 3 tabs for
viewing the following:
- The amount of transients, ATs and classified SNe, that have been reported 
to the TNS, by different cuts and for the top contributing groups.
- Timeline (history) plots of the received AT and classification reports. 
(Hovering on the data points reveals relevant information for the given date.)
- Full-Sky maps showing the projected locations of the reported
transients; by types and groups.

[ Top ]


LIGO GW Events

For every new GW event, alerted on by the GCN/LVC, we create sky maps
showing the localization contours, with all known public TNS transients that
are within the error regions over-plotted. We provide a map showing all
transients with discovery date BEFORE the GW event (i.e. these are not
potential counterparts), and also a map showing the transients having
discovery date AFTER the event. The latter is being updated on an hourly
basis during a period of 2 weeks after the GW event date. All maps and the
corresponding transient lists are downloadable as CSV/JSON files. Here's the
main LIGO GW page listing the existing GW events.

Past events (like the two events from 2015) are accessible to all; new events
are accessible only to members of groups that are part of the LV-EM MOU.

[ Top ]


Quick query links

Unclassified ATs:

Unclassified ATs within a discovery magnitude range (e.g. 15-17):

Classified SNe:


To download as CSV, add "&format=csv", e.g. for classified SNe:

Additional notes:

- The maximum allowed number of results per page is 1000 (num_page=1000).

- If downloading as CSV/TSV and the retrieved results surpass the maximum, you
may implement paging by specifying &page=X (0 being the 1st page), e.g.:

[ Top ]


Feedbacks and comments on all levels are clearly most welcome.

Email:,  or via the contact-us page.


The following people have been involved in the design, development and administration of the TNS:

Ofer Yaron, Avner Saas, Nikola Knezevic, Ilan Manulis, Eran Ofek and Avishay Gal-Yam.

Programs for producing the skymap projections were created by Gilad Margalit.

[ Top ]