← Back to workspace
STKCRAFT / DEVELOPERS / API REFERENCE
REFERENCE · LOCAL SERVER

GeoCalc API

Explore the geometry and time interfaces behind the workspace. Requests are served by the configured STKCraft engines and ordered kernel context.

JSON over HTTPNAIF ET seconds24 discovered operations

Overview

The server exposes calculation discovery, geometry and event search, and checked UTC–ET conversion. Values are passed to the underlying Rust libraries. Kernel selection is configured on the server; clients do not supply filesystem paths.

Contract and scope

These endpoints are the STKCraft server contract. They are not yet a complete implementation of every NASA WebGeocalc HTTP request or option. A displayed decimal match does not prove equality of NASA’s undisclosed internal values.

Calculation catalog

GET/api/catalogReturns supported operations and JSON input schemas

The catalog is read from the running geometry backend, so it reflects its actual supported tools. If the backend cannot start, the server returns HTTP 503 with an error.

Run a calculation

POST/api/calculateRun one calculation using server-configured kernels

Provide an operation name from the catalog and its parameters. All numeric epochs are TDB seconds past J2000 (NAIF ET); distances are kilometres unless the operation states otherwise.

{
  "operation": "state_vector",
  "parameters": {
    "target": 301,
    "observer": 399,
    "epoch_et": 0,
    "correction": "NONE"
  }
}

The result contains the backend’s structured columns, rows and raw CSV, plus a NASA comparison status, source, and mapped output cells when a verified live request mapping exists. Unsupported mappings are explicitly reported. NASA display equality does not prove binary or kernel equality. Invalid inputs and backend failures return an error instead of an estimated result.

Time conversion

POST/api/timeConvert checked UTC and NAIF ET with the configured LSK
{
  "direction": "utc_to_et",
  "utc": {
    "year": 2024,
    "month": 1,
    "day": 1,
    "hour": 0,
    "minute": 0,
    "second": 0
  }
}

For the reverse conversion use { "direction": "et_to_utc", "et": 0 }. Leap seconds and accepted date ranges are governed by STKCraft-time and the selected leap-second kernel.

POST/api/time/convertUse the discovered STKCraft-time operations
{
  "operation": "utc_to_et",
  "parameters": {
    "year": 2024,
    "month": 1,
    "day": 1,
    "hour": 0,
    "minute": 0,
    "second": 0
  }
}

The server supplies LSK, EOP and SCLK paths from its configuration. UT1 and spacecraft-clock operations require their respective configured data. UTC/ET conversions use the same checked TimeContext as the timeline.

LSK Infolsk_info
⌄

Report leap-second kernel coverage, entries, source and policy. Uses the bundled naif0012.tls unless lsk_path is supplied.

Delta Atdelta_at
⌄

Return TAI-UTC in whole seconds for a UTC date. Supply jdn, or year/month/day.

calendarstring
dayinteger
jdnintegerJulian Day Number; overrides year/month/day
monthinteger
yearinteger
UTC To TAIutc_to_tai
⌄

Convert a civil UTC date and time to TAI. Rejects 23:59:60 without a positive leap second and 23:59:59 on a shortened day.

calendarstring
dayinteger · required
hourinteger · required
minuteinteger · required
monthinteger · required
secondnumber · requiredSeconds including fraction; 60.x is legal on a positive leap-second day
yearinteger · requiredAstronomical year
TAI To UTCtai_to_utc
⌄

Convert TAI seconds past 2000-01-01T00:00:00 TAI to civil UTC.

calendarstring
nanosintegerNanoseconds for sec
secintegerWhole TAI seconds; use with nanos instead of tai_seconds
tai_secondsnumberTAI seconds past 2000-01-01T00:00:00 TAI
UTC To ETutc_to_et
⌄

Convert civil UTC to NAIF ET (TDB seconds past J2000).

calendarstring
dayinteger · required
hourinteger · required
minuteinteger · required
monthinteger · required
secondnumber · requiredSeconds including fraction; 60.x is legal on a positive leap-second day
yearinteger · requiredAstronomical year
ET To UTCet_to_utc
⌄

Convert NAIF ET (TDB seconds past J2000) to civil UTC.

calendarstring
etnumber · requiredNAIF ET: TDB seconds past J2000
TAI To TTtai_to_tt
⌄

