Basic usage of WebGeoCalc API

The API variable in webgeocalc provide an access to the WebGeoCalc API:

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

The default API endpoint can be defined with the WGC_URL global environment variable. If it is not present, the API will fallback to the JPL (wgc2) endpoint (as shown above).

You can also use the ESA webgeocalc server:

>>> from webgeocalc import ESA_API
>>> ESA_API.url
'http://spice.esac.esa.int/webgeocalc/api'

Or any 3rd party WGC endpoint:

>>> from webgeocalc import Api
>>> obs_api = Api('https://wgc.obspm.fr/webgeocalc/api')
>>> obs_api.url
'https://wgc.obspm.fr/webgeocalc/api'

Metadata

Some metadata are public provided on the home page of the API and can be retrieved directly as items:

>>> API['description']
'WGC2 -- a WebGeocalc Server with enabled API at NAIF, JPL'

>>> API['version']
'2.8.2'

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='')

Bases: object

WebGeoCalc API object.

Parameters:

url (str, optional) – API root URL. Use WGC_URL global environment variable if present. If not, fallback on JPL_URL: https://wgc2.jpl.nasa.gov:8443/webgeocalc/api

get(url)

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.response.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)

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.response.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')

static read(json)

Read content from API JSON response.

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)

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.

• APIResponseError – If the format of the API response is unexpected.

kernel_sets()

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)

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)

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)

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)

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)

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)

Starts a new calculation.

POST: /calculation/new

Parameters:

payload (dict) – Calculation payload.

Returns:

Tuple of the calculation phase: (calculation-id, phase) See: read().

Return type:

(str, str)

Example

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

phase_calculation(calculation_id)

Gets the phase of a calculation.

GET: /calculation/{id}

Parameters:

calculation_id (str) – Calculation id.

Returns:

Tuple of the calculation phase: (calculation-id, phase) See: read().

Return type:

(str, str)

Example

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

cancel_calculation(calculation_id)

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

GET: /calculation/{id}/cancel

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

Parameters:

calculation_id (str) – Calculation id.

Returns:

Tuple of the calculation phase: (calculation-id, phase) See: read().

Return type:

(str, str)

Example

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

results_calculation(calculation_id)

Gets the results of a complete calculation.

GET: /calculation/{id}/results

Parameters:

calculation_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', ...], [...]])

property metadata

API metadata.