lcogt / whatsup

Find what astronomical objects are visible above LCO sites

Whats UP

Find what astronomical objects are visible above LCO sites from a curated list.

• /whatsup - Application address

Returned values

Each call (from either endpoint) will return JSON response similar to below. datetime is the date and time the call was made.

{
  "count": 113,
  "datetime": "2017-08-08T09:28:10",
  "targets":	[...],
	"site":"ogg",
}

The targets field (i.e. [...] above) will display to a list of multiple visible targets, in the format below.

{
    "name": "NGC7479",
    "ra": 346.2361167,
    "dec": 12.3228778,
    "desc": "NGC 7479 (also known as Caldwell 44) is a barred spiral galaxy about 105 million light-years away in the constellation Pegasus. This is a beautiful barred spiral galaxy, seen almost face on.",
    "filters": [
        {
            "exposure": 240.0,
            "name": "rp"
        },
        {
            "exposure": 240.0,
            "name": "V"
        },
        {
            "exposure": 240.0,
            "name": "B"
        }
    ],
    "avmdesc": "Barred Galaxy",
    "avmcode": "5.3.2.2;5.1.2"
},

All suggested exposure times are scaled dependent on the aperture parameter and targets filtered to be appropriate to the field of view for the specified aperture.

Endpoints

Search

Accessed from /whatsup/search/. All visible objects are displayed.

Visibility

We calculate the visibility of targets in the Whats Up database by filtering only those targets which are within +/- 3.5 hours of the Local Sidereal Time at the specified site and start. We only display those targets greater than 30º above the horizon at start. Further filtering is performed using aperture, as the different field of views of LCO telescope classes can make some targets too large or small in images.

Parameters

The form/API expects the following querystring parameters:

• start - format must be YYY-MM-DDTHH:MM:SS in UTC,
• site - 3-letter site code for LCO sites. Options ogg, coj, elp, lsc, or cpt.
• aperture - size of telescope. Options 2m0, 1m0, or 0m4.
• category (optional) - filter by AVM category of target, e.g. 5.1.1 = Spiral Galaxies
• mode (optional) - Options are rti or normal(default). rti filters the results to only those with exposure times < 600s. normal does not provide any filtering.
• format (optional) - Which schema to respond to requests. Options are json (default), jsonp or api (web browser view).

Example usage

Using required arguments only start, aperture and site:

https://lco.global/whatsup/search/?start=2017-08-08T09:28:10&aperture=0m4&site=ogg

A full example of all available arguments is:

https://lco.global/whatsup/search/?start=2017-08-08T09:28:10&aperture=1m0&site=ogg&category=5.1.1&format=jsonp

Date Range

Accessed from /whatsup/range/. Provides a list of targets visible in northern and southern hemisphere during specified time range.

Visibility

We calculate the Right Ascension of the Sun at the midpoint between start and end. Targets in the Whats Up database are then filtering only those targets which are outside +/- 4 hours of the Sun's Right Ascension. Further filtering is performed using aperture, as the different field of views of LCO telescope classes can make some targets too large or small in images.

Parameters

The form/API expects the following querystring parameters:

• start - format must be YYY-MM-DDTHH:MM:SS in UTC,
• end - format must be YYY-MM-DDTHH:MM:SS in UTC,
• aperture - size of telescope. Can have values 2m0, 1m0, or 0m4.
• full=true/false (optional) - Show full or truncated list of results. Defaults to false where a maximum of 30 random results are displayed.
• category (optional) - filter by AVM category of target, e.g. 5.1.1 = Spiral Galaxies
• format=jsonp (optional) - for jsonp requests. Defaults to json

Example usage

Using required arguments only start, end and aperture:

https://lco.global/whatsup/range/?start=2017-08-08T10:00:00&end=2017-08-17T10:00:00&aperture=0m4

A full example of all available arguments is:

https://lco.global/whatsup/range/?start=2017-08-08T10:00:00&end=2017-08-17T10:00:00&aperture=0m4&category=5.1.1&full=true&format=jsonp

Build

This project is built automatically by the LCO Jenkins Server. Please see the Jenkinsfile for details.

whatsup's Issues

Add usage instructions on the README

Some basic instructions would be a start.

Add multiple filters and exposure times

Different telescope classes need different exposure time settings per object. To make WhatsUP more flexible (i.e. not just to provide 'pretty' pictures targets) we need to be able to provide exposure times per filter and per telescope.

I'm proposing having an alternative URL for these results, so we can update this app and not break apps that use WhatsUP.

Allow any site

API only currently allows for LCOGT sites to be specified by 3-letter airport code. Extend this API so latitude and longitude can be used instead.

Use Django REST framework

This project is mainly an API service. At present all of the API end points are hand-rolled. It would be much more sustainable if these were to use Django REST framework intead

Add documentation

We don't even have any basic documentation. Some details of how you use the service would be useful.

Licensing

Hi,

There is License.txt and License on the root of the repo. Should we just keep one?
Given that license, should we bother rewriting a shorter version of this license on each file? (at least some of them have a license part at the beginning of the file.)
I feel like it's pointless and make the code less easy to read. The shorter the better. =)

Add unittests

Create unit tests using py.test to have good coverage of the app.

Upgrade to Django 1.8.2

Should be fairly easy to update Django in this app.

Non API interface

There is a pretty basic form if you go to WhatsUP. It would be useful if this returned HTML results instead of just the API response.