Convert TAI seconds past 2000-01-01T00:00:00 TAI to TT seconds past J2000 TT.

calendarstring
nanosintegerNanoseconds for sec
secintegerWhole TAI seconds; use with nanos instead of tai_seconds
tai_secondsnumberTAI seconds past 2000-01-01T00:00:00 TAI
TAI To GPStai_to_gps
⌄

Convert a TAI epoch to GPS seconds past the GPS epoch (1980-01-06T00:00:00 UTC).

nanosintegerNanoseconds for sec
secintegerWhole TAI seconds; use with nanos instead of tai_seconds
tai_secondsnumberTAI seconds past 2000-01-01T00:00:00 TAI
GPS To TAIgps_to_tai
⌄

Convert GPS seconds past the GPS epoch to a TAI epoch.

gps_secondsnumber · requiredGPS seconds past 1980-01-06T00:00:00 UTC
WGC Week TOW To ETwgc_week_tow_to_et
⌄

Convert an observed WGC GPS week/TOW input string to checked NAIF ET.

week_towstring · required
WGC GPS Seconds To ETwgc_gps_seconds_to_et
⌄

Convert finite GPS seconds past GPS zero through the WGC-compatible native path to ET.

gps_secondsnumber · required
WGC ET To GPS Secondswgc_et_to_gps_seconds
⌄

Format ET as WGC's six-decimal numeric GPS seconds display cell.

calendarstring
etnumber · requiredNAIF ET: TDB seconds past J2000
WGC GPS Seconds To Week TOWwgc_gps_seconds_to_week_tow
⌄

Format GPS seconds in the observed WGC week/TOW display convention.

gps_secondsnumber · required
WGC ET To Calendarwgc_et_to_calendar
⌄

Format ET as six-decimal WGC YMD or day-of-year calendar output.

etnumber · required
formatstring · required
systemstring · required
UTC To UT1utc_to_ut1
⌄

Convert civil UTC to UT1 seconds past 2000-01-01T00:00:00 UT1 using an IERS EOP file.

calendarstring
dayinteger · required
eop_seriesstring
hourinteger · required
minuteinteger · required
monthinteger · required
observed_onlyboolean
secondnumber · requiredSeconds including fraction; 60.x is legal on a positive leap-second day
yearinteger · requiredAstronomical year
UT1 To UTCut1_to_utc
⌄

Convert UT1 seconds past 2000-01-01T00:00:00 UT1 to civil UTC using an IERS EOP file.

calendarstring
eop_seriesstring
observed_onlyboolean
ut1_secondsnumber · required
SCLK To ETsclk_to_et
⌄

Convert spacecraft clock ticks or a clock string to ET and TAI using a type-1 SCLK kernel.

clock_stringstringFormatted clock string, e.g. `123:45`
spacecraft_idinteger · requiredNAIF clock id, either sign
ticksnumberEncoded tick count
ET To SCLKet_to_sclk
⌄

Convert ET to spacecraft clock ticks, fields and a formatted clock string.

etnumber · requiredTDB seconds past J2000
spacecraft_idinteger · requiredNAIF clock id, either sign
Format UTCformat_utc
⌄

Format a civil UTC date/time as ISO 8601, RFC 3339, RFC 2822, SPICE calendar or strftime. Rounding uses the leap-second table, so 23:59:59.9999 on a leap-second day becomes 23:59:60.000 instead of the next day.

calendarstringCalendar used for day carries; default gregorian
dayinteger · required
hourinteger · required
kindstring
minuteinteger · required
monthinteger · required
patternstringstrftime pattern when kind=strftime
precisionintegerFractional digits for ISO/RFC 3339/SPICE
secondnumber · required
yearinteger · required
Etcaletcal
⌄

Format ET as a SPICE calendar TDB string without a leap-second kernel.

etnumber · required
precisioninteger

Solar system scene

POST/api/sceneGeometric positions at the timeline epoch
{
  "epoch_et": 0
}

Sun and Moon positions are relative to Earth; other returned positions are relative to the Sun in J2000. The result identifies centers and system barycenters, and lists unavailable bodies.

POST/api/trajectoriesSPICE position samples around the selected ET

Each track contains 65 geometric position samples in kilometres, relative to the Sun. A null sample means that position was unavailable. Lines drawn between samples are visual interpolation and do not alter the numerical calculations.

