observerly / nocturnal

🌑 Nocturnal is observerly's Gin Gonic API for Lunar and Solar advanced scheduling, that utilises Dusk.

Nocturnal 🌑 is observerly's Gin Gonic API for Lunar and Solar advanced scheduling, that utilises Dusk, available at https://nocturnal.observerly.com as a highly performant public API.

The Nocturnal API is designed to be stateless, and to return a response based on the current time, and the parameters passed to the API.

Please note, the specifics of the Nocturnal API is currently in active development, and is subject to without warning.

Usage

Introduction

As mentioned, the Nocturnal API is designed to be stateless. That is, a request to the API will return a response based on the current time, and the parameters passed to the API.

This means that the API can be used to understanding the position of the Moon, the Sun, or any transiting body (e.g., a Star) at any time in the past, present, or future.

Schema

The Nocturnal base URL for the API will be {HOST}/api/v2/ where {HOST} is the host name of the API, e.g., https://nocturnal.observerly.com.

There is a deprecate version of the API, but as of 14.02.2023 we do not recommend its use. The deprecate version of the API is available at {HOST}/api/v1/ where {HOST} is the host name of the API, e.g., https://nocturnal.observerly.com.

The Nocturnal API has a standardised API JSON response format, which adheres to the JSON API specification as well as the schema defined in the OpenAPI specification.

For Sun, Moon and Transit endpoints, the API JSON response adheres to the following schema:

{
  "observer": {
    
  },
  "rise": {

  },
  "maximum": {

  },
  "set": {

  },
}

For Twilight endpoints, the API JSON response adheres to the following schema:

{
  "observer": {
    
  },
  "civil": {

  },
  "nautical": {

  },
  "astronomical": {

  },
}

API Endpoints

The Nocturnal API has the following endpoints:

• GET /api/v2/sun

• GET /api/v2/moon

• GET /api/v2/transit

• GET /api/v2/twilight

API Development

Project Requirements

We welcome any and all contributions or raised issues to this repository.

To contribute to this project, you will need the following tools installed on your local machine:

• Docker.
• Docker Compose.
• Go version 1.17+ (or later).

Local Development

The Nocturnal development stack can be built with the following docker compose command:

$ docker compose -f local.yml build

The Nocturnal development stack can then be started with:

$ docker compose -f local.yml up

or simply by utilising the following combined command:

docker compose -f local.yml up --build

Testing

The Nocturnal development stack can be tested with the following command:

GIN_MODE=release bash -c "go test ./... -race -coverprofile=coverage.txt -covermode=atomic -v"

nocturnal's Issues

feat: Provide angular separation between object and the Moon

Currently, the nocturnal endpoints provide the following details on e.g., https://nocturnal.observerly.com/api/v1/transit?datetime=2021-05-15T00:00:00.000Z&longitude=-155.468094&latitude=19.798484&ra=88.7929583&dec=7.4070639:

{
  "observer": {
    "datetime": "2021-05-15T00:00:00Z",
    "latitude": "19.798484",
    "longitude": "-155.468094"
  },
  "position": {
    "alt": "73.448912",
    "az": "136.917066",
    "dec": "7.407064",
    "ra": "88.792958"
  },
  "transit": {
    "rise": "2021-05-15T08:31:29-10:00",
    "set": "2021-05-15T20:50:55-10:00"
  }
}

It would be incredibly useful that we provide various lunar parameters for the duration of the transit, such as the angular separation between the Moon and the object of interest as well as the average lunar illumination, determining an estimated observation quality for the given object.

feat: Provide transit maximum object altitude

Currently, the nocturnal endpoints provide the following details on e.g., https://nocturnal.observerly.com/api/v1/transit?datetime=2021-05-15T00:00:00.000Z&longitude=-155.468094&latitude=19.798484&ra=88.7929583&dec=7.4070639:

{
  "observer": {
    "datetime": "2021-05-15T00:00:00Z",
    "latitude": "19.798484",
    "longitude": "-155.468094"
  },
  "position": {
    "alt": "73.448912",
    "az": "136.917066",
    "dec": "7.407064",
    "ra": "88.792958"
  },
  "transit": {
    "rise": "2021-05-15T08:31:29-10:00",
    "set": "2021-05-15T20:50:55-10:00"
  }
}

It would be incredibly useful that we provide a range of preferred observation, close the maximum transitory altitude and at least +15° above local observer's horizon (i.e., when the object cross the observer's meridian*).

The following calculation from Meeus, Jean. 1991. Astronomical algorithms. Richmond, Va: Willmann - Bell. on p.104 will be needed:

*The observer's meridian is defined as the line which passes through the zenith and the south point on the horizon.

fix: Incorrect Transit.Rise & Transit.Set for non-zero hour date times.

When passing in a particular datetime to the API that is not 2021-05-14T00:00:00.000Z the API returns incorrect set and rise times.

The correct rise and set times are only for the 2021-05-14T00:00:00.000Z datetime passed in.

The returned date times are offset by the same amount, i.e., 6am adds 6 hours to the final maximum, rise and set times.

Endpoint: https://nocturnal.observerly.com/api/v1/transit?datetime=2022-05-15T00:00:00.000Z&longitude=-155.468094&latitude=19.798484&ra=88.7929583&dec=7.4070639

This is an issue with the downstream dusk.GetObjectRiseObjectSetTimesInUTCForDay() whereby the datetime passed in has not been normalised to the 00:00:00.000 time for the datetime given.