JPL Horizons is a web app and API for access to up to date and historic information about parameters of the solar system, e.g. orbital parameters.
This library is an ultra basic (for now?) interface to the API. It requires you to manually construct tables for the options you want. Best to look at the documentation and the web app:
https://ssd.jpl.nasa.gov/horizons/app.html
To give a simple example though. Assume we want to know the distance between Sun and Earth for every day of last year (2022). We can do that as follows (see examples/sun_earth_distance.nim)
import ../horizonsapi
import std / [asyncdispatch, strutils]
# let's try a simple request
let comOpt = { #coFormat : "json", # data returned as "fake" JSON
coMakeEphem : "YES",
coCommand : "10", # our target is the Sun, index 10
coEphemType : "OBSERVER" }.toTable # observational parameters
let ephOpt = { eoCenter : "coord@399", # observational point is a coordinate on Earth (Earth idx 399)
eoStartTime : "2022-01-01",
eoStopTime : "2022-12-31",
eoStepSize : "1 HOURS", # in 1 hour steps
eoCoordType : "GEODETIC",
eoSiteCoord : "+0.0,+51.477806,0", # Greenwich coordinates, because why not?
# First East/West than North/South! Last field is altitude
eoCSVFormat : "YES" }.toTable # data as CSV within the JSON (yes, really)
var q: Quantities
q.incl 20 ## Observer range! In this case range between our coordinates on Earth and target
let fut = request(comOpt, ephOpt, q) # construct the request & perform it async
## If multiple we would `poll`!
let res = fut.waitFor() # wait for it
let resJ = res.parseJson# result is json, so can parse it
for l in resJ["result"].getStr.splitLines()[0 .. 30]:
echo l
## Or alternatively: Construct a HorizonsRequest object and use `getResponses`, which
## takes a `seq` of requests and processes them concurrently. The result is a
## `seq[HorizonsResponse]`, which has seen very basic parsing. The data is split
## into a header, footer and a data section. The data section (if `eoCSVFormat` is
## set to 'YES') can be parsed e.g. with datamancer's `parseCsvString`
import datamancer
block Alt:
let req = initHorizonsRequest(comOpt, ephOpt, q)
let res = getResponses(@[req])
let df = parseCsvString(res[0].csvData)
echo df*******************************************************************************
Revised: July 31, 2013 Sun 10
PHYSICAL PROPERTIES (updated 2018-Aug-15):
GM, km^3/s^2 = 132712440041.93938 Mass, 10^24 kg = ~1988500
Vol. mean radius, km = 695700 Volume, 10^12 km^3 = 1412000
Solar radius (IAU) = 696000 km Mean density, g/cm^3 = 1.408
Radius (photosphere) = 696500 km Angular diam at 1 AU = 1919.3"
Photosphere temp., K = 6600 (bottom) Photosphere temp., K = 4400(top)
Photospheric depth = ~500 km Chromospheric depth = ~2500 km
Flatness, f = 0.00005 Adopted sid. rot. per.= 25.38 d
Surface gravity = 274.0 m/s^2 Escape speed, km/s = 617.7
Pole (RA,DEC), deg. = (286.13, 63.87) Obliquity to ecliptic = 7.25 deg.
Solar constant (1 AU) = 1367.6 W/m^2 Luminosity, 10^24 J/s = 382.8
Mass-energy conv rate = 4.260 x 10^9 kg/s Effective temp, K = 5772
Sunspot cycle = 11.4 yr Cycle 24 sunspot min. = 2008 A.D.
Motion relative to nearby stars = apex : R.A.= 271 deg.; DEC.= +30 deg.
speed: 19.4 km/s (0.0112 au/day)
Motion relative to 2.73K BB/CBR = apex : l= 264.7 +- 0.8; b= 48.2 +- 0.5 deg.
speed: 369 +-11 km/s
*******************************************************************************
*******************************************************************************
Ephemeris / API_USER Wed Jun 28 06:51:58 2023 Pasadena, USA / Horizons
*******************************************************************************
Target body name: Sun (10) {source: DE441}
Center body name: Earth (399) {source: DE441}
Center-site name: (user defined site below)
*******************************************************************************
# From the `Alt` block
DataFrame with 6 columns and 8737 rows:
Idx Date__(UT)__HR:MN Unnamed0 Unnamed1 delta deldot Unnamed2
dtype: string string string float float object
0 2022-Jan-01 00:00 "" "" 0.9834 -0.01627 null
1 2022-Jan-01 01:00 "" "" 0.9834 -0.08504 null
2 2022-Jan-01 02:00 "" "" 0.9834 -0.1494 null
3 2022-Jan-01 03:00 "" "" 0.9834 -0.2049 null
4 2022-Jan-01 04:00 "" "" 0.9834 -0.2478 null
5 2022-Jan-01 05:00 "" "" 0.9834 -0.2751 null
6 2022-Jan-01 06:00 "" "" 0.9834 -0.2849 null
7 2022-Jan-01 07:00 N m 0.9834 -0.2767 null
8 2022-Jan-01 08:00 C m 0.9834 -0.2508 null
9 2022-Jan-01 09:00 * m 0.9833 -0.2091 null
10 2022-Jan-01 10:00 * m 0.9833 -0.1543 null
11 2022-Jan-01 11:00 * m 0.9833 -0.09027 null
12 2022-Jan-01 12:00 * m 0.9833 -0.02123 null
13 2022-Jan-01 13:00 * m 0.9833 0.04809 null
14 2022-Jan-01 14:00 * m 0.9833 0.113 null
15 2022-Jan-01 15:00 * "" 0.9833 0.1691 null
16 2022-Jan-01 16:00 * "" 0.9833 0.2125 null
17 2022-Jan-01 17:00 N "" 0.9834 0.2404 null
18 2022-Jan-01 18:00 A "" 0.9834 0.2509 null
19 2022-Jan-01 19:00 "" "" 0.9834 0.2432 null
The actual body of the requested data starts further down.