API Documentation: Heliocentric Coordinates using Keplerian Elements

This API provides a convenient way to access planetary data and compute their positions using Julian dates. Keplerian coordinates are used to describe the orbits of planets, which is essential for accurate position calculations. By leveraging this API, users can easily retrieve information about planets and determine their positions at any given time. This is particularly useful for astronomers, educators, and developers who need precise planetary data for simulations, educational purposes, or software development. The lack of other easy-to-use Keplerian Coordinate APIs makes this tool invaluable for anyone interested in celestial mechanics.

Running the API

Before you can use the API, ensure you have the latest version of Python 3 installed on your system. Follow these steps to run the API on your backend:

Prerequisites

Latest version of Python 3 installed.

Steps to Run the API

Open your terminal or command prompt.
Navigate to the directory where your API code is located.
Run the following command to start a simple HTTP server:
```
python -m http.server PORT_NUM
                
```
NOTE: Ensure that the specified port (PORT_NUM) is free, or the server will fail to run.

Accessing the API

Once the server is running, you can access the API using the following base URL:

http://127.0.0.1:PORT_NUM/

If you host the API on a server backend, use the IP address and port of that host, or the domain you connect it to, to access the API for your applications.

Please note that you will need to host the API yourself as we, the Concept Squad team, cannot afford to host it.

Endpoints

GET /planets

Retrieves a list of planets in the solar system.

Response

Returns a list of planets.

{
    "planets": ["Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune"]
}

POST /planet-position

Calculates the position of a specified planet based on the provided Julian date. A Julian date is a continuous count of days since the beginning of the Julian Period used primarily by astronomers.

Request Parameters

planet_name (string, required): The name of the planet (e.g., "Earth").
julian_date (float, required): The Julian date for which the position is calculated.

Example Request

POST /planet-position
Content-Type: application/x-www-form-urlencoded

planet_name=Earth&julian_date=2459580.5

Response

Returns the calculated position of the planet in both astronomical units (AU) and kilometers (km).

{
    "X-Coordinate (AU)": -0.1747647126957856,
    "X-Coordinate (km)": -26144428.892786782,
    "Y-Coordinate (AU)": 0.9676399687363331,
    "Y-Coordinate (km)": 144756878.92716998,
    "Z-Coordinate (AU)": -5.766446899769128e-05,
    "Z-Coordinate (km)": -8626.481777100778,
    "message": "Calculating position for Earth on Julian Date 2459580.5"
}

Frontend Pages

The following frontend pages are available for user interaction:

/position: A page to input a planet's name and Julian date to calculate its position.

Usage Example

Here is a brief example of how to use the API with JavaScript to calculate the position of a planet:

fetch('http:///position', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'planet_name=Earth&julian_date=2459580.5'
})
.then(response => response.json())
.then(data => console.log(data));

Conclusion

This API provides a straightforward way to access planetary data and calculate their positions based on Julian dates, facilitating further exploration and understanding of celestial mechanics.