Operations & fields

Expand an operation to inspect its backend-discovered inputs. The server provides the kernels field. Finder confinement is an array of { start, end } intervals in ET seconds.

State vectorstate_vector
⌄

state_vector through the existing state backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
observerinteger · required
targetinteger · required
Angular separationangular_separation
⌄

angular_separation through the existing separation backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
observerinteger · required
shape1stringDefault: POINT
shape2stringDefault: POINT
target1integer · required
target2integer · required
Phase anglephase_angle
⌄

phase_angle through the existing phase backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
illuminatorintegerDefault: 10
observerinteger · required
targetinteger · required
Angular sizeangular_size
⌄

angular_size through the existing size backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
methodstringDefault: MAX_RADIUS
observerinteger · required
targetinteger · required
target_framestring
Orbital elementsosculating_elements
⌄

osculating_elements through the existing elements backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

centerinteger · required
correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
gm_sourcestringDefault: CENTER
reference_framestringDefault: J2000
targetinteger · required
Sub-solar pointsub_solar_point
⌄

sub_solar_point through the existing subpoint backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
methodstringDefault: NEAR_POINT/ELLIPSOID
observerinteger · required
targetinteger · required
target_framestring
Sub-observer pointsub_observer_point
⌄

sub_observer_point through the existing subpoint backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
methodstringDefault: NEAR_POINT/ELLIPSOID
observerinteger · required
targetinteger · required
target_framestring
Longitude of the Sunplanetocentric_solar_longitude
⌄

planetocentric_solar_longitude through the existing longitude backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
targetinteger · required
Illumination anglesillumination_angles
⌄

illumination_angles through the existing illum backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

altitude_kmnumberDefault: 0
correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
illuminatorintegerDefault: 10
latitude_degnumber · required
longitude_degnumber · required
observerinteger · required
targetinteger · required
target_framestring
Surface interceptsurface_intercept_point
⌄

surface_intercept_point through the existing intercept_vec backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
direction_framestringDefault: J2000
epoch_etnumber · required
observerinteger · required
targetinteger · required
target_framestring
xnumber · required
ynumber · required
znumber · required
Tangent pointtangent_point
⌄

tangent_point through the existing tangent backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
correction_locusstringDefault: TANGENT_POINT
epoch_etnumber · required
observerinteger · required
targetinteger · required
target_framestring
xnumberDefault: 0
ynumberDefault: 0
znumberDefault: 0
Pointing directionpointing_direction
⌄

pointing_direction through the existing pointing_full backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

antibooleanDefault: false
axisstringDefault: X
azimuth_counterclockwisebooleanDefault: true
correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
direction_framestringDefault: J2000
direction_typestringDefault: POSITION
elevation_positive_zbooleanDefault: true
epoch_etnumber · required
magnitudestringDefault: UNIT
observerinteger · required
output_framestringDefault: J2000
representationstringDefault: RECTANGULAR
targetintegerDefault: 0
vector_typestringDefault: VECTOR
xnumberDefault: 0
ynumberDefault: 0
znumberDefault: 0
Frame transformationframe_transformation
⌄

frame_transformation through the existing frame_rep backend. Epochs and GF confinement are ET seconds, distances km, GF angular references degrees. See geocalc://manual for the exact contract and supported subset.

angular_unitsstringDefault: rad
angular_velocitystringDefault: NOT_INCLUDED
angular_velocity_axesstringDefault: XYZ
angular_velocity_unitsstringDefault: rad/s
axesstringDefault: ZYZ
correctionstringSPICE correction; ray-in-FOV searches accept NONE, S or XS. VECTOR pointing accepts NONE, LT, CN, XLT, XCN, S or XS. Other families use NONE/LT/LT+S/CN/CN+S/XLT/XLT+S/XCN/XCN+S as supported by that native routine.
epoch_etnumber · required
frame1string · required
frame2string · required
orientationstringDefault: MATRIX_ALL_ONE_ROW
time_locationstringDefault: FRAME1

Precision & scope

Calculations are based on the configured kernels, their load order, the selected correction and the runtime profile. Results do not certify untested inputs or remote server kernel identity. Unsupported operations and missing kernels return explicit errors. Refer to the repository’s numerical contract and validation ledger for the exact tested scope.

View NAIF’s original API information ↗