/
vessels.py
183 lines (146 loc) · 9.1 KB
/
vessels.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
"""
Try me out in your browser:
[](https://mybinder.org/v2/gh/VorTECHsa/python-sdk/master?filepath=docs%2Fexamples%2Ftry_me_out%2Fvessels.ipynb)
"""
from typing import Any, Dict, List, Union
from vortexasdk.api.id import ID
from vortexasdk.endpoints.endpoints import VESSELS_REFERENCE
from vortexasdk.endpoints.vessels_result import VesselsResult
from vortexasdk.operations import Reference, Search
from vortexasdk.utils import convert_to_list
class Vessels(Reference, Search):
"""Vessels endpoint."""
def __init__(self):
"""Instantiate endpoint using reference endpoint."""
Reference.__init__(self, VESSELS_REFERENCE)
Search.__init__(self, VESSELS_REFERENCE)
def load_all(self) -> VesselsResult:
"""Load all vessels."""
return self.search()
def search(
self,
term: Union[str, List[str]] = None,
ids: Union[str, List[str]] = None,
vessel_classes: Union[str, List[str]] = None,
vessel_product_types: Union[ID, List[ID]] = None,
vessel_scrubbers: str = "disabled",
exact_term_match: bool = False,
) -> VesselsResult:
"""
Find all vessels matching given search arguments. Search arguments are combined in an AND manner.
# Arguments
term: The name(s) (or partial name(s)) of a vessel we'd like to search
ids: ID or IDs of vessels we'd like to search
vessel_classes: vessel_class (or list of vessel classes) we'd like to search. Each vessel class must be one of `"oil_coastal", "oil_intermediate", "oil_flexi", "oil_handysize", "oil_mr1","oil_handymax", "oil_mr2", "oil_panamax", "oil_lr1", "oil_aframax", "oil_lr2", "oil_suezmax","oil_lr3", "oil_vlcc","lpg_coasters", "lpg_handysize", "lpg_mgc", "lpg_lgc", "lpg_vlgc", "lpg_vlec", "lng_small_scale_lng", "lng_mid_scale_lng", "lng_two_stroke", "lng_tfde_dfde", "lng_steam", "lng_ssd", "lng_q_flex", "lng_q_max", "oil_coastal", "oil_specialised", "oil_handysize_mr1", "oil_handymax_mr2", "oil_panamax_lr1", "oil_aframax_lr2", "oil_suezmax_lr3", "oil_vlcc","lpg_sgc", "lpg_mgc", "lpg_lgc", "lpg_vlgc_vlec","lng_small_scale_lng", "lng_mid_scale_lng","lng_conventional_lng", "lng_q_fleet", "oil", "lpg", "lng",`. Refer to [VortexaAPI Vessel Entities](https://docs.vortexa.com/reference/intro-vessel-entities) for the most up-to-date list of vessel classes.
vessel_product_types: A product ID, or list of product IDs to filter on, searching vessels _currently_ carrying these products.
vessel_scrubbers: An optional filter to filter on vessels with or without scrubbers.
To disable the filter (the default behaviour), enter 'disabled'.
To only include vessels with scrubbers, enter 'inc'.
To exclude vessels with scrubbers, enter 'exc'.
exact_term_match: Search on only exact term matches, or allow similar matches.
e.g. When searching for "Ocean" with `exact_term_match=False`, then the SDK will yield vessels named
['Ocean', 'Ocean Wisdom', ...] etc. When `exact_term_match=True`,
the SDK will only yield the vessel named `Ocean`.
# Returns
List of vessels matching the search arguments.
# Examples
- Let's find all the VLCCs with 'ocean' in their name, or related names.
```python
>>> from vortexasdk import Vessels
>>> vessels_df = Vessels().search(vessel_classes='oil_vlcc', term='ocean').to_df(columns=['name', 'imo', 'mmsi', 'related_names'])
```
| | name | imo | mmsi | related_names |
|---:|:-------------|--------:|----------:|:--------------------------|
| 0 | OCEANIS | 9532757 | 241089000 | ['OCEANIS'] |
| 1 | AEGEAN | 9732553 | 205761000 | ['GENER8 OCEANUS'] |
| 2 | OCEANIA | 9246633 | 205753000 | ['OCEANIA'| 'TI OCEANIA'] |
| 3 | ENEOS OCEAN | 9662875 | 432986000 | ['ENEOS OCEAN'] |
| 4 | OCEAN LILY | 9284960 | 477178100 | ['OCEAN LILY'] |
| 5 | SHINYO OCEAN | 9197868 | 636019316 | ['SHINYO OCEAN'] |
| 6 | NASHA | 9079107 | 370497000 | ['OCEANIC'] |
| 7 | HUMANITY | 9180281 | 422204700 | ['OCEAN NYMPH'] |
Note the `term` search also looks for vessels with matching `related_names`
- Let's find all the vessels currently carrying Crude.
```python
>>> from vortexasdk import Vessels, Products
>>> crude = [p.id for p in Products().search(term="crude").to_list() if 'group' in p.layer]
>>> vessels_df = Vessels().search(vessel_product_types=crude).to_df()
```
# Further Documentation
[VortexaAPI Vessel Reference](https://docs.vortexa.com/reference/POST/reference/vessels)
"""
api_params: Dict[str, Any] = {
"term": [str(e) for e in convert_to_list(term)],
"ids": convert_to_list(ids),
"vessel_product_types": convert_to_list(vessel_product_types),
"vessel_classes": [
v.lower() for v in convert_to_list(vessel_classes)
],
"vessel_scrubbers": vessel_scrubbers,
}
response = super().search_with_client(
exact_term_match=exact_term_match, **api_params
)
return VesselsResult(
records=response["data"], reference=response["reference"]
)
def reference(self, id: ID) -> Dict:
"""
Perform a vessel lookup.
# Arguments
id: Vessel ID to lookup
# Returns
Vessel record matching the ID
# Further Documentation:
[VortexaAPI Vessel Reference](https://docs.vortexa.com/reference/GET/reference/vessels/%7Bid%7D)
"""
return super().reference(id)
AVAILABLE_VESSEL_CLASSES = [
"oil_coastal",
"oil_intermediate",
"oil_flexi",
"oil_handysize",
"oil_mr1",
"oil_handymax",
"oil_mr2",
"oil_panamax",
"oil_lr1",
"oil_aframax",
"oil_lr2",
"oil_suezmax",
"oil_lr3",
"oil_vlcc",
"lpg_coasters",
"lpg_handysize",
"lpg_mgc",
"lpg_lgc",
"lpg_vlgc",
"lpg_vlec",
"lng_small_scale_lng",
"lng_mid_scale_lng",
"lng_two_stroke",
"lng_tfde_dfde",
"lng_steam",
"lng_ssd",
"lng_q_flex",
"lng_q_max",
"oil_coastal",
"oil_specialised",
"oil_handysize_mr1",
"oil_handymax_mr2",
"oil_panamax_lr1",
"oil_aframax_lr2",
"oil_suezmax_lr3",
"oil_vlcc",
"lpg_sgc",
"lpg_mgc",
"lpg_lgc",
"lpg_vlgc_vlec",
"lng_small_scale_lng",
"lng_mid_scale_lng",
"lng_conventional_lng",
"lng_q_fleet",
"oil",
"lpg",
"lng",
]