VO-TOOLS

The GRS is the largest persistent high-pressure region in the atmosphere of Jupiter, located in the South Equatorial Belt (SEB). Since 1878, the GRS, and many other noticeable vortices, are continuously observed to measure and follow their evolution, their size and their coordinates (longitude and latitude). Some measures date back even to 1830.

Among the numerous resources providing information and data about Jupiter, the JUPOS project is the main reference for collecting precise positions of the characteristics of the Jovian clouds, analyzing them in drift charts, and study their motion over time.

GRS longitude: from the data freely available on the JUPOS Web site, we can set up a time series of the GRS longitude in Jupiter's reference system II, which allows to interpolate the longitude at any epoch between 1830 and now. To compute ephemerides in the close future, the last 4 measured values of the longitude are used to extrapolate its value using a polynomial interpolation. In June 2020, the GRS continues to drift 1.75° per month.

GRS latitude: Simon et al. (AJ 155:151, 2018) provide an accurate estimation of the GRS central latitude over time, which has only varied of ∼0.3° from 1979 to 2017.

https://ssp.imcce.fr/webservices/vo-tools/jgrs/?q=[action]&[parameters]

• transit to compute the timing of the passage of the GRS at the central meridian,
• visibility to determine when the GRS is visible from the observer,
• ephemeris to compute the coordinates of the GRS and the physical ephemeris of Jupiter,

The output results are described in the following section, and are available in VOTable (default), HTML, comma-separated values (CSV), plain text format, and JSON object (cf. examples). Some parameters are optionnal, and their values can be omitted (just left blank the value, e.g. &-mime=&-output=). The input parameters without a default value must be provided.

https://ssp.imcce.fr/webservices/vo-tools/jgrs/[q]/[date]

By default, the transits, visibility and ephemeris of the GRS are computed for a geocentric observer. To change the location you must use the Web service or the HTTP request.

Examples

• Compute the timings of the transit of the GRS for: today's date or 1^st September 2020
• Compute the period of visibility of the GRS for: today's date or 1^st September 2020
• Compute the ephemeris of the GRS for: current date and time or 1^st September 2020 at 12^h

#Tips for transit and visibility, the date can be provided without the time part (e.g. 2020-09-01 or 2459094) to compute the events for the day.

For GRS transits only: if you want to get the figures in addition to the data, you need to add the word /figure to the previous URL:

https://ssp.imcce.fr/webservices/vo-tools/jgrs/transit/[date]/figure

Examples

• data and figures of the GRS transits for: today's date or 1^st September 2020

Web Service URI:

https://ssp.imcce.fr/webservices/vo-tools/jgrs/jgrs.php

Namespace:

https://ssp.imcce.fr/webservices/vo-tools/jgrs

WSDL:

https://ssp.imcce.fr/webservices/vo-tools/jgrs/jgrs.php?wsdl

SOAP header:

name of the SOAP header element: clientID

SOAP header's content: array('from' => 'YourName', 'hostip'=>'', 'lang'=>'en|fr')

Methods:

transit (inputArray)
visibility (inputArray)
ephemeris (inputArray)

The output of the method is an object containing the following attributes:

'flag'

the status of the response: flag=1 means ok; flag=0 or flag=-1 mean that an error occured

'status'

the HTTP status-code of the response (e.g. 400: bad request, 422: Unprocessable Entity, 500: internal error)

'ticket'

the Unix timestamp of the response which can be useful to stamp the request

'result'

a string containing the ephemeris of the requested solar system body with parameters depending on user's options (see Output parameters section).

votable

the data are written in the IVOA standard VOTable format

text

the data are returned in plain text where each block of data is separated by the semicolon character ';', and fields are separated by one or more blank character. The first block is the keyword '#! ephem' which marks the beginning of the data.

text/csv

the data are returned in plain text where each block of data is separated by the semicolon character ';', and fields are separated by a comma. The first line provides the ticket (Unix timestamp of the response) and the flag of the response, and the second line provides the field headers.

JSON

the data are written in a JSON object.

image

only the figures are retrieved, without the data results (see Output parameters section).

» Epoch

The epoch must be formatted as a textual english date (in accordance with the GNU syntax of dates), or as a julian day or as an ISO 8601 date. The timescale of the epoch is UTC. For the transit and visibility methods, only the date part is considered, whatever the time.

Examples (non exhaustive) of valid dates:

• now
• 2020-07-27
• 2020-01-27T1:53:34
• 2453762.529467592
• 10 September 2000
• +1 day
• +1 week 2 days 4 hours 2 seconds
• next Thursday
• last Monday

» Observer coordinates

The coordinates of a terrestrial observer can be defined by the IAU code of the observatory, by the code 500 for an observed located at the centre of mass of the Earth (geocenter), or by its geographical coordinates if the observing location is not referenced in the IAU database of observatory. Read the documentation for more info. Nevertheless, Jupiter being far away from Earth, the maximum geometric parallax is negligible so that the coordinates of the GRS are identical from any terrestrial point of view. It is thus recommended to use the default location (geocenter).

