WebGeocalc Web API Documentation

This document describes the Web API interface to WebGeocalc. The API interface provides a way to perform information queries and invoke calculations in the same way the web browser client does. All requests and responses are processed through HTTP/HTTPS transactions. In addition, request URLs use a RESTful structure with JSON payloads and results.

Last updated 28-JUN-2024.

Contents

Javascript API Example

There is an HTML page available on the WebGeoCalc server which serves as an example of how to call the web API: API Example Page (will open in a new window or tab).

Client-Server API Communication Flow

The following diagram provides a flowchart for the client-server communication, linking each of the possible client-side requests to the different phases of a Calculation.

Client-Server Communcation Flow
Fig.1 - Client-Server Communication Flow.

Integrating WGC API with your Web Application

If you are developing a web-based application and planning on integrating WGC API with it, you will need to overcome the Same-Origin Policy enforced by all modern browsers to prevent web pages from making requests to a different domain than the one that served the original web page.

The definition of an origin is simple. Two websites are of the same origin if their scheme (http://, https://, etc.), host (e.g., google.com), and port (e.g., 80, 443, etc.) are the same. For example, these URIs are considered to have the same origin:

On the other hand, these URIs are all different origins:

As such, direct calls to WGC API from www.my-server.com will not be allowed by browsers, as they violate the Same-Origin Policy.

Same-Origin Policy violation
Fig.2 - Same-Origin Policy violation.

Since WGC API serves multiple users from multiple organizations and it is not manageable to implement a secure, selective and controlled Cross-Origin Resource Sharing (CORS) policy on our server, WGC API does not support it. But this does not mean that WGC API cannot be integrated with your own web application. The implementation of a HTTP/HTTPS reverse proxy within your organization is an effective solution for handling the Same-Origin Policy problem, helping to bypass this restriction.

The proxy will filter the incoming requests and forward them to the appropriate resource, which could be on the same machine the proxy is running on, a different machine within your organization's internal network, or an external resource, such as WGC API.

Lets say that you are deploying an application on the URL

   www.my-server.com

running HTTPS (port 443), and this application integrates WGC API. Instead of performing requests directly to the WGC API server at

   https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/

which would be blocked due to the Same-Origin Policy, your application must direct the WGC API requests to an endpoint on the same URL, e.g.

   https://www.my-server.com/wgc/

The proxy, which shall be running on

   www.my-server.com

port 443, must be configured to forward the requests for /wgc/ to the WGC API server and all other requests to the web server serving your application. The later could be on the same machine where the proxy is deployed or, as in our example, on a different machine, e.g.

   https://192.168.2.100:8080

HTTP/HTTPS Reverse Proxy connecting to WGC API.
Fig.3 - HTTP/HTTPS Reverse Proxy connecting to WGC API.

HTTP/HTTPS Reverse Proxy using Nginx

A simple HTTP/HTTPS reverse proxy can be set up using Nginx. Lets assume that we have Nginx installed on the machine where we want to deploy our server, and that the SSL/TLS certificates for our domain www.my-server.com are located in

   /local/cert/ssl

We will configure Nginx to run an HTTP and an HTTPS server. The HTTP server, listening on port 80, will redirect all requests to the HTTPS server. The HTTPS server, running on port 443, will redirect requests for /wgc/ to the WGC API server

   https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/

and all other requests to the local HTTPS server running on

   https://192.168.2.100:8080

The Nginx configuration file nginx.conf, which should be placed in the Nginx conf.d directory, is shown hereafter.


    #
    # HTTPS server.
    #
    # Requests to /wgc/ are redirected to WGC API server, all others
    # to the HTTPS server running on 192.168.2.100, port 8080
    #
    server {
        listen 443 ssl;
        listen [::]:443 ssl;

        server_name www.my-server.com;

        # Define SSL certificates' location
        ssl_certificate /local/cert/ssl/my-server.crt;
        ssl_certificate_key /local/cert/ssl/my-server-key.pem;

        # If URL match with /wgc/ redirect the request
        location /wgc/ {
            proxy_pass https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/;

            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }

        # In any other case send the request to the local server
        location / {
            proxy_pass https://192.168.2.100:8080/;

            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }

    #
    # HTTP server.
    #
    # http requests are redirected to https, within the same machine.
    #
    server {

        listen 80;
        listen [::]:80;

        server_name www.my-server.com;
        return 302 https://$server_name$request_uri;
    }

HTTP/HTTPS Reverse Proxy using Docker

If we have Docker on the machine where we want to deploy the HTTP/HTTPS proxy, the SSL/TLS certificates for our domain www.my‑server.com are located in

   /home/user/proxy/cert/ssl/

and the Nginx configuration file shown in the previous section in

   /home/user/proxy/config/

we could use the following Dockerfile to create an image for deploying our reverse proxy, which will be listening on ports 80 and 443 for http and https requests.


   # Filename: Dockerfile
   #
   # Use an official Docker Nginx image, running on alpine OS.
   #
   FROM nginx:stable-alpine

   #
   # The official Nginx image has the Nginx default access and error logs
   # linked to /dev/stdout and /dev/stderr. The following command, makes
   # them files, which can be access through a shared folder. If you want
   # the logs to be reported on the terminal, comment out the following
   # lines.
   #
   RUN unlink /var/log/nginx/access.log \
    && unlink /var/log/nginx/error.log  \
    && touch  /var/log/nginx/access.log \
    && touch  /var/log/nginx/error.log

   #
   # Copy the required files in the appropriate locations within the image.
   #
   COPY config/nginx.conf /etc/nginx/conf.d/default.conf
   COPY --chmod=600 ssl/*.* /etc/nginx/ssl/

The previous file shall be named Dokerfile and be placed in

   /home/user/proxy/

In order to deploy the container with the proxy, first we need to build the image. From the directory where we have the Dockerfile file, run

   docker build -t https-proxy:1.0 -f Dockerfile .

This command creates an image called https-proxy. Once we have build the image, we can deploy the Docker container by running

   docker run -d -p 80:80 -p 443:443                     \
              -v /home/user/proxy/logs:/var/log/nginx    \
              --name NginxProxy https-proxy:1.0

By doing this, we have our HTTP/HTTPS proxy listening on ports 80 and 443 ready for operations. The container runs on the background, the access and error logs are placed in

   /home/user/proxy/logs

and no information is reported on the terminal. If we want the Nginx logs to be printed on the terminal, we need to comment out the RUN statement in the Dockerfile, rebuild the image, and run the previous command without the -d and -v options:

   docker run -p 80:80 -p 443:443 --name NginxProxy https-proxy:1.0

Request Reference

All URLs listed here are relative to the context root for the WebGeocalc application. The context root will vary based on the server configuration. As of this writing, the context root for the API-enabled WebGeocalc installation at NAIF is https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/.

For example, the relative URL for the request to list kernel sets is api/kernel-sets. To invoke this request at the main NAIF site, the complete URL would be https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/kernel-sets.

WGC API Information Requests

This section describes those API requests for getting information about the version of the WebGeocalc API currently deployed on the server.

URL: None

Get a short description, a link to the main documentation page (this page), the version number and the build identifier of the WebGeocalc Programmatic Interface (API).

URL parametersNone
Request payloadNone
Response formatJSON with the WGC API information.
Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/
Example response
{
   "title": "WebGeocalc by NAIF",
   "description": "WGC2 -- a WebGeocalc Server with enabled API at NAIF, JPL",
   "documentation": "https://wgc2.jpl.nasa.gov:8443/webgeocalc/documents/api-info.html",
   "contact": "Boris Semenov <boris.semenov@jpl.nasa.gov>",
   "version": "2.2.0",
   "build_id": "4599 N66 19-DEC-2019"
}

Kernel Set Information Requests

This section describes those API requests for getting information about the available kernel sets on the WebGeocalc server.

URL: kernel-sets

Get list of kernel sets available on the server.

URL parametersNone
Request payloadNone
Response formatJSON with list of kernel set objects
Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/kernel-sets
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "resultType": "KernelSetDetails",
  "items":[
    {
      "caption": "Solar System Kernels",
      "sclkId": "0",
      "description": "Generic kernels for planets, satellites, and some asteroids covering from 1950-01-01 to 2050-01-01.",
      "kernelSetId": "1",
      "missionId": "gen"
    },
    ...
  ]
}

URL: kernel-set/kernelSetId/bodies

Get list of bodies available in a kernel set.

URL parameterskernelSetId, an integer
Request payloadNone
Response formatJSON with list of body objects
Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/kernel-set/5/bodies
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "resultType": "BodyData",
  "items": [
    {
      "id": -82,
      "name": "CASSINI"
    },
    ...
  ]
}

URL: kernel-set/kernelSetId/frames

Get list of frames available in a kernel set.

URL parameterskernelSetId, an integer
Request payloadNone
Response formatJSON with list of frame objects
Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/kernel-set/5/frames
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "resultType": "FrameData",
  "items": [
    {
      "id": -82905,
      "name": "CASSINI_KSO",
      "centerBodyID": 699,
      "frameClass": 5
    },
    ...
  ]
}

URL: kernel-set/kernelSetId/instruments

Get list of instruments available in a kernel set.

URL parameterskernelSetId, an integer
Request payloadNone
Response formatJSON with list of instrument objects
Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/kernel-set/5/instruments
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "resultType": "InstrumentData",
  "items": [
    {
      "id": -82898,
      "name": "CASSINI_CIRS_RAD"
    },
    ...
  ]
}

Calculation Requests

This section details the API requests used to invoke calculations and get their status or results.

URL: calculation/new

Starts a new calculation.

URL parametersNone
Request payloadJSON with calculation parameters
Response format JSON with calculation creation status, or with an error, if detected before the response is created.

Standard Request Payload Parameters

The payload JSON object that is sent as POST data needs the following standard parameters.

NameValue
calculationType The type of calculation to perform. One of the following:
kernels The kernels parameter must be an array of kernels or kernel sets. To specify a kernel set use an object like this:
     {
       "type": "KERNEL_SET",
       "id": "the kernel set ID, an integer"
     }
     

To specify an individual kernel, use an object like this:

     {
       "type": "KERNEL",
       "path": "the server path to the kernel"
     }
     
timeSystem One of the following:
  • UTC
  • TDB
  • TDT
  • TT
  • SPACECRAFT_CLOCK
  • GPS

If SPACECRAFT_CLOCK is selected, then sclkId must also be provided.

Note that in SPICE, TDT (Terrestrial Dynamical Time) and TT (Terrestrial Time) refer to the same time system.

timeFormat One of the following:
  • CALENDAR
  • JULIAN
  • SECONDS_PAST_GPS0
  • SECONDS_PAST_J2000
  • SPACECRAFT_CLOCK_TICKS
  • SPACECRAFT_CLOCK_STRING
  • WEEK_TOW

CALENDAR is applicable only when timeSystem is UTC, TDB, TDT, TT or GPS.

JULIAN and SECONDS_PAST_J2000 are applicable only when timeSystem is UTC, TDB, TDT or TT.

SPACECRAFT_CLOCK_STRING and SPACECRAFT_CLOCK_TICKS are applicable only when timeSystem is SPACECRAFT_CLOCK.

SECONDS_PAST_GPS0 and WEEK_TOW are applicable only when timeSystem is GPS.

sclkIdThe SCLK ID. Only used if timeSystem is SPACECRAFT_CLOCK.
times An array of strings representing the time points that should be used in the calculation. E.g.
     "times": [
       "2000-01-01",
       "2000-01-02"
     ],
      
Either this parameter or the intervals parameter must be supplied.
intervalsAn array of objects with startTime and endTime parameters, representing the time intervals used for the calculation. E.g.
     "intervals": [
       {
         "startTime": "2000-01-01",
         "endTime": "2000-01-02"
       }
     ],
   
Either this parameter or the times parameter must be supplied. If this parameter is used, timeStep must also be supplied.
timeStepThe time step/number of steps parameter used for time series or geometry finder calculations. This parameter is not used for time series calculations if the times parameter is supplied.
timeStepUnitsOne of the following:
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • EQUAL_INTERVALS, except for Geometry Finder Calculations where the use of EQUAL_INTERVALS as a time step unit is not allowed.
Only used if timeStep is supplied.

Additional Parameters for Geometry Finder Calculations

All of the calculation types starting with GF_ require these additional parameters:

NameDescription
outputDurationUnitsThe units for the duration column of each interval in the result window. One of:
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
shouldComplementWindowA flag indicating whether to complement the result window against the original search window before returning the result. One of:
  • true
  • false.
intervalAdjustmentAn indication whether to adjust the intervals by expansion or contraction. If specified, both intervalAdjustmentAmount and intervalAdjustmentAmountUnits must be specified. One of:
  • NO_ADJUSTMENT
  • EXPAND_INTERVALS
  • CONTRACT_INTERVALS
intervalAdjustmentAmountThe amount to adjust each interval endpoint.
intervalAdjustmentUnitsThe time units for the interval adjustment amount. One of:
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
intervalFilteringWhether to filter out intervals smaller than a threshold. If specified, both intervalFilteringThreshold and intervalFilteringThresholdUnits must be specified. One of:
  • NO_FILTERING
  • FILTER_INTERVALS
intervalFilteringThresholdThe duration threshold value. All intervals shorter than this value will be removed from the result window.
intervalFilteringThresholdUnitsThe time unit for the interval filtering threshold. One of:
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS

Additional Parameters for Specifying GF Conditions

In addition, all scalar GF calculations (GF_COORDINATE_SEARCH, GF_ANGULAR_SEPARATION_SEARCH, GF_DISTANCE_SEARCH, GF_ILLUMINATION_ANGLES_SEARCH, GF_PHASE_ANGLE_SEARCH, GF_RANGE_RATE_SEARCH, GF_SUB_POINT_SEARCH, and GF_SURFACE_INTERCEPT_POINT_SEARCH) require the user to specify a condition to test during the search. This condition is a Javascript object with several parameters.

NameDescription
coordinateSystemThe name of the coordinate system in which to evaluate the coordinate. Only required for GF_COORDINATE_SEARCH, GF_SUB_POINT_SEARCH, and GF_SURFACE_INTERCEPT_POINT_SEARCH. One of:
  • RECTANGULAR
  • RA/DEC
  • LATITUDINAL (planetocentric)
  • CYLINDRICAL
  • SPHERICAL
  • GEODETIC
  • PLANETOGRAPHIC
  • AZ/EL (only in GF_COORDINATE_SEARCH)
coordinateThe name of the SPICE coordinate to search on.

Only required for GF_COORDINATE_SEARCH, GF_SUB_POINT_SEARCH, and GF_SURFACE_INTERCEPT_POINT_SEARCH. One of:

  • X
  • Y
  • Z
  • LONGITUDE
  • LATITUDE
  • COLATITUDE
  • RIGHT ASCENSION
  • DECLINATION
  • RANGE
  • RADIUS
  • ALTITUDE
  • AZIMUTH
  • ELEVATION

This coordinate must be appropriate for the coordinateSystem. See the SPICE API call gfpos() for more information.

azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when coordinate is AZIMUTH.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when coordinate is ELEVATION.
angleTypeThe name of the SPICE angle to search on. Only required for GF_ILLUMINATION_ANGLES_SEARCH. One of:

  • EMISSION
  • INCIDENCE
  • PHASE
relationalConditionThe relationship for the test. One of:
  • =
  • <
  • >
  • RANGE
  • ABSMAX
  • ABSMIN
  • LOCMAX
  • LOCMIN
If RANGE is used, then upperLimit is also required. For all but RANGE, see the documentation for the SPICE API call gfpos().

Note that for RANGE searches, the referenceValue and upperLimit values do not need to be in increasing order. If these values are in decreasing order, in the case of coordinate being LONGITUDE, RIGHT ASCENSION or AZIMUTH, the search will be performed across the boundary. For all other coordinates, the referenceValue and upperLimit values will be "swapped." Note that longitude, right ascension and azimuth coordinate values provided in referenceValue and upperLimit must be within the expected ranges for these coordinates for the search to work correctly.

referenceValueThe value to compare against, or the lower value of a range. Only needed if relationalCondition is not ABSMAX, ABSMIN, LOCMAX, or LOCMIN.
upperLimitThe upper limit of a range. Only needed if relationalCondition is RANGE.
adjustmentValueThe adjustment value to apply for ABSMIN and ABSMAX searches. Required if relationalCondition is ABSMIN or ABSMAX.

The units associated with the adjustmentValue are either degrees, km or km/s, depending on the selected search constraint, coordinate or angleType.

See the documentation for gfpos() for more details.

For example, here is a sample condition for GF_COORDINATE_SEARCH, which should serve as prototype for all cases where coordinateSystem is required:

"condition": {
  "coordinateSystem": "RA/DEC",
  "coordinate": "DECLINATION",
  "relationalCondition": "<",
  "referenceValue": -5
}

Here is a sample condition for GF_ILLUMINATION_ANGLES_SEARCH:

"condition": {
  "angleType": "EMISSION",
  "relationalCondition": "ABSMAX",
  "adjustmentValue": 0.0001
}

For other searches, the coordinateSystem and coordinate are implied. For example, here is a condition for GF_DISTANCE_SEARCH:

"condition": {
  "relationalCondition": "ABSMIN",
  "adjustmentValue": 1000
}

Additional Parameters for Specifying Directions

Direction vectors for ANGULAR_SEPARATION and POINTING_DIRECTION are specified as JSON dictionaries, using the following parameters:

NameDescription
directionType Method used to specify a direction. Directions could be specified as the position of an object as seen from the observer, as the velocity vector of an object as seen from the observer in a given reference frame, or by providing a vector in a given reference frame. One of:

Velocity depends on the reference frame in which it is expressed.

Given a time-dependent frame transformation R(t) between "input" and "output" reference frames, and position and velocity vectors expressed in the input frame, the velocity transformation between the frames can be expressed as
   Vel_out(t) = d(R(t))/dt * Pos_in(t) + R(t) * Vel_in(t)
In some cases, velocity is used simply as a direction vector; the rate of change of position in the output frame is not relevant. In these cases, the above transformation reduces to
   Vel_out(t) = R(t) * Vel_in(t)

This is the transformation used when velocity is treated as a direction vector.

Examples:

  1. Suppose a spacecraft's reference frame's Z-axis is nominally aligned with the spacecraft's inertially referenced velocity vector; the offset angle between the Z-axis and the velocity is to be measured.

    The spacecraft's inertially referenced velocity should simply be rotated into the spacecraft reference frame in order to make this measurement. The rotation rate of the spacecraft frame does not affect the offset angle at a particular time.

  2. Suppose a planet-orbiting spacecraft's reference frame's Z-axis is nominally aligned with the nadir direction, and the frame's Y-axis is aligned as closely as possible with the sub-spacecraft point's velocity, measured in the planet's body-fixed reference frame. The offset between the spacecraft frame's Y-axis and the projection of the sub-spacecraft point's velocity onto the spacecraft's X-Y plane is to be measured.

    The sub-spacecraft point's body-fixed velocity should simply be rotated into the spacecraft reference frame in order to make this measurement. The rotation rate of the spacecraft frame relative to the planet body-fixed frame does not affect the offset angle at a particular time. In fact, if this rate is taken into account, the transformed velocity is closely aligned with the +/- nadir direction.

  3. Suppose the velocity of particles entering an aperture of a spacecraft-mounted instrument, or contacting a detector of that instrument, is to be measured. In this case, the contribution of the term

       d(R(t))/dt * Pos_in(t)
    

    to the transformed velocity is typically very small, since the position is that of the particle relative to the origin of the instrument reference frame.

Depending on the desired directionType, different parameters are required. The following sections provide the list of additional parameters per directionType value.

Additional Parameters for Direction Vector of type POSITION

NameDescription
targetThe target body name or ID
shapeThe shape to use for the target body, only required for ANGULAR_SEPARATION computations. One of:
  • POINT
  • SPHERE
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SPKPOS.
antiVectorFlag true if the anti-vector shall be used for the direction, and false otherwise. Required when the target shape is POINT. If provided when the target shape is SPHERE, it must be set to false, i.e. using anti-vector direction is not supported for target bodies modeled as spheres.

For example, here is a sample POSITION type direction1 specification for ANGULAR_SEPARATION computation:

"direction1": {
  "directionType": "POSITION",
  "target": "MARS",
  "shape": "POINT",
  "observer": "EARTH",
  "aberrationCorrection": "LT+S",
  "antiVectorFlag": false
}
Here is a sample POSITION type direction specification for POINTING_DIRECTION computation:

"direction": {
  "directionType": "POSITION",
  "target": "MARS",
  "observer": "EARTH",
  "aberrationCorrection": "LT+S",
  "antiVectorFlag": false
}

Additional Parameters for Direction Vector of type VELOCITY

NameDescription
targetThe target body name or ID
referenceFrameThe reference frame name
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SPKEZR.
antiVectorFlag true if the anti-vector shall be used for the direction, and false otherwise.

For example, here is a sample VELOCITY type direction1 specification for ANGULAR_SEPARATION computation:

"direction1": {
  "directionType": "VELOCITY",
  "target": "MARS",
  "referenceFrame": "ITRF93",
  "observer": "EARTH",
  "aberrationCorrection": "XCN+S",
  "antiVectorFlag": true
}
Here is a sample VELOCITY type direction specification for POINTING_DIRECTION computation:

"direction": {
  "directionType": "VELOCITY",
  "target": "MARS",
  "referenceFrame": "ITRF93",
  "observer": "EARTH",
  "aberrationCorrection": "XCN+S",
  "antiVectorFlag": true
}

Additional Parameters for Direction Vector of type VECTOR

NameDescription
directionVectorType Type of vector to be used as the ray direction: the instrument boresight vector, an axis of the specified reference frame, a vector in the reference frame of the specified instrument, a vector in the specified reference frame, or the instrument field-of-view boundary vectors (only for POINTING_DIRECTION computations). One of:
  • INSTRUMENT_BORESIGHT
  • REFERENCE_FRAME_AXIS
  • VECTOR_IN_INSTRUMENT_FOV
  • VECTOR_IN_REFERENCE_FRAME
  • INSTRUMENT_FOV_BOUNDARY_VECTORS
directionInstrument The instrument name or ID. Required only if directionVectorType is INSTRUMENT_BORESIGHT, VECTOR_IN_INSTRUMENT_FOV or INSTRUMENT_FOV_BOUNDARY_VECTORS.
directionFrame The vector's reference frame name. Required only if directionVectorType is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.
directionFrameAxis The direction vector frame axis. Required only if directionVectorType is REFERENCE_FRAME_AXIS. One of:
  • X
  • Y
  • Z
directionVectorX The X direction vector coordinate. If directionVectorType is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of directionVectorX, directionVectorY, and directionVectorZ must be provided, or both directionVectorRA and directionVectorDec, or both directionVectorAz and directionVectorEl.
directionVectorY The Y direction vector coordinate.
directionVectorZ The Z direction vector coordinate.
directionVectorRA The right ascension direction vector coordinate.
directionVectorDec The declination direction vector coordinate.
directionVectorAz The azimuth direction vector coordinate.
directionVectorEl The elevation direction vector coordinate.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
aberrationCorrection The SPICE aberration correction string. Light time correction is applied to the rotation from the vector frame to J2000, while stellar aberration corrections apply to the vector direction. One of:
  • NONE
  • LT
  • CN
  • XLT
  • XCN
  • S
  • XS
For details of light time corrections used to compute the times at the frame center, see the description of the input argument ABCORR of the SPICELIB routine SPKPOS. For details of stellar aberration corrections used adjust the vector direction, see the description of the input argument ABCORR of the SPICELIB routine GFRFOV.
observer The observing body name or ID. Required if aberrationCorrection is not NONE.
antiVectorFlag true if the anti-vector shall be used for the direction, and false otherwise.

For example, here is a sample VECTOR type direction1 specification for ANGULAR_SEPARATION computation:

"direction1": {
  "directionType": "VECTOR",
  "observer": "EARTH",
  "directionVectorType": "REFERENCE_FRAME_AXIS",
  "directionFrame": "IAU_EARTH",
  "directionFrameAxis": "X",
  "aberrationCorrection": "S",
  "antiVectorFlag": true
}
Here is a sample VECTOR type direction specification for POINTING_DIRECTION computation:

"direction": {
  "directionType": "VECTOR",
  "observer": "CASSINI",
  "directionVectorType": "INSTRUMENT_FOV_BOUNDARY_VECTORS",
  "directionInstrument": "CASSINI_ISS_NAC",
  "aberrationCorrection": "CN",
  "antiVectorFlag": false
}

Additional Parameters for Specifying Surface Points

The calculations ILLUMINATION_ANGLES and GF_ILLUMINATION_ANGLES_SEARCH require the following parameters in order to specify the target body surface point on which the computations will be conducted:

NameDescription
targetThe target body name or ID
shape1The shape to use to model the surface of the target body. One of:
targetFrameThe body-fixed reference frame name, centered at target.
offSurfaceFlag Flag indicating whether the location is given as an off-surface point (true) or not (false). Surface points on a target body's reference ellipsoid normally should be specified by two angular coordinates, for example planetocentric longitude and latitude. These coordinates identify a unique point on the ellipsoid, which then can be converted to Cartesian coordinates by WGC.

If this flag is set to true, you can specify a point off the reference ellipsoid. The direction of the outward normal vector calculated by WGC at this point won't be exactly parallel to the outward normal direction at the nearest point on the reference ellipsoid to the specified input point. The angular offset between the directions typically is small for points not far from the reference ellipsoid. Some examples are:

  • Earth: at altitude 10 km, maximum offset is 0.000005 degrees
  • Earth: at altitude -1 km, maximum offset is 0.000001 degrees
  • Mars: at altitude 25 km, maximum offset is 0.000043 degrees
  • Mars: at altitude -15 km, maximum offset is 0.000026 degrees
  • Saturn: at altitude 1e4 km, maximum offset is 0.015408 degrees
  • Saturn: at altitude -1e4 km, maximum offset is 0.021973 degrees
offSurfaceFlag is optional and, if not provided, it defaults to false. If shape1 is DSK, offSurfaceFlag must be set to false.
coordinateRepresentationOne of:
  • LATITUDINAL (planetocentric)
  • SPHERICAL
  • PLANETODETIC, only when shape1 is ELLIPSOID.
  • PLANETOGRAPHIC, only when shape1 is ELLIPSOID.
  • CYLINDRICAL, only when shape1 is ELLIPSOID and offSurfaceFlag is set to true.
  • RECTANGULAR, only when shape1 is ELLIPSOID and offSurfaceFlag is set to true.
latitudeThe latitude coordinate of the surface point, in degrees. Required only when coordinateRepresentation is LATITUDINAL, PLANETODETIC or PLANETOGRAPHIC.
longitudeThe longitude coordinate of the surface point, in degrees. Required only when coordinateRepresentation is LATITUDINAL, PLANETODETIC, PLANETOGRAPHIC, SPHERICAL or CYLINDRICAL.
colatitudeThe colatitude coordinate of the surface point, in degrees. Required only when coordinateRepresentation is SPHERICAL.
radiusThe radius coordinate at the surface point location, in km. Required only when coordinateRepresentation is LATITUDINAL, CYLINDRICAL or SPHERICAL and offSurfaceFlag is set to true.
altitudeThe altitude coordinate of the surface point, in km. Required only when coordinateRepresentation is PLANETODETIC, or PLANETOGRAPHIC and offSurfaceFlag is set to true.
xThe X coordinate of the surface point, in km. Required only when coordinateRepresentation is RECTANGULAR.
yThe Y coordinate of the surface point, in km. Required only when coordinateRepresentation is RECTANGULAR.
zThe Z coordinate of the surface point, in km. Required only when coordinateRepresentation is RECTANGULAR or CYLINDRICAL.

Note that in the case of Surface Point specification, the parameters are NOT grouped in a Javascript object.

For example, here is a sample of the specification of an on-surface point on a target modeled using a DSK:

  "target": "ENCELADUS",
  "shape1": "DSK",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "coordinateRepresentation": "LATITUDINAL",
  "latitude": 0,
  "longitude": 0,

And a sample of the specification of an off-surface point on a target modeled as an ellipsoid:

  "target": "SATURN",
  "shape1": "ELLIPSOID",
  "offSurfaceFlag": true,
  "targetFrame": "IAU_SATURN",
  "coordinateRepresentation": "PLANETODETIC",
  "latitude": 90.0,
  "longitude": 0,
  "altitude": 10.25,

Additional Calculation-Specific Parameters

See the details for each calculation type and the parameter reference for information about other parameters:

Example Calculation Request

Example Request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/calculation/new
Example Post Data
{
  "calculationType": "STATE_VECTOR",
  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 1
    }
  ],
  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2000-01-01",
      "endTime": "2000-01-02"
    }
  ],
  "timeStep": 30,
  "timeStepUnits": "MINUTES",
  "targetType": "OBJECT",
  "target": "SUN",
  "observerType": "OBJECT",
  "observer": "EARTH",
  "referenceFrame": "J2000",
  "aberrationCorrection": "NONE",
  "stateRepresentation": "RA_DEC"
}
Example Response
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "0788aba2-d4e5-4028-9ef1-4867ad5385e0",
  "result": {
    "phase": "COMPLETE",
    "expiresIn": 54
  }
}

URL: calculation/id

Gets the status of a calculation.

URL parameterscalculationId, a string
Request payloadNone
Response format JSON with calculation status, or with an error, if the provided calculation identifier calculationId does not correspond to any previously requested calculation, or if the calculation has been removed from the server.

Example Calculation Status Request

Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/calculation/0788aba2-d4e5-4028-9ef1-4867ad5385e0
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "0788aba2-d4e5-4028-9ef1-4867ad5385e0",
  "result": {
    "phase": "COMPLETE",
    "expiresIn": 54
  }
}

URL: calculation/id/results

Gets the results of a calculation, should it be successfully COMPLETE. If the calculation status phase is FAILED, it returns an error response providing relevant information about the error. Upon serving this request, the results (or error details) are removed from the server, and calculation status phase is set to DISPATCHED.

Requesting results during any other calculation phase will produce an error.

URL parameterscalculationId, a string
Request payloadNone
Response format JSON with calculation results, or with an error, should the calculation FAILED after the response to the request for a new calculation was served, or if the provided calculation identifier calculationId does not correspond to any previously requested calculation, or if the calculation has been removed from the server.

Example Calculation Results Request

Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/calculation/0788aba2-d4e5-4028-9ef1-4867ad5385e0/results
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "0788aba2-d4e5-4028-9ef1-4867ad5385e0",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Right Ascension (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "RIGHT_ASCENSION"
    },
    ...
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    }
  ],
  "rows": [
    [
      "2000-01-01 00:00:00.000000 UTC",
      280.73666816,
      -23.07197828,
      147104359.15044397,
      0.0000127884715,
      8.74255781e-7,
      -0.01659221,
      30.29084386,
      "2000-01-01 00:00:00.000000 UTC",
      490.6873246
    ],
    ...
    [
      "2000-01-02 00:00:00.000000 UTC",
      281.84100169,
      -22.99260787,
      147103258.34983575,
      0.0000127745341,
      9.62949471e-7,
      -0.00894244,
      30.29324424,
      "2000-01-02 00:00:00.000000 UTC",
      490.68365272
    ]
  ]
}

URL: calculation/id/cancel

Cancels a previously requested calculation, should this not be completed, or its results.

Calculations that have been already DISPATCHED, previously CANCELLED or that have EXPIRED cannot be cancelled, and requesting it will produce an error.

URL parameterscalculationId, a string
Request payloadNone
Response format JSON with calculation status, or with an error, if the provided calculation identifier calculationId does not correspond to any previously requested calculation, or if this calculation has been removed from the server.

Example Calculation Cancellation Request

Example request URL https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/calculation/0788aba2-d4e5-4028-9ef1-4867ad5385e0/cancel
Example response
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "0788aba2-d4e5-4028-9ef1-4867ad5385e0",
  "result": {
    "phase": "CANCELLED"
  }
}
    

Response Reference

This section describes the available response types and their parameters.

The Calculation Status Response are returned for successful calculation/new, calculation/id, and calculation/id/cancel requests.

The Calculation Results Response are returned as response to calculation/id/results requests only for successfully completed, non-expired calculations.

The Error Response can be returned for any requests.

Common Parameters

All responses have at least three parameters:

NameDescription
status The status of the request. Either OK or ERROR
message A short message describing the status of the request.
calculationId A string representing the calculation task identifier generated by the calculation service.

Calculation Status Response

The calculation status response is received upon successful processing of a new request for calculation, a request for the status of an existing calculation task, or its successful cancellation. Besides the Common Parameters, the response includes the result JSON object, which contains the following parameters:

NameDescription
phase The status (phase) of the calculation. One of:
  • QUEUED, when the calculation request is queued to be served once the calculation service becomes available.
  • STARTING, when the calculation request has entered the calculation service, but it has not yet started loading the required kernels.
  • LOADING_KERNELS, when the calculation request is being served, and the required kernels are being loaded.
  • CALCULATING, when the required kernels have been loaded, and the calculation server is producing the requested results.
  • COMPLETE, when the calculation server has successfully completed the request, and the results have not yet been retrieved.
  • FAILED, when the calculation request has failed.
  • CANCELLED, when the calculation has been cancelled by the client.
  • DISPATCHED, when the calculation results have been requested by the client and dispatched.
  • EXPIRED, when the calculation results expired due to the client not fetching them before they expire.
position The current position of the calculation request within the calculation service queue. This parameter is only provided if the phase is QUEUED.
expiresIn Number of seconds, from the time the status information has been generated, until the results produced by the calculation request are purged from the calculation service, i.e. the results associated to the given calculationId will be removed from the server, and therefore no longer available, after expiresIn seconds. This parameter is only provided if the phase is COMPLETE.

Available Calculation Status Responses

QUEUED phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "02c0b4c5-8a8a-4fdb-8a07-b446c6e6722a",
  "result": {
    "phase": "QUEUED",
    "position": 6
  }
}
STARTING phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "STARTING"
  }
}
LOADING_KERNELS phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "LOADING_KERNELS"
  }
}
CALCULATING phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "CALCULATING"
  }
}
COMPLETE phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "26d33ccc-a49c-41e5-a733-9c24b04b9fb9",
  "result": {
    "phase": "COMPLETE",
    "expiresIn": 54
  }
}
FAILED phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "FAILED"
  }
}
CANCELLED phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "CANCELLED"
  }
}
DISPATCHED phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "DISPATCHED"
  }
}
EXPIRED phase
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9192ebe1-37ef-41dc-81d2-03bb0e5ae956",
  "result": {
    "phase": "EXPIRED"
  }
}

Calculation Results Response

The calculation results response is received upon successful processing of a request for the results (calculation/id/results request) of a COMPLETE calculation task.

Note that the results for a given calculation, with task identifier calculationId, will be available on the server for a limited time. The remaining seconds until the results are discarded can be obtained by requesting the status of the calculation once it is completed. The server provides this information in the expiresIn parameter of the Calculation Status Response.

Upon retrieval of the calculation results, they are removed from the server, and are no longer available. The phase of the calculation is then set to DISPATCHED.

Besides the Common Parameters, the response includes the columns and rows JSON objects, representing a table.

The columns JSON object contains an array of JSON objects, each of them containing the following parameters:

NameDescription
name A string providing the name of the table's column, giving a short description of the values provided within that column, e.g. "UTC calendar date".
type Column's data type. One of:
  • DATE
  • NUMBER
  • STRING
units Units in which the column's value is given, or an empty string if if the concept of units does not apply to the values in that column.
outputID Unique column identifier. This identifier is unique across all results generated by WGC.

The rows JSON object contains an array of arrays of values, each of them containing as many values as columns have been described within the columns object.

If the provided results correspond to a 7x3 table, the rows object will have 7 arrays of 3 strings each, and the columns object will have 3 objects describing each of the three columns.

Example Results Responses

Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "8fb3afe9-3d77-4c30-9c00-80be816ce942",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "UTC Julian date",
      "type": "NUMBER",
      "units": "",
      "outputID": "DATE2"
    }
  ],
  "rows": [
    [
      "2000-01-01 00:00:00.000000 UTC",
      "2451544.500000000 JD UTC"
    ],
    [
      "2000-01-02 00:00:00.000000 UTC",
      "2451545.500000000 JD UTC"
    ],
    [
      "2000-02-01 00:00:00.000000 UTC",
      "2451575.500000000 JD UTC"
    ],
    [
      "2000-02-02 00:00:00.000000 UTC",
      "2451576.500000000 JD UTC"
    ]
  ]
}

Error Response

The error response is received upon detection of an error, on the server side, either during the processing of the request, in the calculation task or in the generation of the results. Should a Calculation task Identifier exist at the time the error is detected, the Calculation Phase is set to FAILED, otherwise the request is completely discarded and the response parameter calculationId is set to null before returning the error response.

In the event that the error is detected in a new calculation request before the request is processed, the server will return an error response instead of the expected Calculation Status Response. Should the error be detected afterwards, the client shall use the calculation/id/results request in order to retrieve the error description.

Upon retrieval of the error response, the error details are removed from the server, and are no longer available. The phase of the calculation is then set to DISPATCHED.

Besides the Common Parameters, the error response includes the error JSON object, which contains the following parameters:

NameDescription
shortDescription A string providing a short description of the reason for the error.

Note that in all error response objects, the status parameter is set to ERROR.

Example Error Responses

The following table provides examples of Error Responses. This table is neither exhaustive nor it covers all the available Error Response types.
Excessive load on the server, response to a calculation/new request.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": null,
  "error": {
    "shortDescription": "The server is currently experiencing excessive load."
  }
}
Missing required JSON parameter in a calculation/new Calculation Request.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": "e145c522-dbb0-49f2-8624-eddc423c3a25",
  "error": {
    "shortDescription": "No input value found with name 'sclkId'"
  }
}
SPICE related error, from either a calculation/new or a calculation/id/results request.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": "f9c9373b-c455-417c-9b62-f960a5bc5d93",
  "error": {
    "shortDescription": "CSPICE_N0066: CSPICE.scencd: SPICE(KERNELVARNOTFOUND): [scencd_c --> SCENCD --> SCTIKS --> SCTYPE --> SCLI01] SCLK_DATA_TYPE_825 not found. Did you load the SCLK kernel?"
  }
}
Attempt to retrieve Results, using a calculation/id/results request, before COMPLETE.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": "85a5d697-0163-4525-8056-30fcf0a25620",
  "error": {
    "shortDescription": "Application should not retrieve results before calculation is finished."
  }
}
Attempt to retrieve EXPIRED Results, using a calculation/id/results request.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": "8d44762c-2ae9-4d6f-bb00-ba39b41b009c",
  "error": {
    "shortDescription": "The requested results have already expired."
  }
}
Unknown calculationId error response to a calculation/id, calculation/id/results or calculation/id/cancel request.
{
  "status": "ERROR",
  "message": "The request has failed.",
  "calculationId": "f9c9373-c455-417c-9b62-f960a5bc5d93",
  "error": {
    "shortDescription": "The provided Calculation ID does not correspond to any requested calculation."
  }
}

Calculation Reference

This section describes the available calculation types, specified using the parameter calculationType, and the parameters expected by each calculation.

STATE_VECTOR

Calculates the position of one body relative to another, calculated in a desired reference frame.

Standard parameters:

Additional parameters required:

NameDescription
targetTypeThe type of specification used to define the location of the target. One of:
  • OBJECT
  • FIXED_POINT
  • CONSTANT_VELOCITY_POINT
Use OBJECT if the target is specified by providing the name of an ephemeris object, i.e. a target whose trajectory is provided by one of the loaded SPK files. Use FIXED_POINT to specify the target as a fixed (constant) geometric position relative to its "center of motion," expressed in the provided reference frame. Use CONSTANT_VELOCITY_POINT to specify the target having a constant Cartesian velocity relative to its "center of motion," expressed in the provided reference frame at a given epoch. For other epochs, the position of the target relative to its center of motion is linearly extrapolated from the position at the given epoch using the provided Cartesian velocity.

Note that if targetType is either FIXED_POINT or CONSTANT_VELOCITY_POINT then observerType MUST be OBJECT, i.e. specifying both Target and Observer as locations is not allowed.

Note that targetType is optional. If not provided, it is assumed to be OBJECT.

targetThe target body name or ID, only applicable when targetType is OBJECT.
targetLocationJavascript object providing the specification for the target location, only applicable when targetType is either FIXED_POINT or CONSTANT_VELOCITY_POINT. This dictionary shall comply to the specification provided in Additional Parameters for Locations as Points.
observerTypeThe type of specification used to define the location of the observer. One of:
  • OBJECT
  • FIXED_POINT
  • CONSTANT_VELOCITY_POINT
Use OBJECT if the observer is specified by providing the name of an ephemeris object, i.e. an observer whose trajectory is provided by one of the loaded SPK files. Use FIXED_POINT to specify the observer as a fixed (constant) geometric position relative to its "center of motion," expressed in the provided reference frame. Use CONSTANT_VELOCITY_POINT to specify the observer having a constant Cartesian velocity relative to its "center of motion," expressed in the provided reference frame at a given epoch. For other epochs, the position of the observer relative to its center of motion is linearly extrapolated from the position at the given epoch using the provided Cartesian velocity.

Note that if observerType is either FIXED_POINT or CONSTANT_VELOCITY_POINT then targetType MUST be OBJECT, i.e. specifying both Target and Observer as locations is not allowed.

Note that observerType is optional. If not provided, it is assumed to be OBJECT.

observerThe observing body name or ID, only applicable when observerType is OBJECT.
observerLocationJavascript object providing the specification for the observer location, only applicable when observerType is either FIXED_POINT or CONSTANT_VELOCITY_POINT. This dictionary shall comply to the specification provided in Additional Parameters for Locations as Points.
referenceFrameThe reference frame name
frameLocusThe output reference frame evaluation locus; i.e. the location associated with the epoch at which the evaluation of the output frame's orientation, relative to the J2000 frame, will be performed. One of:
  • CENTER
  • OBSERVER
  • TARGET

Use OBSERVER to evaluate the output reference frame at the observer's epoch. Normally the locus OBSERVER should be selected when the output reference frame is centered at the observer.

Use TARGET to evaluate the output reference frame at the target epoch. Normally the locus TARGET should be selected when output reference frame is centered at the target object.

Use CENTER to evaluate the output reference frame at the epoch associated with its center. The locus CENTER should be selected when the user intends to obtain results compatible with those produced by a state vector computation between two objects, i.e. between a targetType OBJECT and an observerType OBJECT.

When the output reference frame is inertial, all choices of frameLocus yield the same results.

frameLocus is only applicable when either targetType or observerType is FIXED_POINT or CONSTANT_VELOCITY_POINT.

aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SPKEZR.
stateRepresentationOne of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC, only applicable when observerType is OBJECT
  • PLANETOGRAPHIC, only applicable when observerType is OBJECT
  • CYLINDRICAL
  • SPHERICAL
  • AZ_EL
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when stateRepresentation is set to AZ_EL.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when stateRepresentation is set to AZ_EL.

Additional Parameters for specification of locations as points:

Target or observer locations, when defined as points (i.e. when targetType or observerType are either FIXED_POINT or CONSTANT_VELOCITY_POINT), are specified as JSON dictionaries, using the following parameters:

NameDescription
centerBodythe name of the location's center of motion. The ephemeris of centerBody is provided by loaded SPK files.
referenceFrame name of a reference frame, whether built in or defined in loaded kernels.

This reference frame is used to specify the location's coordinates relative to its "center of motion." If coordinateRepresentation (used to specify the locations's position) is set to PLANETODETIC or PLANETOGRAPHIC coordinates, this frame shall be non-inertial and its center MUST be the same as the center provided in centerBody.

coordinateRepresentation Coordinate system used to specify the location's position coordinates. One of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC
  • PLANETOGRAPHIC
  • CYLINDRICAL
  • SPHERICAL
  • AZ_EL
Before performing the calculation, the position specified using this coordinate system is converted to Cartesian coordinates. If the selected coordinate representation is either PLANETODETIC or PLANETOGRAPHIC, the locations's center of motion, given in centerBody and the center of the non-inertial reference frame used to specify the coordinates, given in referenceFrame within this dictionary, MUST be the same. In these cases, the center body shape shall be a spheroid and its equatorial and polar radii will be used in the coordinates system conversion.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when coordinateRepresentation is set to AZ_EL.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when coordinateRepresentation is set to AZ_EL.
xThe X coordinate, in km, applicable only when coordinateRepresentation is RECTANGULAR.
yThe Y coordinate, in km, applicable only when coordinateRepresentation is RECTANGULAR.
zThe Z coordinate, in km, applicable only when coordinateRepresentation is RECTANGULAR or CYLINDRICAL.
rightAscension The right ascension of the location, in degrees, applicable only when coordinateRepresentation is RA_DEC.
declination The declination of the location, in degrees, applicable only when coordinateRepresentation is RA_DEC.
range The range to the location, in km, applicable only when coordinateRepresentation is RA_DEC or AZ_EL.
longitude The longitude of the location, in degrees, applicable only when coordinateRepresentation is LATITUDINAL, PLANETODETIC, PLANETOGRAPHIC, CYLINDRICAL or SPHERICAL.
latitude The latitude of the location, in degrees, applicable only when coordinateRepresentation is LATITUDINAL, PLANETODETIC, or PLANETOGRAPHIC.
radius The radius at the location, in km, applicable only when coordinateRepresentation is LATITUDINAL, CYLINDRICAL or SPHERICAL.
altitude The altitude of the location, in km, applicable only when coordinateRepresentation is PLANETODETIC or PLANETOGRAPHIC.
colatitude The colatitude of the location, in degrees, applicable only when coordinateRepresentation is SPHERICAL.
azimuth The azimuth of the location, in degrees, applicable only when coordinateRepresentation is AZ_EL.
elevation The elevation of the location, in degrees, applicable only when coordinateRepresentation is AZ_EL.
dxdt The X Cartesian velocity coordinate, in km/s, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType).
dydt The Y Cartesian velocity coordinate, in km/s, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType).
dzdt The Z Cartesian velocity coordinate, in km/s, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType).
timeSystem The time system used to specify the location's epoch, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType). One of:
  • UTC
  • TDB
  • TDT
  • TT
  • SPACECRAFT_CLOCK
  • GPS

If SPACECRAFT_CLOCK is selected, then sclkId must also be provided.

Note that in SPICE, TDT (Terrestrial Dynamical Time) and TT (Terrestrial Time) refer to the same time system.

timeFormat The time format used to represent the location's epoch, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType). One of:
  • CALENDAR
  • JULIAN
  • SECONDS_PAST_GPS0
  • SECONDS_PAST_J2000
  • SPACECRAFT_CLOCK_STRING
  • SPACECRAFT_CLOCK_TICKS
  • WEEK_TOW
CALENDAR is applicable if either UTC, TDB, TDT, TT or GPS are selected as timeSystem. JULIAN and SECONDS_PAST_J2000 are applicable if either UTC, TDB, TDT or TT are selected as timeSystem. SPACECRAFT_CLOCK_STRING and SPACECRAFT_CLOCK_TICKS are only applicable when timeSystem is SPACECRAFT_CLOCK. SECONDS_PAST_GPS0 and WEEK_TOW are only applicable when timeSystem is GPS.
sclkId The spacecraft clock identifier, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType) and timeSystem is SPACECRAFT_CLOCK.
epoch The location's epoch, applicable only when CONSTANT_VELOCITY_POINT is used to specify the location (in targetType or observerType).

For other epochs than this, the position of the location relative to its center of motion is linearly extrapolated from the position at this epoch using the provided Cartesian velocity.

Example STATE_VECTOR Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "STATE_VECTOR",
  "targetType": "OBJECT",
  "target": "CASSINI",
  "observerType": "OBJECT",
  "observer": "SATURN",
  "referenceFrame": "IAU_SATURN",
  "aberrationCorrection": "NONE",
  "stateRepresentation": "PLANETOGRAPHIC"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "2312e51f-1593-4e72-834b-86e4fb3beca5",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Longitude (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "LONGITUDE"
    },
    {
      "name": "Latitude (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "LATITUDE"
    },
    {
      "name": "Altitude (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "ALTITUDE"
    },
    {
      "name": "d Longitude/dt (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "D_LONGITUDE_DT"
    },
    {
      "name": "d Latitude/dt (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "D_LATITUDE_DT"
    },
    {
      "name": "d Altitude/dt (km/s)",
      "type": "NUMBER",
      "units": "km/s",
      "outputID": "D_ALTITUDE_DT"
    },
    {
      "name": "Speed (km/s)",
      "type": "NUMBER",
      "units": "km/s",
      "outputID": "SPEED"
    },
    {
      "name": "Time at Target",
      "type": "DATE",
      "units": "",
      "outputID": "TIME_AT_TARGET"
    },
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      46.18900522,
      21.26337134,
      694259.8921163,
      0.00888655,
      -0.00031533,
      4.77080305,
      109.34997994,
      "2012-10-19 08:24:00.000000 UTC",
      2.51438831
    ]
  ]
}

ANGULAR_SEPARATION

Calculates the angular separation between two directions. These directions could be defined by two targets or by specifying each direction separately using a position vector, a velocity vector or a vector on a given reference frame.

This calculation requires these parameters:

Standard parameters:

Additional parameters required:

NameDescription
specType Method used to specify the directions between which the angular separation is computed. One of:
  • TWO_TARGETS
  • TWO_DIRECTIONS

Use TWO_TARGETS to specify the directions using two target bodies as seen from an observer. Use TWO_DIRECTIONS to define each direction by specifying the position or velocity of an object with respect to an observer, or by specifying a vector in a given reference frame.

Note that specType is optional if the method used to specify the directions is TWO_TARGETS

Additional parameters required (TWO_TARGETS):

NameDescription
target1The target body name or ID of the first body
shape1The shape to use for the first body. One of:
  • POINT
  • SPHERE
target2The target body name or ID of the second body
shape2The shape to use for the second body. One of:
  • POINT
  • SPHERE
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For details of aberration corrections applied to both target position vectors, see the description of the input argument ABCORR of the SPICELIB routine SPKPOS.

Additional parameters required (TWO_DIRECTIONS):

NameDescription
direction1 Javascript object providing the specification for the first direction vector. This dictionary shall comply to the specification provided in Additional Parameters for Specifying Directions.
direction2 Javascript object providing the specification for the second direction vector. This dictionary shall comply to the specification provided in Additional Parameters for Specifying Directions.

Example ANGULAR_SEPARATION Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL",
      "path": "pds/wgc/kernels/lsk/naif0012.tls"
    },
    {
      "type": "KERNEL",
      "path": "pds/wgc/kernels/spk/de430.bsp"
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "ANGULAR_SEPARATION",
  "target1": "VENUS",
  "shape1": "POINT",
  "target2": "MERCURY",
  "shape2": "POINT",
  "observer": "SUN",
  "aberrationCorrection": "NONE"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "963c48d7-c7d9-48ed-b97c-b3e2ff021e29",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Angular Separation (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ANGULAR_SEPARATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      175.17111606
    ]
  ]
}

ANGULAR_SIZE

Calculates the angular size of a target as seen by an observer.

Standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For details of aberration correction applied to the target position vector, see the description of the input argument ABCORR of the SPICELIB routine SPKPOS.

Example ANGULAR_SIZE Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "ANGULAR_SIZE",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "aberrationCorrection": "CN+S"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "5343f13a-b13b-4d35-9dc5-d20462e64f01",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Angular Size (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ANGULAR_SIZE"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      0.03037939
    ]
  ]
}

FRAME_TRANSFORMATION

Calculate the transformation from one reference frame (Frame 1) to another reference frame (Frame 2).

Standard parameters:

Additional parameters required:

NameDescription
frame1The first reference frame name
frame2The second reference frame name
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • XLT
  • CN
  • XCN
For details of aberration corrections used to compute times at the frame centers, see the description of the input argument ABCORR of the SPICELIB routine SPKPOS.
timeLocationThe frame for the input times. Only needed if aberrationCorrection is not NONE. One of:
  • frame1
  • frame2.
orientationRepresentationThe representation of the result transformation. One of:
  • EULER_ANGLES
  • ANGLE_AND_AXIS
  • SPICE_QUATERNION
  • OTHER_QUATERNION
  • MATRIX_ROW_BY_ROW
  • MATRIX_FLAGGED
  • MATRIX_ALL_ONE_ROW
axis1The first axis for Euler angle rotation. Only needed if orientationRepresentation is EULER_ANGLES. One of:
  • X
  • Y
  • Z
axis2The second axis for Euler angle rotation. Only needed if orientationRepresentation is EULER_ANGLES. One of:
  • X
  • Y
  • Z
axis3The third axis for Euler angle rotation. Only needed if orientationRepresentation is EULER_ANGLES. One of:
  • X
  • Y
  • Z
angularUnitsThe angular units used for the angle of rotation. Only needed if orientationRepresentation is EULER_ANGLES or ANGLE_AND_AXIS. One of:
  • deg
  • rad
angularVelocityRepresentationThe representation of angular velocity in the output. One of:
  • NOT_INCLUDED
  • VECTOR_IN_FRAME1
  • VECTOR_IN_FRAME2
  • EULER_ANGLE_DERIVATIVES
  • MATRIX
angularVelocityUnitsThe units for the angular velocity. Only needed if angularVelocityRepresention is one of VECTOR_IN_FRAME1, VECTOR_IN_FRAME2, or EULER_ANGLE_DERIVATIVES. One of:
  • deg/s
  • rad/s
  • RPM
  • unitless or Unitary (synonym, for backwards compatibility). Only applicable for VECTOR_IN_FRAME1 and VECTOR_IN_FRAME2.

Example FRAME_TRANSFORMATION Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "FRAME_TRANSFORMATION",
  "frame1": "IAU_SATURN",
  "frame2": "IAU_ENCELADUS",
  "aberrationCorrection": "NONE",
  "timeLocation": "FRAME1",
  "orientationRepresentation": "EULER_ANGLES",
  "axis1": "X",
  "axis2": "Y",
  "axis3": "Z",
  "angularUnits": "deg",
  "angularVelocityRepresentation": "VECTOR_IN_FRAME1",
  "angularVelocityUnits": "deg/s"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "798f7427-c87f-4579-92ab-68d2c9ab95e1",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Angle 3 (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ANGLE3"
    },
    {
      "name": "Angle 2 (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ANGLE2"
    },
    {
      "name": "Angle 1 (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ANGLE1"
    },
    {
      "name": "AV X (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "AV_X"
    },
    {
      "name": "AV Y (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "AV_Y"
    },
    {
      "name": "AV Z (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "AV_Z"
    },
    {
      "name": "AV Magnitude (deg/s)",
      "type": "NUMBER",
      "units": "deg/s",
      "outputID": "AV_MAG"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      -20.58940104,
      0.01874004,
      0.00136319,
      9.94596495e-7,
      -7.23492228e-8,
      -0.00634331,
      0.00634331
    ]
  ]
}

ILLUMINATION_ANGLES

Calculate the emission, phase and incidence angles at a point on a target as seen from an observer.

Standard parameters:

Parameters specifying the surface point on the target:

Additional parameters required:

NameDescription
observerThe observing body name or ID
illuminator The illumination source name or ID. This source may be any ephemeris object. This parameter is optional and, if not provided, it defaults to SUN.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine ILUMIN.

Example ILLUMINATION_ANGLES Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "ILLUMINATION_ANGLES",
  "target": "ENCELADUS",
  "shape1": "ELLIPSOID",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "coordinateRepresentation": "LATITUDINAL",
  "latitude": 0.0,
  "longitude": 0.0,
  "aberrationCorrection": "CN+S"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "af86f6eb-f415-4c99-9b55-95cf6bfaa011",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Incidence Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "INCIDENCE_ANGLE"
    },
    {
      "name": "Emission Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "EMISSION_ANGLE"
    },
    {
      "name": "Phase Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "PHASE_ANGLE"
    },
    {
      "name": "Observer Distance (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "OBSERVER_ALTITUDE"
    },
    {
      "name": "Time at Point",
      "type": "DATE",
      "units": "",
      "outputID": "TIME_AT_POINT"
    },
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    },
    {
      "name": "Local True Solar Time",
      "type": "STRING",
      "units": "",
      "outputID": "LTST"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      24.78527742,
      25.56007298,
      1.00079007,
      967668.02765637,
      "2012-10-19 08:23:56.772207 UTC",
      3.2277931,
      "13:15:59"
    ]
  ]
}

PHASE_ANGLE

Calculate the phase angle defined by the centers of an illumination source, a target and an observer.

The phase angle is computed using the location of the bodies (if point objects) or the center of the bodies (if finite bodies). The range of the phase angle is [0, pi].

Standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
illuminatorThe illumination source body name or ID. Often, the illumination source is the Sun, but it could be any other ephemeris object.
aberrationCorrectionThe SPICE aberration correction string. This computation supports only reception mode aberration corrections. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
For details of aberration correction applied to the target-observer and target-illuminator vectors, see the description of the input argument ABCORR of the SPICELIB routine PHASEQ.

Example PHASE_ANGLE Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "PHASE_ANGLE",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "illuminator": "SUN",
  "aberrationCorrection": "CN+S"

}
Example Results
{
   "status": "OK",
   "message": "The request was successful.",
   "calculationId": "34c2a6a3-5e8d-4ab9-8776-47cbc5e69915",
   "columns": [
      {
         "name": "UTC calendar date",
         "outputID": "DATE",
         "type": "DATE",
         "units": ""
      },
      {
         "name": "Phase Angle (deg)",
         "outputID": "PHASE_ANGLE",
         "type": "NUMBER",
         "units": "deg"
      }
   ],
   "rows": [
      [
         "2012-10-19 08:24:00.000000 UTC",
         0.99567811
      ]
   ]
}

POINTING_DIRECTION

Calculates the pointing direction in a user specified reference frame and output it as a unit or full magnitude vector represented in a user specified coordinate system.

The direction can be specified by the position or velocity of an object with respect to an observer, or by directly providing a vector, which could be specified as coordinates in a given frame, a frame axis, an instrument boresight, or as instrument FoV corner vectors.

The output reference frame may be different than the one used for specification of the input vector (if such option is selected). If so, the orientations of both frames relative to the inertial space are computed at the same time taking into account the aberration corrections given in the direction specification.

The output direction could be given as unit or non-unit vector in Rectangular, Azimuth/Elevation, Right Ascension/Declination/Range, Planetocentric, Cylindrical, or Spherical coordinates.

Standard parameters:

Additional parameters required:

NameDescription
direction Javascript object providing the specification for input direction vector. This dictionary shall comply to the specification provided in Additional Parameters for Specifying Directions.
referenceFrame The output reference frame.
vectorMagnitude Magnitude of the output vector representation. One of:
  • UNIT
  • PRESERVE_ORIGINAL
Use UNIT to represent the output direction vector as a unit vector, and PRESERVE_ORIGINAL to output the direction vector with its computed magnitude.
coordinateRepresentation Coordinate system used to specify the computed direction output coordinates. One of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • CYLINDRICAL
  • SPHERICAL
  • AZ_EL
Units are degrees for angular coordinate components. For unit vectors, the distance-type individual coordinate components have no units (unitless). For non-unit vectors originally defined by position, the units are Km; for non-unit vectors originally defined by velocity, the units are Km/s; and for non-unit vectors originally defined as vectors, the units are the same as those on input. Note that the distance-type individual coordinate components of pointing directions originally defined as Reference frame axis vectors have no units (these are always unitless by definition).
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when coordinateRepresentation is set to AZ_EL.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when coordinateRepresentation is set to AZ_EL.

Example POINTING_DIRECTION Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "POINTING_DIRECTION",
  "direction": {
    "directionType": "VECTOR",
    "observer": "CASSINI",
    "directionVectorType": "INSTRUMENT_FOV_BOUNDARY_VECTORS",
    "directionInstrument": "CASSINI_ISS_NAC",
    "aberrationCorrection": "CN",
    "antiVectorFlag": false
  },

  "referenceFrame": "J2000",
  "coordinateRepresentation": "RA_DEC",
  "vectorMagnitude": "UNIT"
}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "d6b1f2fb-9540-4e40-924d-451893c99ebb",
  "columns": [
    {
      "name": "UTC calendar date",
      "outputID": "DATE",
      "type": "DATE",
      "units": ""
    },
    {
      "name": "Boundary Point",
      "outputID": "BOUNDARY_POINT_NUMBER",
      "type": "NUMBER",
      "units": ""
    },
    {
      "name": "Right Ascension (deg)",
      "outputID": "RIGHT_ASCENSION",
      "type": "NUMBER",
      "units": "deg"
    },
    {
      "name": "Declination (deg)",
      "outputID": "DECLINATION",
      "type": "NUMBER",
      "units": "deg"
    },
    {
      "name": "Range (unitless)",
      "outputID": "RANGE",
      "type": "NUMBER",
      "units": "unitless"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      1.0,
      209.67666609,
      -9.57805349,
      1.0
    ],
    [
      "2012-10-19 08:24:00.000000 UTC",
      2.0,
      209.39265094,
      -9.78809254,
      1.0
    ],
    [
      "2012-10-19 08:24:00.000000 UTC",
      3.0,
      209.60585254,
      -10.06808401,
      1.0
    ],
    [
      "2012-10-19 08:24:00.000000 UTC",
      4.0,
      209.88997256,
      -9.85786722,
      1.0
    ]
  ]
}

SUB_SOLAR_POINT

Calculates the sub-solar point on a target as seen from an observer.

Standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
targetFrameThe target body-fixed reference frame name
observerThe observing body name or ID
subPointTypeThe method of finding the sub-solar point, as in the SPICE subslr() API call. One of:
  • Near point: ellipsoid
  • Intercept: ellipsoid
  • NADIR/DSK/UNPRIORITIZED
  • INTERCEPT/DSK/UNPRIORITIZED
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SUBSLR.
stateRepresentationOne of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC
  • PLANETOGRAPHIC
  • CYLINDRICAL
  • SPHERICAL

Example SUB_SOLAR_POINT Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "SUB_SOLAR_POINT",
  "target": "ENCELADUS",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "subPointType": "Near point: ellipsoid",
  "aberrationCorrection": "CN+S",
  "stateRepresentation": "RECTANGULAR"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "824e983c-f75f-4f49-89bd-b487a77da65c",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "X (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "X"
    },
    {
      "name": "Y (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "Y"
    },
    {
      "name": "Z (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "Z"
    },
    {
      "name": "Sub-Point Radius (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "SUB_POINT_RADIUS"
    },
    {
      "name": "Observer Distance (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "OBSERVER_ALTITUDE"
    },
    {
      "name": "Incidence Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "INCIDENCE_ANGLE"
    },
    {
      "name": "Emission Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "EMISSION_ANGLE"
    },
    {
      "name": "Phase Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "PHASE_ANGLE"
    },
    {
      "name": "Time at Point",
      "type": "DATE",
      "units": "",
      "outputID": "TIME_AT_POINT"
    },
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      234.00550655,
      -77.32612213,
      67.42916937,
      255.50851089,
      967644.15493281,
      4.49798357e-15,
      0.99611862,
      0.99611862,
      "2012-10-19 08:23:56.772287 UTC",
      3.22771347
    ]
  ]
}

SUB_OBSERVER_POINT

Calculate the sub-observer point on a target as seen from an observer.

Standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
targetFrameThe target body-fixed reference frame name
observerThe observing body name or ID
subPointTypeThe method of finding the sub-observer point, as in the SPICE subpnt() API call. One of:
  • Near point: ellipsoid
  • Intercept: ellipsoid
  • NADIR/DSK/UNPRIORITIZED
  • INTERCEPT/DSK/UNPRIORITIZED
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SUBPNT.
stateRepresentationOne of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC
  • PLANETOGRAPHIC
  • CYLINDRICAL
  • SPHERICAL

Example SUB_OBSERVER_POINT Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "SUB_OBSERVER_POINT",
  "target": "ENCELADUS",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "subPointType": "Near point: ellipsoid",
  "aberrationCorrection": "CN+S",
  "stateRepresentation": "RECTANGULAR"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "bcad1026-3535-4ec8-a8fe-3fe45d5d6e6f",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "X (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "X"
    },
    {
      "name": "Y (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "Y"
    },
    {
      "name": "Z (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "Z"
    },
    {
      "name": "Sub-Point Radius (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "SUB_POINT_RADIUS"
    },
    {
      "name": "Observer Distance (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "OBSERVER_ALTITUDE"
    },
    {
      "name": "Incidence Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "INCIDENCE_ANGLE"
    },
    {
      "name": "Emission Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "EMISSION_ANGLE"
    },
    {
      "name": "Phase Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "PHASE_ANGLE"
    },
    {
      "name": "Time at Point",
      "type": "DATE",
      "units": "",
      "outputID": "TIME_AT_POINT"
    },
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    },
    {
      "name": "Local True Solar Time",
      "type": "STRING",
      "units": "",
      "outputID": "LTST"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      232.5831733,
      -81.40386728,
      67.35505213,
      255.45689491,
      967644.11734179,
      0.99586304,
      1.66981544e-12,
      0.99586304,
      "2012-10-19 08:23:56.772287 UTC",
      3.22771334,
      "11:58:49"
    ]
  ]
}

SURFACE_INTERCEPT_POINT

Calculate the intercept point of a vector or vectors on a target as seen from an observer.

Standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
shape1The shape to use for the target body, One of:
  • ELLIPSOID
  • DSK
targetFrameThe target body-fixed reference frame name
observerThe observing body name or ID
directionVectorTypeType of vector to be used as the ray direction: the instrument boresight vector, the instrument field-of-view boundary vectors, an axis of the specified reference frame, a vector in the reference frame of the specified instrument, a vector in the specified reference frame. One of:
  • INSTRUMENT_BORESIGHT
  • INSTRUMENT_FOV_BOUNDARY_VECTORS
  • REFERENCE_FRAME_AXIS
  • VECTOR_IN_INSTRUMENT_FOV
  • VECTOR_IN_REFERENCE_FRAME
directionInstrumentThe instrument name or ID. Required only if directionVectorType is INSTRUMENT_BORESIGHT, INSTRUMENT_FOV_BOUNDARY_VECTORS, or VECTOR_IN_INSTRUMENT_FOV.
directionFrameThe vector's reference frame name. Required only if directionVectorType is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.
directionFrameAxisThe ray's direction frame axis. Required only if directionVectorType is REFERENCE_FRAME_AXIS. One of:
  • X
  • Y
  • Z
directionVectorXThe X ray's direction vector coordinate. If directionVectorType is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of directionVectorX, directionVectorY, and directionVectorZ must be provided, or both directionVectorRA and directionVectorDec, or both directionVectorAz and directionVectorEl.
directionVectorY The Y ray's direction vector coordinate.
directionVectorZ The Z ray's direction vector coordinate.
directionVectorRA The right ascension ray's direction vector coordinate.
directionVectorDec The declination ray's direction vector coordinate.
directionVectorAz The azimuth ray's direction vector coordinate.
directionVectorEl The elevation ray's direction vector coordinate.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine SINCPT.
stateRepresentationOne of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC
  • PLANETOGRAPHIC
  • CYLINDRICAL
  • SPHERICAL

Example SURFACE_INTERCEPT_POINT Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-14T00:00:00"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "SURFACE_INTERCEPT_POINT",
  "target": "SATURN",
  "shape1": "ELLIPSOID",
  "targetFrame": "IAU_SATURN",
  "observer": "CASSINI",
  "directionVectorType": "INSTRUMENT_BORESIGHT",
  "directionInstrument": "CASSINI_ISS_NAC",
  "aberrationCorrection": "NONE",
  "stateRepresentation": "LATITUDINAL"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9575c09e-6634-4765-8264-21e565a479d6",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Longitude (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "LONGITUDE"
    },
    {
      "name": "Latitude (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "LATITUDE"
    },
    {
      "name": "Intercept Radius (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "INTERCEPT_RADIUS"
    },
    {
      "name": "Observer Distance (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "OBSERVER_ALTITUDE"
    },
    {
      "name": "Incidence Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "INCIDENCE_ANGLE"
    },
    {
      "name": "Emission Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "EMISSION_ANGLE"
    },
    {
      "name": "Phase Angle (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "PHASE_ANGLE"
    },
    {
      "name": "Time at Point",
      "type": "DATE",
      "units": "",
      "outputID": "TIME_AT_POINT"
    },
    {
      "name": "Light Time (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "LIGHT_TIME"
    },
    {
      "name": "Local True Solar Time",
      "type": "STRING",
      "units": "",
      "outputID": "LTST"
    }
  ],
  "rows": [
    [
      "2012-10-14 00:00:00.000000 UTC",
      98.7675609,
      -38.69027976,
      57739.95803153,
      1831047.67987589,
      123.05323675,
      5.8567773,
      123.77530312,
      "2012-10-14 00:00:00.000000 UTC",
      6.10771763,
      "20:03:06"
    ]
  ]
}

TANGENT_POINT

Calculate the tangent point for a given observer, ray emanating from the observer, and target.

The tangent point is defined as the point on the ray nearest to the target's surface. This panel also computes the point on the target's surface nearest to the tangent point. The locations of both points are optionally corrected for light time and stellar aberration, and may be represented using either Rectangular, Ra/Dec, Planetocentric, Planetodetic, Planetographic, Spherical or Cylindrical coordinates.

The target's surface shape is modeled as a triaxial ellipsoid.

For remote sensing observations, for maximum accuracy, reception light time and stellar aberration corrections should be used. These corrections model observer-target-ray geometry as it is observed.

For signal transmission applications, for maximum accuracy, transmission light time and stellar aberration corrections should be used. These corrections model the observer-target-ray geometry that applies to the transmitted signal. For example, these corrections are needed to calculate the minimum altitude of the signal's path over the target body.

This calculation ignores differential aberration effects over the target body's surface: it computes corrections only at a user-specified point, which is called the "aberration correction locus." The user may select either the Tangent point or corresponding Surface point as the locus. In many cases, the differences between corrections for these points are very small.

Additionally, the illumination angles (incidence, emission and phase), time and local true solar time at the target point (where the aberration correction locus is set -- or at the tangent point if no corrections are used), and the light time to that point, are computed.

Standard parameters:

Additional parameters required:

NameDescription
computationMethodThe computation method. Currently, it is restricted to ELLIPSOID. This value indicates that the target shape is modeled as a triaxial ellipsoid
targetThe target body name or ID
targetFrameThe target body-fixed reference frame name
observerThe observing body name or ID
directionVectorTypeType of vector to be used as the ray direction: the instrument boresight vector, the instrument field-of-view boundary vectors, an axis of the specified reference frame, a vector in the reference frame of the specified instrument, a vector in the specified reference frame, or a vector defined by the position of a given object as seen from the observer. One of:
  • INSTRUMENT_BORESIGHT
  • INSTRUMENT_FOV_BOUNDARY_VECTORS
  • REFERENCE_FRAME_AXIS
  • VECTOR_IN_INSTRUMENT_FOV
  • VECTOR_IN_REFERENCE_FRAME
  • DIRECTION_TO_OBJECT
directionObjectThe ephemeris object name or ID. Required only if directionVectorType is DIRECTION_TO_OBJECT.
directionInstrumentThe instrument name or ID. Required only if directionVectorType is INSTRUMENT_BORESIGHT, INSTRUMENT_FOV_BOUNDARY_VECTORS, or VECTOR_IN_INSTRUMENT_FOV.
directionFrameThe vector's reference frame name. Required only if directionVectorType is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.
directionFrameAxisThe ray's direction frame axis. Required only if directionVectorType is REFERENCE_FRAME_AXIS. One of:
  • X
  • Y
  • Z
directionVectorXThe X ray's direction vector coordinate. If directionVectorType is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of directionVectorX, directionVectorY, and directionVectorZ must be provided, or both directionVectorRA and directionVectorDec, or both directionVectorAz and directionVectorEl.
directionVectorY The Y ray's direction vector coordinate.
directionVectorZ The Z ray's direction vector coordinate.
directionVectorRA The right ascension ray's direction vector coordinate.
directionVectorDec The declination ray's direction vector coordinate.
directionVectorAz The azimuth ray's direction vector coordinate.
directionVectorEl The elevation ray's direction vector coordinate.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
vectorAbCorr Type of aberration correction to be applied to the specified vector. Only required if directionVectorType is VECTOR_IN_REFERENCE_FRAME. One of:
  • NONE
  • STELLAR_ABERRATION_VECTOR
Use NONE to compute geometry without aberration corrections, and STELLAR_ABERRATION_VECTOR to correct the vector's direction for stellar aberration, taking into account the velocity of the observer with respect to the solar system barycenter. The direction of stellar aberration correction is determined by the light time direction selected in aberrationCorrection.

For backward compatibility, if not provided, it is assumed to be NONE.

aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
Note that the selected aberration correction applies both to the point set by correctionLocus and the direction vector if directionVectorType is DIRECTION_TO_OBJECT. For any other directionVectorType, the selected aberration correction only applies to the point set by correctionLocus.

For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine TANGPT.

correctionLocusAberration correction "locus," which is the fixed point in the Reference frame for which light time and stellar aberration corrections are computed. One of:
  • TANGENT_POINT
  • SURFACE_POINT
Required only when aberrationCorrection is not NONE.

Differential aberration effects across the surface of the target body are not considered. When aberration corrections are used, the effective positions of the observer and target, and the orientation of the target, are computed according to the corrections determined for the aberration correction locus.

The light time used to determine the position and orientation of the target body is that between the aberration correction locus and the observer.

The stellar aberration correction applied to the position of the target is that computed for the aberration correction locus.

Use TANGENT_POINT to compute corrections at the "tangent point." Use SURFACE_POINT to compute corrections at the point on the target's surface nearest to the tangent point.

When aberrationCorrection is NONE, the illumination angles, time, local true solar time and light time are computed with respect to the tangent point.

coordinateRepresentationCoordinate system to represent both the Tangent point and the point on the surface's target nearest to the target point. One of:
  • RECTANGULAR
  • RA_DEC
  • LATITUDINAL (planetocentric)
  • PLANETODETIC
  • PLANETOGRAPHIC
  • CYLINDRICAL
  • SPHERICAL

Example TANGENT_POINT Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2010-11-30T14:02:00"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "TANGENT_POINT",
  "computationMethod": "ELLIPSOID",
  "target": "ENCELADUS",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "directionVectorType": "INSTRUMENT_BORESIGHT",
  "directionInstrument": "CASSINI_UVIS_HSP",
  "aberrationCorrection": "CN+S",
  "correctionLocus": "TANGENT_POINT",
  "coordinateRepresentation": "RECTANGULAR"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "9575c09e-6634-4765-8264-21e565a479d6",
  "columns": [
  "columns": [
    {
      "name": "UTC calendar date",
      "outputID": "DATE",
      "type": "DATE",
      "units": ""
    },
    {
      "name": "Tangent Point Geometry",
      "outputID": "TANGENT_POINT_GEOMETRY",
      "type": "STRING",
      "units": ""
    },
    {
      "name": "Tangent Point X (km)",
      "outputID": "TANGENT_POINT_X",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Tangent Point Y (km)",
      "outputID": "TANGENT_POINT_Y",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Tangent Point Z (km)",
      "outputID": "TANGENT_POINT_Z",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Surface Point X (km)",
      "outputID": "SURFACE_POINT_X",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Surface Point Y (km)",
      "outputID": "SURFACE_POINT_Y",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Surface Point Z (km)",
      "outputID": "SURFACE_POINT_Z",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Distance to Tangent Point (km)",
      "outputID": "DISTANCE_TO_TANGENT_POINT",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Tangent Point Altitude (km)",
      "outputID": "TANGENT_POINT_ALTITUDE",
      "type": "NUMBER",
      "units": "km"
    },
    {
      "name": "Incidence Angle (deg)",
      "outputID": "INCIDENCE_ANGLE",
      "type": "NUMBER",
      "units": "deg"
    },
    {
      "name": "Emission Angle (deg)",
      "outputID": "EMISSION_ANGLE",
      "type": "NUMBER",
      "units": "deg"
    },
    {
      "name": "Phase Angle (deg)",
      "outputID": "PHASE_ANGLE",
      "type": "NUMBER",
      "units": "deg"
    },
    {
      "name": "Time at Point",
      "outputID": "TIME_AT_POINT",
      "type": "DATE",
      "units": ""
    },
    {
      "name": "Light Time (s)",
      "outputID": "LIGHT_TIME",
      "type": "NUMBER",
      "units": "s"
    },
    {
      "name": "Local True Solar Time",
      "outputID": "LTST",
      "type": "STRING",
      "units": ""
    }
 ],
 "rows": [
    [
      "2010-11-30 14:02:00.000000 UTC",
      "Ray above limb",
      -10.04382446,
      35.91102868,
      -330.90359129,
      -7.61303406,
      26.94731469,
      -246.7595201,
      49830.24430324,
      84.65507443,
      97.7218317,
      90.0210322,
      14.11694568,
      "2010-11-30 14:01:59.833784 UTC",
      0.1662158,
      "05:39:32"
    ]
 ],
}

OSCULATING_ELEMENTS

Calculate the osculating elements of the orbit of a target body around a central body. The orbit may be elliptical, parabolic, or hyperbolic. The elements are:

The calculation can be performed using the gravitational constant for the center of motion, the sum of the gravitational constants for the center of motion and the orbiting object, or a value provided by the user. In the first two cases, the values for the gravitational constant(s) are provided by SPICE kernel(s).

Osculating elements are valid only when computed in a non-rotating reference frame.

Standard parameters:

Additional parameters required:

NameDescription
orbitingBodyThe SPICE body name or ID for the orbiting body.
centerBodyThe SPICE body name or ID for the body that is the center of motion.
referenceFrame The reference frame name. Osculating elements are valid only when computed in a non-rotating reference frame.
gmType The gravitational constant to be used in the computation. One of:
  • CENTER
  • CENTER_ORBITER
  • CUSTOM

If gmType is CENTER, the GM is the center of motion's gravitational constant. If it is CENTER_ORBITER, the GM is computed as the sum of the gravitational constants of the orbiting object and center of motion bodies. If it is CUSTOM, the GM shall be provided by the user.

For calculations where the orbiting body has negligible mass compared to the center of motion (for example, spacecraft and planet), use CENTER GM. When the orbiting body has non-negligible mass compared to the center of motion (for example, Moon and Earth), use CENTER_ORBITER GM.

Note: if not provided, gmType defaults to CENTER.

gmValue The custom gravitational constant to be used in the computation. Required if gmType is CUSTOM, and ignored otherwise.

Example OSCULATING_ELEMENTS Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 1
    },
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "times": [
    "2012-10-19T08:24:00.000"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "OSCULATING_ELEMENTS",
  "orbitingBody": "CASSINI",
  "centerBody": "SATURN",
  "referenceFrame": "J2000",
  "gmType": "CENTER"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "178cf91a-f59a-442d-b44f-6b2bb3e213ee",
  "columns": [
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Perifocal distance (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "PERIFOCAL_DISTANCE"
    },
    {
      "name": "Eccentricity",
      "type": "NUMBER",
      "units": "",
      "outputID": "ECCENTRICITY"
    },
    {
      "name": "Inclination (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "INCLINATION"
    },
    {
      "name": "Ascending node longitude (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ASCENDING_NODE_LONGITUDE"
    },
    {
      "name": "Argument of periapse (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "ARGUMENT_OF_PERIAPSE"
    },
    {
      "name": "Mean anomaly (deg)",
      "type": "NUMBER",
      "units": "deg",
      "outputID": "MEAN_ANOMALY_AT_EPOCH"
    },
    {
      "name": "Orbiting body range (km)",
      "type": "NUMBER",
      "units": "km",
      "outputID": "ORBITING_BODY_RANGE"
    },
    {
      "name": "Orbiting body speed (km/s)",
      "type": "NUMBER",
      "units": "km/s",
      "outputID": "ORBITING_BODY_SPEED"
    },
    {
      "name": "Period (s)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "PERIOD"
    },
    {
      "name": "GM (km^3/s^2)",
      "type": "NUMBER",
      "units": "km^3/s^2",
      "outputID": "GM"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:24:00.000000 UTC",
      474789.03917271,
      0.70348463,
      38.18727034,
      223.98123058,
      71.59474487,
      14.65461204,
      753794.65101401,
      8.77222231,
      2067101.2236748,
      37931207.49865224
    ]
  ]
}

GF_COORDINATE_SEARCH

Find time intervals when a coordinate of an observer-target position vector satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
referenceFrameThe reference frame name
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFPOSC.
conditionThe coordinate condition to search for. See specifying conditions for more information.

Example GF_COORDINATE_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_COORDINATE_SEARCH",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "referenceFrame": "CASSINI_ISS_NAC",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "coordinateSystem": "SPHERICAL",
    "coordinate": "COLATITUDE",
    "relationalCondition": "<",
    "referenceValue": 0.25,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "f3327213-79c5-43c9-aa4e-e8cc6844c8ac",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 07:42:59.633339 UTC",
      "2012-10-19 08:39:33.749463 UTC",
      3394.11612415
    ]
  ]
}

GF_ANGULAR_SEPARATION_SEARCH

Find time intervals when the angle between two bodies, as seen by an observer, satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
target1The first target body name or ID
shape1The shape type to use for the first target. One of:
  • POINT
  • SPHERE
target2The second target body name or ID
shape2The shape type to use for the second target. One of:
  • POINT
  • SPHERE
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFSEP.
conditionThe condition to search for. See specifying conditions for more information.

Example GF_ANGULAR_SEPARATION_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_ANGULAR_SEPARATION_SEARCH",
  "target1": "SATURN",
  "shape1": "POINT",
  "target2": "ENCELADUS",
  "shape2": "POINT",
  "observer": "CASSINI",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "relationalCondition": ">",
    "referenceValue": 7.0,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "c1713f67-5d1b-4ffb-b691-52e9a3c77596",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:17:41.782732 UTC",
      "2012-10-19 09:00:01.000000 UTC",
      2539.21726751
    ]
  ]
}

GF_DISTANCE_SEARCH

Find time intervals when the distance between a target and observer satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFDIST.
conditionThe condition to search for. See specifying conditions for more information.

Example GF_DISTANCE_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_DISTANCE_SEARCH",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "relationalCondition": "<",
    "referenceValue": 960000.0,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "a7f661f7-1792-42ba-bd13-c9437a2032e0",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 06:59:59.000000 UTC",
      "2012-10-19 07:35:59.695642 UTC",
      2160.6956417
    ]
  ]
}

GF_SUB_POINT_SEARCH

Find time intervals when a coordinate of the sub-observer point on a target satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
targetFrameThe target body-fixed frame name
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFSUBC.
subPointTypeThe method of finding the sub-observer point, as in the SPICE gfsubc() API call. One of:
  • Near point: ellipsoid
  • Intercept: ellipsoid
conditionThe coordinate condition to search for. See specifying conditions for more information.

Example GF_SUB_POINT_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_SUB_POINT_SEARCH",
  "target": "ENCELADUS",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "aberrationCorrection": "NONE",
  "subPointType": "Near point: ellipsoid",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "coordinateSystem": "LATITUDINAL",
    "coordinate": "LATITUDE",
    "relationalCondition": "<",
    "referenceValue": 15.0,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "26cb3e18-0f85-4cec-aaa4-3c2187469260",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:58:13.550321 UTC",
      "2012-10-19 09:00:01.000000 UTC",
      107.44967914
    ]
  ]
}

GF_OCCULTATION_SEARCH

Find time intervals when an observer sees one target occulted by, or in transit across, another.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
occultationTypeType of occultation to be considered in the calculation. Transits are considered to be a type of occultation. One of:
  • ANY
  • FULL
  • ANNULAR
  • PARTIAL
target1The SPICE numeric name or ID of the front body.
shape1The geometric model used to represent the shape of the front body. One of:
  • POINT
  • ELLIPSOID
  • DSK
frame1The front body body-fixed frame name. Required if shape1 is ELLIPSOID, and ignored otherwise.
target2The SPICE numeric name or ID of the back body.
shape2The geometric model used to represent the shape of the back body. One of:
  • POINT
  • ELLIPSOID
  • DSK
frame2The back body body-fixed frame name. Required if shape1 is ELLIPSOID, and ignored otherwise.
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • CN
  • XLT
  • XCN
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFOCLT.

Example GF_OCCULTATION_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 1
    },
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2017-08-21 15:00:00",
      "endTime": "2017-08-21 23:00:00"
    },
    {
      "startTime": "2017-08-22 15:00:00",
      "endTime": "2017-08-22 23:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "HOURS",

  "calculationType": "GF_OCCULTATION_SEARCH",
  "occultationType": "ANY",
  "target1": "MOON",
  "shape1": "ELLIPSOID",
  "frame1": "IAU_MOON",
  "target2": "EARTH",
  "shape2": "ELLIPSOID",
  "frame2": "IAU_EARTH",
  "observer": "SUN",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "093f1a8d-dbf0-4f5e-b826-79a1dc401339",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2017-08-21 16:17:50.138140 UTC",
      "2017-08-21 20:34:30.965976 UTC",
      15400.82783592
    ]
  ]
}

GF_SURFACE_INTERCEPT_POINT_SEARCH

Find time intervals when a coordinate of a surface intercept vector satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
targetFrameThe target body-fixed reference frame name
observerThe observing body name or ID
directionVectorTypeType of vector to be used as the ray direction: the instrument boresight vector, an axis of the specified reference frame, a vector in the reference frame of the specified instrument, a vector in the specified reference frame. One of:
  • INSTRUMENT_BORESIGHT
  • REFERENCE_FRAME_AXIS
  • VECTOR_IN_INSTRUMENT_FOV
  • VECTOR_IN_REFERENCE_FRAME
directionInstrumentThe instrument name or ID. Required only if directionVectorType is INSTRUMENT_BORESIGHT, or VECTOR_IN_INSTRUMENT_FOV.
directionFrameThe vector's reference frame name. Required only if directionVectorType is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.
directionFrameAxisThe ray's direction frame axis. Required only if directionVectorType is REFERENCE_FRAME_AXIS. One of:
  • X
  • Y
  • Z
directionVectorXThe X ray's direction vector coordinate. If directionVectorType is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of directionVectorX, directionVectorY, and directionVectorZ must be provided, or both directionVectorRA and directionVectorDec, or both directionVectorAz and directionVectorEl.
directionVectorYThe Y ray's direction vector coordinate.
directionVectorZThe Z ray's direction vector coordinate.
directionVectorRAThe right ascension ray's direction vector coordinate.
directionVectorDecThe declination ray's direction vector coordinate.
directionVectorAzThe azimuth ray's direction vector coordinate.
directionVectorElThe elevation ray's direction vector coordinate.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFSNTC.
conditionThe coordinate condition to search for. See specifying conditions for more information.

Example GF_SURFACE_INTERCEPT_POINT_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-13T18:00:00",
      "endTime": "2012-10-14T06:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_SURFACE_INTERCEPT_POINT_SEARCH",
  "target": "SATURN",
  "targetFrame": "IAU_SATURN",
  "observer": "CASSINI",
  "directionVectorType": "INSTRUMENT_BORESIGHT",
  "directionInstrument": "CASSINI_ISS_NAC",
  "directionFrame": "CASSINI_ISS_NAC",
  "directionFrameAxis": "Z",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "coordinateSystem": "PLANETOGRAPHIC",
    "coordinate": "LONGITUDE",
    "relationalCondition": "RANGE",
    "referenceValue": 150.0,
    "upperLimit": 180.0,
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "cd0ba9b2-38dd-438e-9947-624828c836e8",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-13 20:40:08.098400 UTC",
      "2012-10-13 21:34:05.267972 UTC",
      3237.16957152
    ]
  ]
}

GF_TARGET_IN_INSTRUMENT_FOV_SEARCH

Find time intervals when a target intersects the space bounded by the field-of-view of an instrument.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
instrumentThe SPICE numeric name or ID of the instrument.
targetThe SPICE numeric name or ID of the target.
shapeGeometric model used to represent the shape of the body. One of:
  • POINT
  • ELLIPSOID
targetFrameThe target body-fixed frame name.
observerThe SPICE numeric name or ID of the observing body.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFTFOV.

Example GF_TARGET_IN_INSTRUMENT_FOV_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_TARGET_IN_INSTRUMENT_FOV_SEARCH",
  "instrument": "CASSINI_ISS_NAC",
  "target": "ENCELADUS",
  "shape": "ELLIPSOID",
  "targetFrame": "IAU_ENCELADUS",
  "observer": "CASSINI",
  "aberrationCorrection": "CN+S",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "7a9d0995-9f88-4b17-a810-faf3458d8d82",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 07:43:02.743464 UTC",
      "2012-10-19 08:39:30.177172 UTC",
      3387.43370879
    ]
  ]
}

GF_RAY_IN_FOV_SEARCH

Find time intervals when a specified ray is contained in the space bounded by an instrument's field-of-view.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
instrumentThe SPICE numeric name or ID of the instrument.
observerThe SPICE numeric name or ID of the observing body.
directionVectorTypeType of vector to be used as the ray direction: the instrument boresight vector, an axis of the specified reference frame, a vector in the reference frame of the specified instrument, a vector in the specified reference frame. One of:
  • INSTRUMENT_BORESIGHT
  • REFERENCE_FRAME_AXIS
  • VECTOR_IN_INSTRUMENT_FOV
  • VECTOR_IN_REFERENCE_FRAME
directionInstrumentThe instrument name or ID. Required only if directionVectorType is INSTRUMENT_BORESIGHT, or VECTOR_IN_INSTRUMENT_FOV.
directionFrameThe vector's reference frame name. Required only if directionVectorType is REFERENCE_FRAME_AXIS or VECTOR_IN_REFERENCE_FRAME.
directionFrameAxisThe ray's direction frame axis. Required only if directionVectorType is REFERENCE_FRAME_AXIS. One of:
  • X
  • Y
  • Z
directionVectorXThe X ray's direction vector coordinate. If directionVectorType is VECTOR_IN_INSTRUMENT_FOV or VECTOR_IN_REFERENCE_FRAME, then either all three of directionVectorX, directionVectorY, and directionVectorZ must be provided, or both directionVectorRA and directionVectorDec, or both directionVectorAz and directionVectorEl.
directionVectorYThe Y ray's direction vector coordinate.
directionVectorZThe Z ray's direction vector coordinate.
directionVectorRAThe right ascension ray's direction vector coordinate.
directionVectorDecThe declination ray's direction vector coordinate.
directionVectorAzThe azimuth ray's direction vector coordinate.
directionVectorElThe elevation ray's direction vector coordinate.
azccwFlag Flag indicating how azimuth is measured. If azccwFlag is true, azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
elplszFlag Flag indicating how elevation is measured. If elplszFlag is true, elevation increases from the XY plane toward +Z; otherwise toward -Z. Required only when directionVectorAz and directionVectorEl are used to provide the coordinates of the direction vector.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • S (currently does not work due to a bug)
  • XS (currently does not work due to a bug)
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFRFOV.

Example GF_RAY_IN_FOV_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_RAY_IN_FOV_SEARCH",
  "instrument": "CASSINI_ISS_NAC",
  "observer": "CASSINI",
  "directionVectorType": "VECTOR_IN_REFERENCE_FRAME",
  "directionInstrument": "",
  "directionFrame": "J2000",
  "directionFrameAxis": "",
  "directionVectorRA": 208.0,
  "directionVectorDec": -10.0,
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "f9546e47-9666-4f84-9ae3-d2baddcc761e",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 07:56:33.919960 UTC",
      "2012-10-19 08:00:57.704818 UTC",
      263.78485787
    ]
  ]
}

GF_RANGE_RATE_SEARCH

Find time intervals when the range rate between a target and observer satisfies a condition.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
  • XLT
  • XLT+S
  • XCN
  • XCN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFRR.
conditionThe condition to search for. See specifying conditions for more information.

Example GF_RANGE_RATE_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_RANGE_RATE_SEARCH",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "relationalCondition": "<",
    "referenceValue": 2.0,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "7fdf903d-a266-413c-af55-6945463fcddc",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:35:12.929162 UTC",
      "2012-10-19 09:00:01.000000 UTC",
      1488.07083756
    ]
  ]
}

GF_PHASE_ANGLE_SEARCH

Find time intervals for which a specified constraint on the phase angle defined by an illumination source, a target, and an observer body centers is met.

Standard parameters:

GF standard parameters:

Additional parameters required:

NameDescription
targetThe target body name or ID
observerThe observing body name or ID
illuminator The illumination source name or ID. This source may be any ephemeris object.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFPA.
conditionThe condition to search for. See specifying conditions for more information.

Example GF_PHASE_ANGLE_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_PHASE_ANGLE_SEARCH",
  "target": "ENCELADUS",
  "observer": "CASSINI",
  "illuminator": "SUN",
  "aberrationCorrection": "NONE",

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "MINUTES",

  "condition": {
    "relationalCondition": "<",
    "referenceValue": 2.0,
    "upperLimit": "",
    "adjustmentValue": ""
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "e735ce95-97f5-4e62-88c0-3e8120ec79b3",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:08:05.031235 UTC",
      "2012-10-19 09:00:01.000000 UTC",
      3115.96876544
    ]
  ]
}

GF_ILLUMINATION_ANGLES_SEARCH

Find the time intervals, within a specified time window, when one of the illumination angles — phase, incidence or emission — at the specified target body surface point as seen from an observer satisfies a given constraint.

Standard parameters:

GF standard parameters:

Parameters specifying the surface point on the target:

Additional parameters required:

NameDescription
observerThe observing body name or ID
illuminator The illumination source name or ID. This source may be any ephemeris object.
aberrationCorrectionThe SPICE aberration correction string. One of:
  • NONE
  • LT
  • LT+S
  • CN
  • CN+S
For aberration correction details, see the description of the input argument ABCORR of the SPICELIB routine GFILUM.
conditionThe condition to search for. See specifying conditions for more information.

Example GF_ILLUMINATION_ANGLES_SEARCH Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "UTC",
  "timeFormat": "CALENDAR",
  "intervals": [
    {
      "startTime": "2012-10-19T07:00:00",
      "endTime": "2012-10-19T09:00:00"
    }
  ],
  "timeStep": 1,
  "timeStepUnits": "MINUTES",

  "calculationType": "GF_ILLUMINATION_ANGLES_SEARCH",
  "observer": "CASSINI",
  "illuminator": "SUN",
  "aberrationCorrection": "NONE",

  "target": "ENCELADUS",
  "shape1": "ELLIPSOID",
  "targetFrame": "IAU_ENCELADUS",
  "offSurfaceFlag": false,
  "coordinateRepresentation": "LATITUDINAL",
  "latitude": 0.0,
  "longitude": 90.0,

  "outputDurationUnits": "SECONDS",
  "shouldComplementWindow": false,
  "intervalAdjustment": "EXPAND_INTERVALS",
  "intervalAdjustmentAmount": 1.0,
  "intervalAdjustmentUnits": "SECONDS",
  "intervalFiltering": "FILTER_INTERVALS",
  "intervalFilteringThreshold": 1.0,
  "intervalFilteringThresholdUnits": "SECONDS",

  "condition": {
    "angleType": "EMISSION",
    "relationalCondition": "ABSMAX",
    "adjustmentValue": 0.001
  }

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "e735ce95-97f5-4e62-88c0-3e8120ec79b3",
  "columns": [
    {
      "name": "Start Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Stop Time",
      "type": "DATE",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "Duration (secs)",
      "type": "NUMBER",
      "units": "s",
      "outputID": "DURATION"
    }
  ],
  "rows": [
    [
      "2012-10-19 08:59:58.480638 UTC",
      "2012-10-19 09:00:01.000000 UTC",
      2.51936162
    ]
  ]
}

TIME_CONVERSION

Convert times from one time system or format to another.

Standard parameters:

Additional parameters required:

NameDescription
outputTimeSystemThe time system for the result times. One of:
  • UTC
  • TDB
  • TDT
  • TT
  • SPACECRAFT_CLOCK
  • GPS

If SPACECRAFT_CLOCK is selected, then outputSclkId must also be provided.

Note that in SPICE, TDT (Terrestrial Dynamical Time) and TT (Terrestrial Time) refer to the same time system.

outputTimeFormatOne of:
  • CALENDAR
  • CALENDAR_YMD; synonym of CALENDAR
  • CALENDAR_DOY
  • JULIAN
  • SECONDS_PAST_GPS0
  • SECONDS_PAST_J2000
  • SPACECRAFT_CLOCK_STRING
  • SPACECRAFT_CLOCK_TICKS
  • CUSTOM
  • WEEK_TOW

CALENDAR, CALENDAR_YMD and CALENDAR_DOY are applicable only when outputTimeSystem is UTC, TDB, TDT, TT or GPS.

JULIAN, SECONDS_PAST_J2000 and CUSTOM are applicable only when outputTimeSystem is UTC, TDB, TDT or TT.

SPACECRAFT_CLOCK_STRING and SPACECRAFT_CLOCK_TICKS are applicable only when outputTimeSystem is SPACECRAFT_CLOCK.

SECONDS_PAST_GPS0 and WEEK_TOW are applicable only when outputTimeSystem is GPS.

If CUSTOM is selected, then outputTimeCustomFormat must also be provided.

outputSclkIdThe output SCLK ID. Only used if outputTimeSystem is SPACECRAFT_CLOCK.
outputTimeCustomFormatA SPICE timout() format string. Only used if outputTimeFormat is CUSTOM. For details, please refer to the custom output format help.

Example TIME_CONVERSION Calculation

Example Post Data
{

  "kernels": [
    {
      "type": "KERNEL_SET",
      "id": 5
    }
  ],

  "timeSystem": "SPACECRAFT_CLOCK",
  "timeFormat": "SPACECRAFT_CLOCK_STRING",
  "sclkId": -82,
  "times": [
    "1/1729329441.042"
  ],
  "timeStep": 1,
  "timeStepUnits": "SECONDS",

  "calculationType": "TIME_CONVERSION",
  "outputTimeSystem": "UTC",
  "outputTimeFormat": "CALENDAR",
  "outputSclkId": "",
  "outputTimeCustomFormat": "YYYY Month DD HR:MN"

}
Example Results
{
  "status": "OK",
  "message": "The request was successful.",
  "calculationId": "5218d94d-1e15-4c07-98c9-adeb26249336",
  "columns": [
    {
      "name": "SCLK string (ID=-82)",
      "type": "NUMBER",
      "units": "",
      "outputID": "DATE"
    },
    {
      "name": "UTC calendar date",
      "type": "DATE",
      "units": "",
      "outputID": "DATE2"
    }
  ],
  "rows": [
    [
      "1/1729329441.042",
      "2012-10-19 08:24:03.001344 UTC"
    ]
  ]
}

API Calculation Type vs. WGC GUI Calculation

For reference, the following table provides the mapping between the calculation types available through this API and those in the WGC graphical user interface.

API Calculation Type GUI Calculation
STATE_VECTOR State Vector
ANGULAR_SEPARATION Angular Separation
ANGULAR_SIZE Angular Size
FRAME_TRANSFORMATION Frame Transformation
ILLUMINATION_ANGLES Illumination Angles
PHASE_ANGLE Phase Angle
POINTING_DIRECTION Pointing Direction
SUB_SOLAR_POINT Sub-solar Point
SUB_OBSERVER_POINT Sub-observer Point
SURFACE_INTERCEPT_POINT Surface Intercept Point
TANGENT_POINT Tangent Point
OSCULATING_ELEMENTS Orbital Elements
GF_COORDINATE_SEARCH Position Finder
GF_ANGULAR_SEPARATION_SEARCH Angular Separation Finder
GF_DISTANCE_SEARCH Distance Finder
GF_SUB_POINT_SEARCH Sub-Point Finder
GF_OCCULTATION_SEARCH Occultation Finder
GF_SURFACE_INTERCEPT_POINT_SEARCH Surface Intercept Finder
GF_TARGET_IN_INSTRUMENT_FOV_SEARCH Target in Field of View Finder
GF_RAY_IN_FOV_SEARCH Ray in Field of View Finder
GF_RANGE_RATE_SEARCH Range Rate Finder
GF_PHASE_ANGLE_SEARCH Phase Angle Finder
GF_ILLUMINATION_ANGLES_SEARCH Illumination Angles Finder
TIME_CONVERSION Time Conversion

References

JSON

RESTful Web Services