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.
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.
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": {
},
}The Nocturnal API has the following endpoints:
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).
The Nocturnal development stack can be built with the following docker compose command:
$ docker compose -f local.yml buildThe Nocturnal development stack can then be started with:
$ docker compose -f local.yml upor simply by utilising the following combined command:
docker compose -f local.yml up --buildThe Nocturnal development stack can be tested with the following command:
GIN_MODE=release bash -c "go test ./... -race -coverprofile=coverage.txt -covermode=atomic -v"