To observe the GRS from an extra-terrestrial point of view (e.g. an interplanetary spacecraft), you can define the location using one of the codes recognized by Miriade.ephemph method.

--greg

to format the epoch as a calendar date.

--iso

to format the epoch as an ISO-8601 date (default).

--jd

to format the epoch as a julian period.

--lighttime

to display the value of the light time between the target and the observer.

--ttmutc

to display the TT-UTC value.

• Transits now in JSON format or the 1st July 2020 in VOTable format
• Visibility in July 2020 in text/csv format
• Ephemeris now for the 6 next hours in JSON format

» Data

The output parameters of the transit and visibility methods are described in the following table. Columns with italic numbers are present only when the corresponding option is enabled. The output parameters of the ephemeris method are described in the Miriade.ephemph method. They are completed by the jovicentric longitude and latitude of the GRS in the system II.

Notes:

1. By default the date is expressed in the ISO-8601 format. It can be changed to julian period or calendar date with the output argument.
2. See Optional parameters section.
3. The sub-observer and sub-Solar point are expressed in the system II.

» Figure

When the argument view is set to PDF or EPS, the data are completed by an URL to download a figure displaying the apparent aspect of Jupiter at the date of the ephemeris.

The psvopts argument allows to pass options to the image generator, to control some parts of the drawing. The general syntax is a list of options separated by the semicolon character:

psvopts="zoom=a[,b];label=0|1"

where:

zoom=a[,b]

Defines the bounds of the x and y axes with the value ±a, and ±b for the y-axis if provided. Examples: zoom(2) plot a scene of ±2 Sso radius along x and y axes; zoom(9.0,1.7) plot a scene of ±9 Sso radius in x, and ±1.7 Sso radius in y.

label=0|1

Displays (default) or not (0) the labels in the image.

$> curl "<URL>"

$> wget "<URL>"

To help you in calling the JGRS Web service, here are some detailed explanations to write a client with PHP and SOAP which invokes the transit method:

1/ Provide the input parameters which are mandatory for the service:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$action = 'transit';
$param = array('epoch' => now,
               'nbd' => 1,
               'step' => '',
               'observer' => '500',
               'mime' => 'json',
               'output' => '--lighttime'
);

2/ Define the SOAP options, the namespace and the WSDL URI of JGRS Web service:

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// JGRS namespace
$namespace = 'https://ssp.imcce.fr/webservices/vo-tools/jgrs';
// JGRS WSDL
$uriwsdl = $namespace.'/jgrs.wsdl';

3/ Create a SoapClient object in WSDL mode, set the SOAP header, then call the method and catch exceptions:

try {
   // Constructs the client
   $client = new SoapClient($uriwsdl, array('exceptions'=>1));
   // SOAP header
   $header = array('from'=>$from, 'hostip'=>'', 'lang'=>'en');
   $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));  
   // Call the resolver method
   $response = $client->__soapCall($action,array($param));
   // Display results
   if ($param['mime'] == 'text')
   {
     $res = explode(';', $response->result);
     $nbr = count($res);
     $newkey = array_keys($res);
     header("HTTP/1.0 ".$response->status);
     header("Content-Type: text/plain");
     echo "# Flag: ".$response->flag.PHP_EOL;
     echo "# Ticket: ".$response->ticket.PHP_EOL;
     for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]].PHP_EOL; }
   }
   else if ($param['mime'] == 'text/csv')
   {
     $res = explode(';', $response->result);
     $nbr = count($res);
     $newkey = array_keys($res);
     header("HTTP/1.0 ".$response->status);
     if ($response->status < 300) {
       header("Content-Type: text/csv");
       header('Content-disposition: attachment;filename="ephemph.csv"'); 
     } else {
       header("Content-Type: text/plain");
     }
     echo "# Flag: ".$response->flag.PHP_EOL;
     echo "# Ticket: ".$response->ticket.PHP_EOL;
     for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]].PHP_EOL; }
   }
   else if ($param['mime'] == 'json')
   {
     header("HTTP/1.0 ".$response->status);
     header("Content-Type: application/json");
     echo $response->result;
   }
   else if ($param['mime'] == 'image')
   {
     if ($response->status < 300) {
       switch ($param['view']) {
       case "pdf":
       case "wired:pdf":
         $content = "application/pdf"; 
         $ext = "pdf";
         break;
       case "eps":
       case "wired:eps":
         $content = "application/postscript"; 
         $ext = "eps";
         break;
       default:
         $content = ""; 
         $ext = "dat";
         break;
       }
       header("HTTP/1.0 ".$response->status);
       header("Content-Type: ".$content);
       header("Content-disposition: attachment;filename=\"jgrs.".$ext."\"");
       echo file_get_contents($response->result);
     }
     else
     {
       header("HTTP/1.0 ".$response->status);
       header("Content-Type: text/xml;content=x-votable");
       echo $response->result;
     }
   }
   else
   {
     header("HTTP/1.0 ".$response->status);
     header("Content-Type: text/xml;content=x-votable");
     echo $response->result;
   }
} catch (SoapFault $fault) {
   trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode},
                               faultstring: {$fault->faultstring})", E_USER_ERROR);
}