Navigator's Sextant
8.1 / 10
841ms
50%
N/A
README
Navigator’s Sextant - A Comprehensive Solar Positioning Service
Table of Contents
Overview
Navigator’s Sextant is a specialized service designed for developers, navigators, and astronomy enthusiasts. The service provides precise solar positioning data, including sunrise, sunset, solar noon, and the solar position at any given time. This data is crucial for various applications like mapping, augmented reality apps, and navigation. The service is designed to expand in the future to include other astronomical values, enriching the data provided further.
Features
- Solar Positioning: Obtain precise solar positioning data including azimuth and elevation for any given time and location.
- Sunrise and Sunset: Get the exact times of sunrise and sunset for a specific location.
- Solar Noon: Determine the solar noon time for a particular day.
- Day Length: Calculate the total daylight duration for a specific day.
- Twilight Times: Acquire the times for various twilight phases including civil, nautical, and astronomical twilight.
- Time Zone Information: Retrieve the time zone information for any geographical location.
- Batch Solar Positioning: Get a batch of solar positioning data for a range of time, useful for visualizing solar movement over time.
Endpoints
/api/v1/sun: Get sunrise and sunset times./api/v1/noon: Get solar noon time./api/v1/daylength: Get the length of the day./api/v1/twilight: Get twilight times./api/v1/time: Get time zone information./api/v1/solar-position: Get solar position for a specific time./api/v1/solar-position-for-range: Get solar position data for a range of time.
Endpoint: /api/v1/sun
Method: GET
Description:
The /api/v1/sun endpoint provides sunrise and sunset times for a specified geographical location. This data is crucial for various applications including but not limited to photography, real estate, and outdoor event planning.
Request Parameters:
lat(Required): The latitude of the geographical location. Value should be between -90 and 90.lng(Required): The longitude of the geographical location. Value should be between -180 and 180.timezone(Required): The time zone of the geographical location.
Response Format:
The response will be a JSON object containing properties sunrise and sunset, indicating the times of sunrise and sunset respectively.
Response Example:
{
"sunrise": "06:12",
"sunset": "18:23"
}
Usage Example:
GET /api/v1/sun?lat=52.5200&lng=13.4050&timezone=Europe/Berlin
Note:
Ensure to replace 52.5200, 13.4050, and Europe/Berlin with your own latitude, longitude, and time zone values respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid latitude, longitude, or time zone values, you might receive a response like:
{
"error": "Invalid latitude, longitude, or time zone values."
}
Endpoint: /api/v1/noon
Method: GET
Description:
The /api/v1/noon endpoint provides the time of solar noon based on the sunrise and sunset times. Solar noon is the time when the Sun is at its highest point in the sky for the day, which is useful for various applications including solar energy planning and astronomy.
Request Parameters:
sunrise(Required): The time of sunrise.sunset(Required): The time of sunset.
Response Format:
The response will be a JSON object containing a single property solarNoon, indicating the time of solar noon.
Response Example:
{
"solarNoon": "12:18"
}
Usage Example:
GET /api/v1/noon?sunrise=06:12&sunset=18:23
Note:
Ensure to replace 06:12 and 18:23 with your own sunrise and sunset times respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid sunrise or sunset times, you might receive a response like:
{
"error": "Invalid sunrise or sunset times."
}
Endpoint: /api/v1/daylength
Method: GET
Description:
The /api/v1/daylength endpoint provides the total duration of daylight based on the sunrise and sunset times. This data is useful for various applications including energy planning, agriculture, and outdoor event planning.
Request Parameters:
sunrise(Required): The time of sunrise.sunset(Required): The time of sunset.
Response Format:
The response will be a JSON object containing a single property dayLength, indicating the total duration of daylight.
Response Example:
{
"dayLength": "12:11"
}
Usage Example:
GET /api/v1/daylength?sunrise=06:12&sunset=18:23
Note:
Ensure to replace 06:12 and 18:23 with your own sunrise and sunset times respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid sunrise or sunset times, you might receive a response like:
{
"error": "Invalid sunrise or sunset times."
}
Endpoint: /api/v1/twilight
Method: GET
Description:
The /api/v1/twilight endpoint provides the times for various twilight phases including civil, nautical, and astronomical twilight for a specified geographical location. This data is crucial for photographers, astronomers, and anyone interested in the different phases of twilight.
Request Parameters:
lat(Required): The latitude of the geographical location. Value should be between -90 and 90.lng(Required): The longitude of the geographical location. Value should be between -180 and 180.timezone(Required): The time zone of the geographical location.
Response Format:
The response will be a JSON object containing properties for the different twilight phases, indicating the start
and end times of each phase.
Response Example:
{
"civilTwilight": {
"start": "05:45",
"end": "06:12"
},
"nauticalTwilight": {
"start": "05:12",
"end": "05:45"
},
"astronomicalTwilight": {
"start": "04:38",
"end": "05:12"
}
}
Usage Example:
GET /api/v1/twilight?lat=52.5200&lng=13.4050&timezone=Europe/Berlin
Note:
Ensure to replace 52.5200, 13.4050, and Europe/Berlin with your own latitude, longitude, and time zone values respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid latitude, longitude, or time zone values, you might receive a response like:
{
"error": "Invalid latitude, longitude, or time zone values."
}
Endpoint: /api/v1/time
Method: GET
Description:
The /api/v1/time endpoint provides the time zone information for a specified geographical location. This data is crucial for various applications including scheduling, real-time communication, and global coordination.
Request Parameters:
lat(Required): The latitude of the geographical location. Value should be between -90 and 90.lng(Required): The longitude of the geographical location. Value should be between -180 and 180.
Response Format:
The response will be a JSON object containing a single property timezone, indicating the time zone of the specified location.
Response Example:
{
"timezone": "Europe/Berlin"
}
Usage Example:
GET /api/v1/time?lat=52.5200&lng=13.4050
Note:
Ensure to replace 52.5200 and 13.4050 with your own latitude and longitude values respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid latitude or longitude values, you might receive a response like:
{
"error": "Invalid latitude or longitude values."
}
Endpoint: /api/v1/solar-position
Method: GET
Description:
The /api/v1/solar-position endpoint provides the solar position including azimuth and elevation for a specified geographical location and time. This data is crucial for various applications including solar energy planning, astronomy, and augmented reality apps.
Request Parameters:
lat(Required): The latitude of the geographical location. Value should be between -90 and 90.lng(Required): The longitude of the geographical location. Value should be between -180 and 180.dateTime(Required): The date and time for which the solar position is desired, in the formatYYYY-MM-DDTHH:MM:SS.
Response Format:
The response will be a JSON object containing properties azimuth and elevation, indicating the solar azimuth and elevation respectively.
Response Example:
{
"azimuth": 135.0,
"elevation": 45.0
}
Usage Example:
GET /api/v1/solar-position?lat=52.5200&lng=13.4050&dateTime=2023-09-26T12:00:00
Note:
Ensure to replace 52.5200, 13.4050, and 2023-09-26T12:00:00 with your own latitude, longitude, and date-time values respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid latitude, longitude, or date-time values, you might receive a response like:
{
"error": "Invalid latitude, longitude, or date-time values."
}
Endpoint: /api/v1/solar-position-for-range
Method: GET
Description:
The /api/v1/solar-position-for-range endpoint provides a batch of solar positioning data for a specified time range, geographical location, and time step. This data is useful for visualizing the solar movement over time, which is crucial for various applications including solar energy planning, astronomy, and augmented reality apps.
Request Parameters:
lat(Required): The latitude of the geographical location. Value should be between -90 and 90.lng(Required): The longitude of the geographical location. Value should be between -180 and 180.startTime(Required): The start time for the range, in the formatYYYY-MM-DDTHH:MM:SS.endTime(Required): The end time for the range, in the formatYYYY-MM-DDTHH:MM:SS.stepsInMinutes(Required): The time step in minutes for which solar positioning data is desired.
Response Format:
The response will be a JSON array containing objects with properties azimuth and elevation, indicating the solar azimuth and elevation for each time step within the specified range.
Response Example:
[
{
"azimuth": 135.0,
"elevation": 45.0
},
{
"azimuth": 136.0,
"elevation": 46.0
},
// ... more data points
]
Usage Example:
GET /api/v1/solar-position-for-range?lat=52.5200&lng=13.4050&startTime=2023-09-26T06:00:00&endTime=2023-09-26T18:00:00&stepsInMinutes=30
Note:
Ensure to replace 52.5200, 13.4050, 2023-09-26T06:00:00, 2023-09-26T18:00:00, and 30 with your own latitude, longitude, start time, end time, and steps in minutes values respectively.
Error Handling:
Errors are returned in a standard format. For instance, if you pass invalid latitude, longitude, time values, or steps in minutes values, you might receive a response like:
{
"error": "Invalid latitude, longitude, time values, or steps in minutes values."
}
Navigator’s Sextant is a robust and comprehensive service that provides crucial solar positioning data, enabling developers, navigators, and astronomy enthusiasts to harness the power of solar data for their projects and applications.
