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
anditems
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
androws
, 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 notOK
.APIReponseError
– If the format of the API response is unexpected.
- (Columns: [
-
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 setid
.Parameters: kernel_set (str or int) – Kernel set name
orid
.Returns: Kernel set details object. Return type: webgeocalc.types.KernelSetDetails
-
kernel_set_id
(kernel_set)[source]¶ Extract kernel set
id
based onid
,name
or object.Parameters: kernel_set (str, int or webgeocalc.types.KernelSetDetails
) – Kernel setsname
,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 setsname
,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 setsname
,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 setsname
,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 whenphase
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 whenphase
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', ...], [...]])
-