This python-based http API supports the main Helioviewer API (PHP) by providing interfaces to functions written in python.
This allows Helioviewer to take advantage of libraries in the python ecosystem (i.e. sunpy, astropy) without needing to fully migrate the Helioviewer back-end to python. The API is meant to run in parallel with Helioviewer.
Running with docker:
docker run --rm -t ghcr.io/helioviewer-project/coordinator
Running manually with python
pip install -r requirements.txt
python -m fastapi run main.py
The server hosts the following routes
Convert a heliographic stonyhurst coordinate into a helioprojective coordinate.
| query parameter | description |
|---|---|
| lat | Latitude coordinate in degrees |
| lon | Longitude coordinate in degrees |
| coord_time | Time that the measurement was taken |
| target | (Optional) Desired observation time. Applies differential rotation |
Returns:
{ x: float, y: float }
Convert a heliographic carrington coordinate into a helioprojective coordinate. Carrington longitude is observer-dependent (it accounts for light travel time), so an observer is required; it defaults to earth.
| query parameter | description |
|---|---|
| lat | Latitude coordinate in degrees |
| lon | Carrington longitude coordinate in degrees |
| coord_time | Time that the measurement was taken |
| target | (Optional) Desired observation time. Applies differential rotation |
| observer | (Optional) Solar-system body the coordinate is observed from (case-insensitive). Defaults to earth. See valid observers below; any other value returns 422 |
Returns:
{ x: float, y: float }
observer (on both the GET and POST routes) must be one of the solar-system
bodies sunpy can resolve (case-insensitive). Any other value returns HTTP 422.
earth, earth-moon-barycenter, jupiter, mars, mercury, moon,
neptune, saturn, sun, uranus, venus
Batch version of GET /hgc2hpc: convert a list of heliographic carrington
coordinates (one or more) against a single target observation time. The
optional observer applies to every coordinate in the batch, defaults to
earth, and follows the same valid observers rule.
{
"coordinates": [
{ "lat": 0, "lon": 117.7, "coord_time": "2012-01-01 00:00:00" },
{ "lat": 10, "lon": 20, "coord_time": "2013-06-01 00:00:00" }
],
"target": "2024-01-02 00:00:00",
"observer": "earth"
}Returns:
{
"coordinates": [
{ "x": float, "y": float },
...
]
}Normalize a helioprojective coordinate into Helioviewer's coordinate frame.
| query parameter | description |
|---|---|
| x | X position in arcseconds |
| y | Y position in arcseconds |
| coord_time | Time that the measurement was taken |
| target | (Optional) Desired observation time. Applies differential rotation |
Returns:
{ x: float, y: float }
Transforms a list of GSE coordinates to Heliographic Stonyhurst coordinates using a constant frame of reference. The reference frame is the coordinate frame used for Heliographic Stonyhurst at 2025-01-01 00:00:00 UTC. All coordinate transformations are done using sunpy and assume the sun remains at the origin of the system.
{
"coordinates": [
{
"x": number in kilometers,
"y": number in kilometers,
"z": number in kilometers,
"time": string (Y-m-d H:M:S)
},
...
]
}Returns the same format, but with the point in the new coordinate frame
{
"coordinates": [
{
"x": number,
"y": number,
"z": number,
"time: string (Y-m-d H:M:S)
},
...
]
}Get the position of an observatory over a time range. The observatory path
parameter is any body sunpy can resolve (e.g. SDO, SOHO, STEREO_A).
| query parameter | description |
|---|---|
| start | Start of the time range |
| stop | End of the time range |
Returns a list of positions (in kilometers) in Helioviewer's 3D frame:
{
"coordinates": [
{ "x": number, "y": number, "z": number, "time": "Y-m-d H:M:S" },
...
]
}