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.2.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='')[source]¶ Bases:
object
WebGeoCalc API object.
- Parameters
url (str, optional) – API root URL. Use
WGC_URL
global environment variable if present. If not, fallback onJPL_URL
: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')
-
static
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)
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.
- (Columns: [
- 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 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 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)[source]¶ 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)[source]¶ Cancels a previously requested calculation, should this not be completed, or its results..
GET: /calculation/{id}/cancel
Calculations that have been already
DISPATCHED
, previouslyCANCELLED
or that haveEXPIRED
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)[source]¶ 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.