Basic usage of WebGeoCalc API

The API variable in webgeocalc provide an access to the WebGeoCalc API (on its default wgc2 server) :

>>> from webgeocalc import API
>>> API.url
'https://wgc2.jpl.nasa.gov:8443/webgeocalc/api'

Request kernel sets

List all the kernel sets available on the API:

>>> API.kernel_sets()
[<KernelSetDetails> Solar System Kernels (id: 1), ...]

or request a single kernel set with it name of id:

>>> API.kernel_set('Cassini Huygens')
<KernelSetDetails> Cassini Huygens (id: 5)

Convert it as int and you will get its id:

>>> int(API.kernel_set('Cassini Huygens'))
5

Convert it as str and you will get its caption name:

>>> str(API.kernel_set(5))
'Cassini Huygens'

Get all the kernel set attributes and values:

>>> dict(API.kernel_set('Cassini Huygens').items())
{'caption': 'Cassini Huygens', 'sclkId': '-82', 'description': ...}

If more than one kernel set is found, an error is thrown:

>>> API.kernel_set('Cassini')
Traceback (most recent call last):
    ...
TooManyKernelSets: Too many kernel sets contains 'Cassini' in their names:
    - Cassini Huygens
    - SPICE Class -- CASSINI Remote Sensing Lesson Kernels

Request bodies

List all bodies contains in kernel set (by name or id):

>>> API.bodies('Cassini Huygens')
[<BodyData> CASSINI (id: -82), ...]

Request frames

List all frames contains in kernel set (by name or id):

>>> API.frames('Cassini Huygens')
[<FrameData> CASSINI_SATURN_SKR4N_LOCK (id: -82982), ...]

Request instruments

List all instruments contains in kernel set (by name or id):

>>> API.instruments('Cassini Huygens')
[<InstrumentData> CASSINI_CIRS_RAD (id: -82898), ...]

API class

class webgeocalc.api.Api(url='https://wgc2.jpl.nasa.gov:8443/webgeocalc/api')[source]

Bases: object

WebGeoCalc API object.

Parameters:url (str, optional) – API root URL. Default: https://wgc2.jpl.nasa.gov:8443/webgeocalc/api
get(url)[source]

Generic GET request on the API.

Parameters:url (str) – Request url with GET method.
Returns:Parsed json API response. See: read().
Return type:list or tuple
Raises:requests.reponse.HTMLError – If HTML error is thrown by the API (HTML code not equal 200)

Example

>>> API.get('/kernel-sets')
[<KernelSetDetails> Solar System Kernels (id: 1), ...]
post(url, payload)[source]

Generic POST request on the API.

Parameters:
  • url (str) – Request url with POST method.
  • payload (dict) – Calculation payload data.
Returns:

Parsed json API response. See: read().

Return type:

list or tuple

Raises:

requests.reponse.HTMLError – If HTML error is thrown by the API (HTML code not equal 200)

Example

>>> API.post('/calculation/new', payload=calculation_payload)  
('0788aba2-d4e5-4028-9ef1-4867ad5385e0', 'COMPLETE', 0)
read(json)[source]

Read content from API JSON reponse.

Parameters:

json (dict) – API JSON response

Returns:

Parsed content of the JSON API response.

If the response contents resultType and items keys, then return type will be:

[Result objects: webgeocalc.types.ResultType]

If response contents result, then return type will be:

(Calculation id: str, Phase: str, Progress: int)

If the response contents columns and rows, then return type will be:

(Columns: [webgeocalc.types.ColumnResult],

Results rows: [[int, float or str], …])

Else an error is thrown.

Return type:

list or tuple

Raises:
  • APIError – If the API status is not OK.
  • APIReponseError – If the format of the API response is unexpected.
kernel_sets()[source]

Get list of all kernel sets available on the webgeocalc server.

GET: /kernel-sets

Returns:List of kernel sets.
Return type:[webgeocalc.types.KernelSetDetails]
kernel_set(kernel_set)[source]

Get kernel set by caption name or kernel set id.

Parameters:kernel_set (str or int) – Kernel set name or id.
Returns:Kernel set details object.
Return type:webgeocalc.types.KernelSetDetails
kernel_set_id(kernel_set)[source]

Extract kernel set id based on id, name or object.

Parameters:kernel_set (str, int or webgeocalc.types.KernelSetDetails) – Kernel sets name, id or object.
Returns:Kernel set id.
Return type:int
bodies(kernel_set)[source]

Get list of bodies available in a kernel set.

GET: /kernel-set/{kernelSetId}/bodies

Parameters:kernel_set (str, int or webgeocalc.types.KernelSetDetails) – Kernel sets name, id or object.
Returns:List of bodies in the requested kernel set.
Return type:[webgeocalc.types.BodyData]
frames(kernel_set)[source]

Get list of frames available in a kernel set.

GET: /kernel-set/{kernelSetId}/frames

Parameters:kernel_set (str, int or webgeocalc.types.KernelSetDetails) – Kernel sets name, id or object.
Returns:List of frames in the requested kernel set.
Return type:[webgeocalc.types.FrameData]
instruments(kernel_set)[source]

Get list of instruments available in a kernel set.

GET: /kernel-set/{kernelSetId}/instruments

Parameters:kernel_set (str, int or webgeocalc.types.KernelSetDetails) – Kernel sets name, id or object.
Returns:List of instruments in the requested kernel set.
Return type:[webgeocalc.types.InstrumentData]
new_calculation(payload)[source]

Starts a new calculation.

POST: /calculation/new

Parameters:payload (dict) – Calculation payload.
Returns:Tuple of the calculation status: (calculation-id, phase, progress) See: read().
Return type:(str, str, int)

Example

>>> API.calculation_new(calculation_payload)  
('0788aba2-d4e5-4028-9ef1-4867ad5385e0', 'LOADING_KERNELS', 0)

Warning

The progress attribute is not relevant when phase is COMPLETE.

In the next release, the API responses may contain progress only when applicable.

status_calculation(id)[source]

Gets the status of a calculation.

GET: /calculation/{id}

Parameters:id (str) – Calculation id.
Returns:Tuple of the calculation status: (calculation-id, phase, progress) See: read().
Return type:(str, str, int)

Example

>>> API.status_calculation('0788aba2-d4e5-4028-9ef1-4867ad5385e0')  # noqa: E501  
('0788aba2-d4e5-4028-9ef1-4867ad5385e0', 'COMPLETE', 0)

Warning

The progress attribute is not relevant when phase is COMPLETE.

In the next release, the API responses may contain progress only when applicable.

results_calculation(id)[source]

Gets the results of a complete calculation.

GET: /calculation/{id}/results

Parameters:id (str) – Calculation id.
Returns:Tuple of calculation results: (columns, rows) See: read().
Return type:([webgeocalc.types.ColumnResult], [[int, float or str], …])

Example

>>> API.results_calculation('0788aba2-d4e5-4028-9ef1-4867ad5385e0')  # noqa: E501  
([<ColumnResult> UTC calendar date, ...], [['2000-01-01 00:00:00.000000 UTC', ...], [...]])