Skip to content

Package Documentation

Voyages API Package.

Classes:

Name Description
VoyagesAPI

Represents Signal's Voyages API.
Voyage

Represents a Voyage of a vessel.
VoyageEvent

Represents an Event associated with a Voyage.
VoyageEventDetail

Represents details about a VoyageEvent.
VoyageGeo

Represents a geo asset object associated with a voyage.
VoyagesFlat

Voyages with additional information in flat format.
VoyagesIncremental

Incremental voyages, including token for next request.
VoyagesCondensed

Voyages with additional information in condensed format.
Vessel

Vessel name and IMO
VesselFilter

Vessel Filter object
VesselClass

Vessel class
VesselClassFilter

Vessel class Filter object
VesselType

Vessel type object
VesselTypeFilter

Vessel type Filter object

Vessel dataclass

Vessels.

Attributes:

Name Type Description
imo int

The vessel imo.
vessel_name str

The vessel name.
Source code in signal_ocean/voyages/models.py 
 8
 9
10
11
12
13
14
15
16
17
18
@dataclass(frozen=True, eq=False)
class Vessel:
    """Vessels.

    Attributes:
        imo: The vessel imo.
        vessel_name: The vessel name.
    """

    imo: int
    vessel_name: str

VesselClass dataclass

A group of vessels of similar characteristics, i.e. Aframax, Panamax, etc.

Attributes:

Name Type Description
vessel_class_id int

The vessel class ID.
vessel_class_name str

The vessel class name.
vessel_type_id int

The vessel type ID.
vessel_type str

The vessel type
Source code in signal_ocean/voyages/models.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
@dataclass(frozen=True, eq=False)
class VesselClass:
    """A group of vessels of similar characteristics, i.e. Aframax, Panamax, etc.

    Attributes:
        vessel_class_id: The vessel class ID.
        vessel_class_name: The vessel class name.
        vessel_type_id: The vessel type ID.
        vessel_type: The vessel type
    """

    vessel_class_id: int
    vessel_class_name: str
    vessel_type_id: int
    vessel_type: str

VesselClassFilter dataclass

A filter used to find specific vessel classes.

Attributes:

Name Type Description
name_like Optional[str]

Used to find vessel classes by name. When specified, vessel classes whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.
Source code in signal_ocean/voyages/models.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@dataclass(eq=False)
class VesselClassFilter:
    """A filter used to find specific vessel classes.

    Attributes:
        name_like: Used to find vessel classes by name. When specified, vessel
            classes whose names partially match (contain) the attribute's value
            will be returned. Matching is case-insensitive.
    """

    name_like: Optional[str] = None

    def _apply(
        self, vessel_classes: Iterable[VesselClass]
    ) -> Iterable[VesselClass]:
        return filter(self.__does_class_match, vessel_classes)

    def __does_class_match(self, vessel_class: VesselClass) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, vessel_class.vessel_class_name
        )

VesselFilter dataclass

A filter used to find specific vessels.

Attributes:

Name Type Description
name_like Optional[str]

Used to find vessel by name. When specified, vessel name whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.
Source code in signal_ocean/voyages/models.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@dataclass(eq=False)
class VesselFilter:
    """A filter used to find specific vessels.

    Attributes:
        name_like: Used to find vessel by name. When specified, vessel
            name whose names partially match (contain) the attribute's value
            will be returned. Matching is case-insensitive.
    """

    name_like: Optional[str] = None

    def _apply(self, vessels: Iterable[Vessel]) -> Iterable[Vessel]:
        return filter(self.__does_class_match, vessels)

    def __does_class_match(self, vessel: Vessel) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, vessel.vessel_name
        )

VesselType dataclass

Type of vessel used for transport.

Attributes:

Name Type Description
vessel_type_id int

The vessel type ID.
vessel_type str

The vessel type name.
Source code in signal_ocean/voyages/models.py 
82
83
84
85
86
87
88
89
90
91
92
@dataclass(frozen=True, eq=False)
class VesselType:
    """Type of vessel used for transport.

    Attributes:
        vessel_type_id: The vessel type ID.
        vessel_type: The vessel type name.
    """

    vessel_type_id: int
    vessel_type: str

VesselTypeFilter dataclass

A filter used to find specific vessel types.

Attributes:

Name Type Description
name_like Optional[str]

Used to find vessel types by name. When specified, vessel types whose names partially match (contain) the attribute's value will be returned. Matching is case-insensitive.
Source code in signal_ocean/voyages/models.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@dataclass(eq=False)
class VesselTypeFilter:
    """A filter used to find specific vessel types.

    Attributes:
        name_like: Used to find vessel types by name. When specified, vessel
            types whose names partially match (contain) the attribute's value
            will be returned. Matching is case-insensitive.
    """

    name_like: Optional[str] = None

    def _apply(
        self, vessel_types: Iterable[VesselType]
    ) -> Iterable[VesselType]:
        return filter(self.__does_type_match, vessel_types)

    def __does_type_match(self, vessel_type: VesselType) -> bool:
        return not self.name_like or contains_caseless(
            self.name_like, vessel_type.vessel_type
        )

Voyage dataclass

Contains information about a single voyage of a vessel.

Attributes:

Name Type Description
imo Optional[int]

A seven-digits number that uniquely identifies a ship and does not change when the ship's owner, country of registry or name of the vessel changes.
voyage_number Optional[int]

Numeric, a counter of the voyages for the same IMO.
vessel_type_id Optional[int]

Numeric ID corresponding to the different values of the VesselType field. 1-> Tanker, 3-> Dry, 4 -> Containers, 5 ->LNG (Liquified Natural gas) , 6-> LPG (Liquified Petroleum Gas).
vessel_class_id Optional[int]

Numeric ID corresponding to the different vessel classes of a certain vessel type.
vessel_status_id Optional[int]

Numeric ID that takes the following values 1 -> Voyage, 2 -> Breaking, 3 -> Domestic Trade, 4-> FPSO, 5-> FPSO Conversion, 6-> Inactive, 7-> Storage Vessel, 9-> Conversion.
deadweight Optional[int]

Numeric, measured in tonnes [t], often shortened as DWT, denotes the total carrying capacity of the vessel including cargo, ballast water, stores, provisions, crew and so on.
commercial_operator_id Optional[int]

Numeric ID corresponding to the maritime company that manages the vessel commercially.
deleted Optional[bool]

Boolean. This will be true if the voyage has been deleted from our database.
events Optional[Tuple[VoyageEvent, ...]]

The events that took place during the voyage.
id Optional[str]

String. Uniquely identifies the voyage.
horizon_id Optional[int]

Numeric ID that takes the following values Unknown (0), Historic (1), Historical (1), Current (2), Future (3)
horizon Optional[str]

String. It can take "Historic", "Current" or "Future" values, depending on whether the voyage event is in the past (StartDate and EndDate both in the past), is current (StartDate in the past and EndDate in the future) or future (both StartDate and EndDate in the future). Note: the notions of "past", "current" and "future" are not derived by the current date, but by the comparison between the voyage dates and the latest received AIS for that specific vessel.
latest_received_ais Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The most recent AIS update for the vessel. It is used to define the horizon of a voyage and its events.
vessel_name Optional[str]

The vessel name corresponding to that IMO at the time of that voyage.
pit_vessel_name Optional[str]

String, The vessel name corresponding to that IMO at the time of that voyage (if different than VesselName)
vessel_type Optional[str]

Description of the type of the vessel, based on the carried cargo. Main categories are Tankers, Dry (bulk carriers), Containers, LNG and LPG.
vessel_class Optional[str]

Name of the vessel class the vessel belongs to. Assignment of a vessel to a certain VesselClass is based on the VesselType and the value of its Deadweight (if Tanker or Dry), its LiquidCap (if LNG/LPG) or its TEU (if Containers). For example, an Aframax is a Tanker vessel with Deadweight within the range 82kt - 125kt, while a Capesize is a Dry vessel with Deadweight within the range 120kt-220kt. LR2 are defined as Aframax, as only Deadweight is used to define vessel classes.
trade Optional[str]

Additional attribute used to specify a Tanker vessel with finer granularity. It is derived by the last cargo carried by the vessel at the time of query. For example, an LR2 with fueloil as last cargo has VesselClass=Aframax and Trade=Product.
trade_id Optional[int]

For Tankers only. Numeric ID that takes the following values 1 -> Crude, 2 -> Product, 3 -> Chemical.
vessel_status Optional[str]

String identifying the status of a vessel. The active and most common status is the "Voyage" one, the one in which the vessel continuously sails and performs operations. The other statuses are used for specific purposes different than voyage.
deadweight Optional[int]

Numeric, measured in tonnes [t], often shortened as DWT, denotes the total carrying capacity of the vessel including cargo, ballast water, stores, provisions, crew and so on.
year_built Optional[int]

Numeric, year format, the year the vessel was built.
commercial_operator Optional[str]

Name of the maritime company that manages the vessel commercially.
start_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The beginning of the specific voyage. The start of a voyage is set as the end of the previous voyage (if existing) or the first received AIS (for a new building). Voyages are consecutive and with no breaks in between, therefore a vessel is always in a voyage.
first_load_arrival_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The time of arrival for the first load in the voyage. Indicates the transition from Ballast to Laden.
end_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The end of the specific voyage. The end of a voyage is set as the sailing date (or completion date) from the port where the vessel discharged for the last time.
charterer_id Optional[int]

Numeric ID corresponding to the company reported as charterer in at least one of the fixtures.
charterer Optional[str]

String, name of the company reported as charterer in at least one of the fixtures.
rate Optional[float]

Numeric, indicates the rate reported in at least one of the fixtures. If lump sum, the rate is reported in USD.
rate_type Optional[str]

String, indicates the type of rate reported in at least one of the fixtures. Main types are "WS" for World Scale or "LS" for Lump Sum.
ballast_bonus Optional[float]

.
ballast_bonus_type Optional[str]

.
cargo_type_id Optional[int]

Numeric ID corresponding to the type of cargo the vessel carries in this voyage. For example 19-> Crude Oil, 16->Fueloil, 9-> Naphtha, 135-> Unleaded Motor Spirit, 12-> Gasoil.
cargo_type Optional[str]

String, it corresponds to the estimated cargo type the vessel carries according to the specific voyage, AIS information, jetty the vessel may have visited or information coming from market reports.
cargo_type_source_id Optional[int]

Numeric ID corresponding to the type of CargoSubType source. 0 -> None, 2 -> MarketInfo, 3 -> Lineup, 8 -> EstimatedLow, 9 -> EstimatedMedium, 10 -> EstimatedHigh, 20 -> PrivateInfo.
cargo_type_source Optional[str]

String, it specifies the source of CargoType and CargoGroup. If market reports are available this filed takes value "MarketInfo". If no market reports are available for this voyage, the cargo is estimated based on AIS and visited jetties. Market info are considered more accurate and reliable, whenever available.
cargo_sub_type_id Optional[int]

Numeric ID corresponding to the type of cargo the vessel carries in the given voyage at taxonomy level 0, for example 97-> High Sulphur Gasoil. CargoSubTypes are a subcategory of CargoTypes and the most detailed level of information for the cargo that is onboard. In the case of the CargoType Crude Oil, CargoSubTypes represent specific grades, like Basrah Light.
cargo_sub_type Optional[str]

String, corresponds to the taxonomy 0 cargo type the vessel carries in the specific voyage. It is a product of all available information, including current and historical voyage information, geofencing and market data. CargoSubTypes are a subcategory of CargoTypes and the most detailed level of information for the cargo that is onboard. In the case of the CargoType Crude Oil, CargoSubTypes represent specific grades, like Basrah Light.
cargo_sub_type_source_id Optional[int]

Numeric ID corresponding to the type of CargoSubType source. 0 -> None, 2 -> MarketInfo, 3 -> Lineup, 8 -> EstimatedLow, 9 -> EstimatedMedium, 10 -> EstimatedHigh, 20 -> PrivateInfo.
cargo_sub_type_source Optional[str]

String, it specifies the source of CargoSubType. The source will be ""Lineup"" if the selection of CargoSubType is based on Lineup info, ""MarketInfo"" if the selection of CargoSubType is based on other market data like fixtures or tonnage lists, ""PrivateInfo"" if it is based on your private info and ""Estimated(Low/Medium/High, providing the different confidence levels of our estimation)"" if it is based on our proprietary sequential and hierarchical CargoTracking model that also uses current/historical voyage data as input, plus a specific cargo layer of our geofencing data structure.
cargo_group_id Optional[int]

Numeric ID corresponding to the high-level cargo the vessel carries in this voyage, therefore called cargo group. For example 130000->Dirty, 120000-> Clean.
cargo_group Optional[str]

String, it corresponds to the estimated high-level cargo the vessel carries in this voyage, according to AIS information and jetties the vessel may have visited or information coming from market reports.
cargo_sub_group_id Optional[int]

Numeric ID corresponding to the type of cargo the vessel carries in the given voyage at taxonomy level 2. For example 132000-> Crude. CargoSubGroups are a subcategory of CargoGroups and a parent category of CargoTypes, so the second-highest level of information after CargoGroups.
cargo_sub_group Optional[str]

String, corresponds to the taxonomy level 2 cargo type the vessel carries in the specific voyage. It is a product of all available information, including current and historical voyage information, geofencing and market data. CargoSubGroups are a subcategory of CargoGroups and a parent category of CargoTypes, so the second-highest level of information after CargoGroups.
cargo_sub_group_source_id Optional[int]

Numeric ID corresponding to the type of CargoSubGroup source 0 -> None, 2 -> MarketInfo, 3 -> Lineup, 8 -> EstimatedLow, 9 -> EstimatedMedium, 10 -> EstimatedHigh, 20 -> PrivateInfo.
cargo_sub_group_source Optional[str]

String, it specifies the source of CargoSubGroup. The source will be ""Lineup"" if the selection of CargoSubGroup is based on Lineup info, ""MarketInfo"" if the selection of CargoSubGroup is based on other market data, ""PrivateInfo"" if it is based on private info and ""Estimated(Low/Medium/High, providing the different confidence levels of our estimation)"" if it is based on our proprietary sequential and hierarchical CargoTracking model that also uses current/historical voyage data as input, plus a specific cargo layer of our geofencing data structure.
quantity Optional[float]

Numeric, measured in kilotonnes [kt]. It is the cargo quantity reported in at least one of the market reports.
quantity_unit_id Optional[int]

Numeric ID corresponding to the Quantity unit 1 -> MetricTonnes, 2 -> CubicMeters.
quantity_unit Optional[str]

String corresponding to the unit type of the field Quantity (MetricTonnes for Tanker, LPG and Dry, CubicMeters for LNG).
quantity_in_barrels Optional[int]

Numeric, the quantity measured in barrels, applicable for Tanker vessels.
quantity_source_id Optional[int]

"Numeric ID corresponding to the type of Quantity source 0 -> None, 1 -> Estimated, 2 -> MarketInfo, 3 -> Lineup, 20 -> PrivateInfo.
quantity_source Optional[str]

String, it specifies the source of Quantity. If market reports are available this field takes value "MarketInfo". If no market reports are available for this voyage, the quantity is estimated. Market info is considered more accurate and reliable, whenever available.
cubic_source Optional[str]

Numeric, measured in cubic meters [cbm] denotes the carrying capacity of Gas vessels (LNG, LPG). For tankers it is the volume of cargo tanks.
laycan_from Optional[datetime]

Date, format YYYY-MM-DD indicates the earliest reported Laycan From (latest day of cancellation) across all fixtures.
laycan_to Optional[datetime]

Date, format YYYY-MM-DD indicates the latest reported Laycan To (latest day of cancellation) across all fixtures.
fixture_status_id Optional[int]

Numeric ID corresponding to the different values of the FixtureStatus field. 0-> OnSubs, 1-> FullyFixed, 2 -> Failed, 3 -> Cancelled , 4-> Available, 5-> PossFixed, -2 -> NotSet, -1 -> Unknown.
fixture_status Optional[str]

String denoting the commercial status of a fixture if explicitly mentioned, like ffxd for fully fixed or subs for on subs.
fixture_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Details the date of the first fixture reporting the specific voyage.
fixture_is_coa Optional[bool]

Boolean. Value is true if "COA" (Contract of Affreightment) is explicitly reported in at least one of the fixtures relative to the specific voyage.
fixture_is_hold Optional[bool]

Boolean. Value is true if "Hold" is explicitly reported in at least one of the fixtures relative to the specific voyage.
is_implied_by_ais Optional[bool]

Boolean. This will be true if the voyage is implied from AIS.
has_manual_entries Optional[bool]

Boolean. True if the fused matched fixture on a voyage contains at least one (partial or full) fixture input by a user. It indicates that there is additional information input by a user in addition to what received through market reports only.
ballast_distance Optional[float]

Numeric. Travelled distance in nautical miles between the last discharge port of the previous voyage and the first load port of the current voyage. It is computed based on AIS data. It includes the whole period between the two port calls and non operational stops as well. Accuracy depends on AIS coverage.
predicted_ballast_distance Optional[float]

Numeric, Computed distance of the ballast leg based on our distance model, in nautical miles. For current voyage, when vessel is ballast, it is the remaining distance between the vessel position and the first load port. For historical legs PredictedBallastDistance is empty.
laden_distance Optional[float]

Numeric. Travelled distance in nautical miles between the first load port and the last discharge port of the same voyage. It is computed based on AIS data. Accuracy depends on AIS coverage.
predicted_laden_distance Optional[float]

Numeric, Computed distance of the laden leg based on our distance model, in nautical miles. For current voyage, when vessel is laden, it is the remaining distance between the vessel position and the last discharge port. For historical legs PredictedLadenDistance is empty.
suez_crossing Optional[str]

String, indicates whether the vessel crossed the Suez canal during the voyage. Depending on the leg, it can take "Laden", "Ballast" or "Both" as values.
panama_crossing Optional[str]

String, indicates whether the vessel crossed the Panama canal during the voyage. Depending on the leg, it can take "Laden", "Ballast" or "Both" as values.
canakkale_crossing Optional[str]

String, indicates whether the vessel crossed the Canakkale strait during the voyage. Depending on the leg, it can take "Laden", "Ballast" or "Both" as values.
bosporus_crossing Optional[str]

String, indicates whether the vessel crossed the Bosporus strait during the voyage. Depending on the leg, it can take "Laden", "Ballast" or "Both" as values.
Source code in signal_ocean/voyages/models.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
@dataclass(frozen=True)
class Voyage:
    """Contains information about a single voyage of a vessel.

    Attributes:
        imo: A seven-digits number that uniquely identifies a ship and does not
            change when the ship's owner, country of registry or name of the
            vessel changes.
        voyage_number: Numeric, a counter of the voyages for the same IMO.
        vessel_type_id: Numeric ID corresponding to the different values of the
            VesselType field.  1-> Tanker, 3-> Dry, 4 -> Containers, 5 ->LNG
            (Liquified Natural gas) , 6-> LPG (Liquified Petroleum Gas).
        vessel_class_id: Numeric ID corresponding to the different vessel
            classes of a certain vessel type.
        vessel_status_id: Numeric ID that takes the following values  1 ->
            Voyage, 2 -> Breaking, 3 -> Domestic Trade, 4-> FPSO, 5-> FPSO
            Conversion, 6-> Inactive, 7-> Storage Vessel, 9-> Conversion.
        deadweight: Numeric, measured in tonnes [t], often shortened as DWT,
            denotes the total carrying capacity of the vessel including cargo,
            ballast water, stores, provisions, crew and so on.
        commercial_operator_id: Numeric ID corresponding to the maritime
            company that manages the vessel commercially.
        deleted: Boolean. This will be true if the voyage has been deleted from
            our database.
        events: The events that took place during the voyage.
        id: String. Uniquely identifies the voyage.
        horizon_id: Numeric ID that takes the following values Unknown (0),
            Historic (1), Historical (1), Current (2), Future (3)
        horizon: String. It can take "Historic", "Current" or "Future" values,
            depending on whether the voyage event is in the past (StartDate and
            EndDate both in the past), is current (StartDate in the past and
            EndDate in the future) or future (both StartDate and EndDate in the
            future). Note: the notions of "past", "current" and "future" are
            not derived by the current date, but by the comparison between the
            voyage dates and the latest received AIS for that specific vessel.
        latest_received_ais: Date, format YYYY-MM-DD HH:MM:SS. The most recent
            AIS update for the vessel. It is used to define the horizon of a
            voyage and its events.
        vessel_name: The vessel name corresponding to that IMO at the time of
            that voyage.
        pit_vessel_name: String, The vessel name corresponding to that IMO at
            the time of that voyage (if different than VesselName)
        vessel_type: Description of the type of the vessel, based on the
            carried cargo. Main categories are Tankers, Dry (bulk carriers),
            Containers, LNG and LPG.
        vessel_class: Name of the vessel class the vessel belongs to.
            Assignment of a vessel to a certain VesselClass is based on the
            VesselType and the value of its Deadweight (if Tanker or Dry), its
            LiquidCap (if LNG/LPG) or its TEU (if Containers).   For example,
            an Aframax is a Tanker vessel with Deadweight within the range 82kt
            - 125kt, while a Capesize is a Dry vessel with Deadweight within
            the range 120kt-220kt. LR2 are defined as Aframax, as only
            Deadweight is used to define vessel classes.
        trade: Additional attribute used to specify a Tanker vessel with finer
            granularity. It is derived by the last cargo carried by the vessel
            at the time of query.  For example, an LR2 with fueloil as last
            cargo has VesselClass=Aframax and Trade=Product.
        trade_id: For Tankers only. Numeric ID that takes the following values
            1 -> Crude, 2 -> Product, 3 -> Chemical.
        vessel_status: String identifying the status of a vessel. The active
            and most common status is the "Voyage" one, the one in which the
            vessel continuously sails and performs operations. The other
            statuses are used for specific purposes different than voyage.
        deadweight: Numeric, measured in tonnes [t], often shortened as DWT,
            denotes the total carrying capacity of the vessel including cargo,
            ballast water, stores, provisions, crew and so on.
        year_built: Numeric, year format, the year the vessel was built.
        commercial_operator: Name of the maritime company that manages the
            vessel commercially.
        start_date: Date, format YYYY-MM-DD HH:MM:SS. The beginning of the
            specific voyage. The start of a voyage is set as the end of the
            previous voyage (if existing) or the first received AIS (for a new
            building). Voyages are consecutive and with no breaks in between,
            therefore a vessel is always in a voyage.
        first_load_arrival_date: Date, format YYYY-MM-DD HH:MM:SS. The time
            of arrival for the first load in the voyage. Indicates the
            transition from Ballast to Laden.
        end_date: Date, format YYYY-MM-DD HH:MM:SS. The end of the specific
            voyage. The end of a voyage is set as the sailing date (or
            completion date) from the port where the vessel discharged for the
            last time.
        charterer_id: Numeric ID corresponding to the company reported as
            charterer in at least one of the fixtures.
        charterer: String, name of the company reported as charterer in at
            least one of the fixtures.
        rate: Numeric, indicates the rate reported in at least one of the
            fixtures. If lump sum, the rate is reported in USD.
        rate_type: String, indicates the type of rate reported in at least one
            of the fixtures. Main types are "WS" for World Scale or "LS" for
            Lump Sum.
        ballast_bonus: .
        ballast_bonus_type: .
        cargo_type_id: Numeric ID corresponding to the type of cargo the vessel
            carries in this voyage. For example 19-> Crude Oil, 16->Fueloil,
            9-> Naphtha, 135-> Unleaded Motor Spirit, 12-> Gasoil.
        cargo_type: String, it corresponds to the estimated cargo type the
            vessel carries according to the specific voyage, AIS information,
            jetty the vessel may have visited or information coming from market
            reports.
        cargo_type_source_id: Numeric ID corresponding to the type of
            CargoSubType source. 0 -> None, 2 -> MarketInfo, 3 -> Lineup,
            8 -> EstimatedLow, 9 -> EstimatedMedium,
            10 -> EstimatedHigh, 20 -> PrivateInfo.
        cargo_type_source: String, it specifies the source of CargoType and
            CargoGroup. If market reports are available this filed takes value
            "MarketInfo". If no market reports are available for this voyage,
            the cargo is estimated based on AIS and visited jetties. Market
            info are considered more accurate and reliable, whenever available.
        cargo_sub_type_id: Numeric ID corresponding to the type of cargo the
            vessel carries in the given voyage at taxonomy level 0, for example
            97-> `High Sulphur Gasoil`. CargoSubTypes are a subcategory of
            CargoTypes and the most detailed level of information for the cargo
            that is onboard. In the case of the CargoType `Crude Oil`,
            CargoSubTypes represent specific grades, like `Basrah Light`.
        cargo_sub_type: String, corresponds to the taxonomy 0 cargo type the
            vessel carries in the specific voyage. It is a product of all
            available information, including current and historical voyage
            information, geofencing and market data. CargoSubTypes are a
            subcategory of CargoTypes and the most detailed level of
            information for the cargo that is onboard. In the case of the
            CargoType Crude Oil, CargoSubTypes represent specific grades,
            like Basrah Light.
        cargo_sub_type_source_id: Numeric ID corresponding to the type of
            CargoSubType source. 0 -> None, 2 -> MarketInfo, 3 -> Lineup,
            8 -> EstimatedLow, 9 -> EstimatedMedium, 10 -> EstimatedHigh,
            20 -> PrivateInfo.
        cargo_sub_type_source: String, it specifies the source of
            CargoSubType. The source will be ""Lineup"" if the selection of
            CargoSubType is based on Lineup info, ""MarketInfo"" if the
            selection of CargoSubType is based on other market data like
            fixtures or tonnage lists, ""PrivateInfo"" if it is based on your
            private info and ""Estimated(Low/Medium/High, providing the
            different confidence levels of our estimation)"" if it is based
            on our proprietary sequential and hierarchical CargoTracking
            model that also uses current/historical voyage data as input,
            plus a specific cargo layer of our geofencing data structure.
        cargo_group_id: Numeric ID corresponding to the high-level cargo the
            vessel carries in this voyage, therefore called cargo group. For
            example 130000->Dirty, 120000-> Clean.
        cargo_group: String, it corresponds to the estimated high-level cargo
            the vessel carries in this voyage, according to AIS information and
            jetties the vessel may have visited or information coming from
            market reports.
        cargo_sub_group_id: Numeric ID corresponding to the type of cargo the
            vessel carries in the given voyage at taxonomy level 2. For example
            132000-> Crude. CargoSubGroups are a subcategory of CargoGroups and
            a parent category of CargoTypes, so the second-highest level
            of information after CargoGroups.
        cargo_sub_group: String, corresponds to the taxonomy level 2 cargo
            type the vessel carries in the specific voyage. It is a product of
            all available information, including current and historical voyage
            information, geofencing and market data. CargoSubGroups are a
            subcategory of CargoGroups and a parent category of CargoTypes,
            so the second-highest level of information after CargoGroups.
        cargo_sub_group_source_id: Numeric ID corresponding to the type of
            CargoSubGroup source 0 -> None, 2 -> MarketInfo, 3 -> Lineup,
            8 -> EstimatedLow, 9 -> EstimatedMedium, 10 -> EstimatedHigh,
            20 -> PrivateInfo.
        cargo_sub_group_source: String, it specifies the source of
            CargoSubGroup. The source will be ""Lineup"" if the selection
            of CargoSubGroup is based on Lineup info, ""MarketInfo"" if the
            selection of CargoSubGroup is based on other market data,
            ""PrivateInfo"" if it is based on private info and
            ""Estimated(Low/Medium/High, providing the different confidence
            levels of our estimation)"" if it is based on our proprietary
            sequential and hierarchical CargoTracking model that also uses
            current/historical voyage data as input, plus a specific cargo
            layer of our geofencing data structure.
        quantity: Numeric, measured in kilotonnes [kt]. It is the cargo
            quantity reported in at least one of the market reports.
        quantity_unit_id: Numeric ID corresponding to the Quantity unit
            1 -> MetricTonnes, 2 -> CubicMeters.
        quantity_unit: String corresponding to the unit type of the field
            Quantity (MetricTonnes for Tanker, LPG and Dry, CubicMeters
            for LNG).
        quantity_in_barrels: Numeric, the quantity measured in barrels,
            applicable for Tanker vessels.
        quantity_source_id: "Numeric ID corresponding to the type of
            Quantity source 0 -> None, 1 -> Estimated, 2 -> MarketInfo,
            3 -> Lineup, 20 -> PrivateInfo.
        quantity_source: String, it specifies the source of Quantity. If market
                reports are available this field takes value "MarketInfo".
                If no market reports are available
                for this voyage, the quantity is estimated.
                Market info is considered more accurate and reliable,
                whenever available.
        cubic_source: Numeric, measured in cubic meters [cbm] denotes the
            carrying capacity of Gas vessels (LNG, LPG). For tankers it is the
            volume of cargo tanks.
        laycan_from: Date, format YYYY-MM-DD indicates the earliest reported
            Laycan From (latest day of cancellation) across all fixtures.
        laycan_to: Date, format YYYY-MM-DD indicates the latest reported Laycan
            To (latest day of cancellation) across all fixtures.
        fixture_status_id: Numeric ID corresponding to the different values of
            the FixtureStatus field.   0-> OnSubs, 1-> FullyFixed, 2 -> Failed,
            3 -> Cancelled , 4-> Available, 5-> PossFixed,
            -2 -> NotSet, -1 -> Unknown.
        fixture_status: String denoting the commercial status of a fixture if
            explicitly mentioned, like ffxd for fully fixed or subs for on
            subs.
        fixture_date: Date, format YYYY-MM-DD HH:MM:SS. Details the date of the
            first fixture reporting the specific voyage.
        fixture_is_coa: Boolean. Value is true if "COA" (Contract of
            Affreightment) is explicitly reported in at least one of the
            fixtures relative to the specific voyage.
        fixture_is_hold: Boolean. Value is true if "Hold" is explicitly
            reported in at least one of the fixtures relative to the specific
            voyage.
        is_implied_by_ais: Boolean. This will be true if the voyage is implied
            from AIS.
        has_manual_entries: Boolean. True if the fused matched fixture on a
            voyage contains at least one (partial or full) fixture input by a
            user. It indicates that there is additional information input by a
            user in addition to what received through market reports only.
        ballast_distance: Numeric. Travelled distance in nautical miles between
            the last discharge port of the previous voyage and the first load
            port of the current voyage. It is computed based on AIS data.
            It includes the whole period between the two port calls and non
            operational stops as well. Accuracy depends on AIS coverage.
        predicted_ballast_distance: Numeric, Computed distance of the ballast
            leg based on our distance model, in nautical miles. For current
            voyage, when vessel is ballast, it is the remaining distance
            between the vessel position and the first load port. For
            historical legs PredictedBallastDistance is empty.
        laden_distance: Numeric. Travelled distance in nautical miles between
            the first load port and the last discharge port of the same voyage.
            It is computed based on AIS data. Accuracy depends on AIS coverage.
        predicted_laden_distance: Numeric, Computed distance of the laden leg
            based on our distance model, in nautical miles. For current voyage,
            when vessel is laden, it is the remaining distance between the
            vessel position and the last discharge port. For historical legs
            PredictedLadenDistance is empty.
        suez_crossing: String, indicates whether the vessel crossed the Suez
            canal during the voyage. Depending on the leg, it can take
            "Laden", "Ballast" or "Both" as values.
        panama_crossing: String, indicates whether the vessel crossed the
            Panama canal during the voyage. Depending on the leg, it can take
            "Laden", "Ballast" or "Both" as values.
        canakkale_crossing: String, indicates whether the vessel crossed the
            Canakkale strait during the voyage. Depending on the leg, it can
            take "Laden", "Ballast" or "Both" as values.
        bosporus_crossing: String, indicates whether the vessel crossed the
            Bosporus strait during the voyage. Depending on the leg, it can
            take "Laden", "Ballast" or "Both" as values.
    """

    imo: Optional[int] = None
    voyage_number: Optional[int] = None
    vessel_type_id: Optional[int] = None
    vessel_class_id: Optional[int] = None
    vessel_status_id: Optional[int] = None
    commercial_operator_id: Optional[int] = None
    deleted: Optional[bool] = False
    events: Optional[Tuple[VoyageEvent, ...]] = None
    id: Optional[str] = None
    horizon_id: Optional[int] = None
    horizon: Optional[str] = None
    latest_received_ais: Optional[datetime] = None
    vessel_name: Optional[str] = None
    pit_vessel_name: Optional[str] = None
    vessel_type: Optional[str] = None
    vessel_class: Optional[str] = None
    trade: Optional[str] = None
    trade_id: Optional[int] = None
    vessel_status: Optional[str] = None
    deadweight: Optional[int] = None
    year_built: Optional[int] = None
    commercial_operator: Optional[str] = None
    start_date: Optional[datetime] = None
    first_load_arrival_date: Optional[datetime] = None
    end_date: Optional[datetime] = None
    charterer_id: Optional[int] = None
    charterer: Optional[str] = None
    rate: Optional[float] = None
    rate_type: Optional[str] = None
    ballast_bonus: Optional[float] = None
    ballast_bonus_type: Optional[str] = None
    cargo_type_id: Optional[int] = None
    cargo_type: Optional[str] = None
    cargo_type_source_id: Optional[int] = None
    cargo_type_source: Optional[str] = None
    cargo_sub_type_id: Optional[int] = None
    cargo_sub_type: Optional[str] = None
    cargo_sub_type_source_id: Optional[int] = None
    cargo_sub_type_source: Optional[str] = None
    cargo_group_id: Optional[int] = None
    cargo_group: Optional[str] = None
    cargo_sub_group_id: Optional[int] = None
    cargo_sub_group: Optional[str] = None
    cargo_sub_group_source_id: Optional[int] = None
    cargo_sub_group_source: Optional[str] = None
    quantity: Optional[float] = None
    quantity_unit_id: Optional[int] = None
    quantity_unit: Optional[str] = None
    quantity_in_barrels: Optional[int] = None
    quantity_source_id: Optional[int] = None
    quantity_source: Optional[str] = None
    cubic_size: Optional[int] = None
    laycan_from: Optional[datetime] = None
    laycan_to: Optional[datetime] = None
    fixture_status_id: Optional[int] = None
    fixture_status: Optional[str] = None
    fixture_date: Optional[datetime] = None
    fixture_is_coa: Optional[bool] = None
    fixture_is_hold: Optional[bool] = None
    is_implied_by_ais: Optional[bool] = None
    has_manual_entries: Optional[bool] = None
    ballast_distance: Optional[float] = None
    predicted_ballast_distance: Optional[float] = None
    laden_distance: Optional[float] = None
    predicted_laden_distance: Optional[float] = None
    suez_crossing: Optional[str] = None
    panama_crossing: Optional[str] = None
    canakkale_crossing: Optional[str] = None
    bosporus_crossing: Optional[str] = None

VoyageCondensed dataclass

Bases: Voyage

Contains information about a single voyage of a vessel.

Attributes:

Name Type Description
starting_port_name Optional[str]

String, name of the port in where the voyage started from.
starting_port_id Optional[int]

Numeric ID corresponding to the port where the voyage started from. The start of a voyage is set as the end of the previous voyage (if existing) or the first received AIS (for a new building). Voyages are consecutive and with no breaks in between, therefore a vessel is always in a voyage.
starting_country_id Optional[int]

Numeric ID corresponding to the country where the voyage started from.
starting_country_name Optional[str]

String, name of the country where the voyage started from.
starting_area_id_level0 Optional[int]

Numeric ID corresponding to the level 0 area where the voyage started from. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest.
starting_area_name_level0 Optional[str]

String, name of the area where the voyage started from. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
first_load_port_name Optional[str]

String, name of the port where the vessel performed the first loading port call of a voyage.
first_load_port_id Optional[int]

Numeric ID corresponding to the port where the vessel performed the first loading port call of a voyage.
first_load_arrival_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The beginning of the first loading port call, including waiting time. The arrival date of a port call is calculated based on the first AIS point within the event. If the vessel waits in an anchorage area for days, this waiting time is captured as the difference between the FirstLoadArrivalDate and the FirstLoadStartTimeOfOperation.
first_load_start_time_of_operation Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of the first loading operation. This is the timestamp of the first AIS point received when the vessel is within a jetty or while performing a ship-to-ship operation.
first_load_sailing_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The end of the first loading port call. The sailing date of an event is calculated based on the last AIS point within the event. In the case of missing AIS data, the sailing date is derived based on the next reported location of the vessel after the event and the time without reported AIS information.
first_load_country_id Optional[int]

Numeric ID corresponding to the country where the vessel performed the first loading port call.
first_load_country_name Optional[str]

String, name of the country where the vessel performed the first loading port call.
first_load_area_id_level0 Optional[int]

Numeric ID corresponding to the level 0 area where the vessel performed the first loading operation of the voyage. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest.
first_load_area_name_level0 Optional[str]

String, name of the area where the vessel performed the first loading operation of the voyage. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
last_discharge_port_name Optional[str]

String, name of the port where the vessel performed the last discharging port call of a voyage.
last_discharge_port_id Optional[int]

Numeric ID corresponding to the port where the vessel performed the last discharging port call of a voyage.
last_discharge_arrival_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The beginning of the last discharging port call, including waiting time. The arrival date of a port call is calculated based on the first AIS point within the event. If the vessel waits in an anchorage area for days, this waiting time is captured as the difference between the LastDischargeArrivalDate and the LastDischargeStartTimeOfOperation.
last_discharge_start_time_of_operation Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of the last discharging operation. This is the timestamp of the first AIS point received when the vessel is within a jetty or while performing a ship-to-ship operation.
last_discharge_sailing_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of the first loading operation. This is the timestamp of the first AIS point received when the vessel is within a jetty or while performing a ship-to-ship operation.
last_discharge_country_id Optional[int]

Numeric ID corresponding to the country where the vessel performed the last discharging port call.
last_discharge_country_name Optional[str]

String, name of the country where the vessel performed the last discharging port call.
last_discharge_area_id_level0 Optional[int]

Numeric ID corresponding to the level 0 area where the vessel performed the last discharging operation of the voyage. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest.
last_discharge_area_name_level0 Optional[str]

String, name of the area where the vessel performed the last discharging operation of the voyage. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
repairs_ind Optional[bool]

Boolean. True if the voyage contains any port call operation performed in a dry dock or shipyard.
storage_ind Optional[bool]

Boolean. True if the vessel acted as storage in the specific voyage.
sts_load_ind Optional[bool]

Boolean. True if at least one loading operation has been performed by transferring cargo from another vessel through a ship-to-ship operation.
sts_discharge_ind Optional[bool]

Boolean. True if at least one discharging operation has been performed by transferring cargo from another vessel through a ship-to-ship operation.
local_trade_ind Optional[bool]

Boolean. True if the vessel has loaded and discharged in the same country.
Source code in signal_ocean/voyages/models.py 
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
@dataclass(frozen=True)
class VoyageCondensed(Voyage):
    """Contains information about a single voyage of a vessel.

    Attributes:
            starting_port_name: String, name of the port in where the voyage
                    started from.
            starting_port_id: Numeric ID corresponding to the port where the
                    voyage started from. The start of a voyage is set as the
                    end of the previous voyage (if existing) or the first
                    received AIS (for a new building). Voyages are
                    consecutive and with no breaks in between, therefore a
                    vessel is always in a voyage.
            starting_country_id: Numeric ID corresponding to the country
                    where the voyage started from.
            starting_country_name: String, name of the country where the
                    voyage started from.
            starting_area_id_level0: Numeric ID corresponding to the level 0
                    area where the voyage started from. Level 0 areas offer a
                    detailed breakdown of the globe to the areas of maritime
                    interest.
            starting_area_name_level0: String, name of the area where the
                    voyage started from. Level 0 areas offer a detailed
                    breakdown of the globe to the areas of maritime interest.
                    Examples of level 0 areas include "Arabian Gulf",
                    "US Gulf" and "East Mediterranean".
            first_load_port_name: String, name of the port where the vessel
                    performed the first loading port call of a voyage.
            first_load_port_id: Numeric ID corresponding to the port where
                    the vessel performed the first loading port call of a
                    voyage.
            first_load_arrival_date: Date, format YYYY-MM-DD HH:MM:SS. The
                    beginning of the first loading port call, including
                    waiting time. The arrival date of a port call is
                    calculated based on the first AIS point within the
                    event. If the vessel waits in an anchorage area for days,
                    this waiting time is captured as the difference between
                    the FirstLoadArrivalDate and the
                    FirstLoadStartTimeOfOperation.
            first_load_start_time_of_operation: Date, format
                    YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of
                    the first loading operation. This is the timestamp of the
                    first AIS point received when the vessel is within a jetty
                    or while performing a ship-to-ship operation.
            first_load_sailing_date: Date, format YYYY-MM-DD HH:MM:SS. The end
                    of the first loading port call. The sailing date of an
                    event is calculated based on the last AIS point within the
                    event. In the case of missing AIS data, the sailing date
                    is derived based on the next reported location of the
                    vessel after the event and the time without reported AIS
                    information.
            first_load_country_id: Numeric ID corresponding to the country
                    where the vessel performed the first loading port call.
            first_load_country_name: String, name of the country where the
                    vessel performed the first loading port call.
            first_load_area_id_level0: Numeric ID corresponding to the level 0
                    area where the vessel performed the first loading
                    operation of the voyage. Level 0 areas offer a detailed
                    breakdown of the globe to the areas of maritime interest.
            first_load_area_name_level0: String, name of the area where the
                    vessel performed the first loading operation of the
                    voyage. Level 0 areas offer a detailed breakdown of the
                    globe to the areas of maritime interest. Examples of level
                    0 areas include "Arabian Gulf", "US Gulf" and "East
                    Mediterranean".
            last_discharge_port_name: String, name of the port where the
                    vessel performed the last discharging port call of a
                    voyage.
            last_discharge_port_id: Numeric ID corresponding to the port where
                    the vessel performed the last discharging port call of a
                    voyage.
            last_discharge_arrival_date: Date, format YYYY-MM-DD HH:MM:SS. The
                    beginning of the last discharging port call, including
                    waiting time. The arrival date of a port call is
                    calculated based on the first AIS point within the event.
                    If the vessel waits in an anchorage area for days, this
                    waiting time is captured as the difference between the
                    LastDischargeArrivalDate and the
                    LastDischargeStartTimeOfOperation.
            last_discharge_start_time_of_operation: Date, format
                    YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of
                    the last discharging operation. This is the timestamp of
                    the first AIS point received when the vessel is within a
                    jetty or while performing a ship-to-ship operation.
            last_discharge_sailing_date: Date, format YYYY-MM-DD HH:MM:SS.
                    Timestamp indicating the beginning of the first loading
                    operation. This is the timestamp of the first AIS point
                    received when the vessel is within a jetty or while
                    performing a ship-to-ship operation.
            last_discharge_country_id: Numeric ID corresponding to the country
                    where the vessel performed the last discharging port call.
            last_discharge_country_name: String, name of the country where the
                    vessel performed the last discharging port call.
            last_discharge_area_id_level0: Numeric ID corresponding to the
                    level 0 area where the vessel performed the last
                    discharging operation of the voyage. Level 0 areas offer
                    a detailed breakdown of the globe to the areas of maritime
                    interest.
            last_discharge_area_name_level0: String, name of the area where
                    the vessel performed the last discharging operation of the
                    voyage. Level 0 areas offer a detailed breakdown of the
                    globe to the areas of maritime interest. Examples of level
                    0 areas include "Arabian Gulf", "US Gulf" and "East
                    Mediterranean".
            repairs_ind: Boolean. True if the voyage contains any port call
                    operation performed in a dry dock or shipyard.
            storage_ind: Boolean. True if the vessel acted as storage in the
                    specific voyage.
            sts_load_ind: Boolean. True if at least one loading operation has
                    been performed by transferring cargo from another vessel
                    through a ship-to-ship operation.
            sts_discharge_ind: Boolean. True if at least one discharging
                    operation has been performed by transferring cargo from
                    another vessel through a ship-to-ship operation.
            local_trade_ind: Boolean. True if the vessel has loaded and
                    discharged in the same country.
    """

    starting_port_name: Optional[str] = None
    starting_port_id: Optional[int] = None
    starting_country_id: Optional[int] = None
    starting_country_name: Optional[str] = None
    starting_area_id_level0: Optional[int] = None
    starting_area_name_level0: Optional[str] = None
    first_load_port_name: Optional[str] = None
    first_load_port_id: Optional[int] = None
    first_load_arrival_date: Optional[datetime] = None
    first_load_start_time_of_operation: Optional[datetime] = None
    first_load_sailing_date: Optional[datetime] = None
    first_load_country_id: Optional[int] = None
    first_load_country_name: Optional[str] = None
    first_load_area_id_level0: Optional[int] = None
    first_load_area_name_level0: Optional[str] = None
    last_discharge_port_name: Optional[str] = None
    last_discharge_port_id: Optional[int] = None
    last_discharge_arrival_date: Optional[datetime] = None
    last_discharge_start_time_of_operation: Optional[datetime] = None
    last_discharge_sailing_date: Optional[datetime] = None
    last_discharge_country_id: Optional[int] = None
    last_discharge_country_name: Optional[str] = None
    last_discharge_area_id_level0: Optional[int] = None
    last_discharge_area_name_level0: Optional[str] = None
    repairs_ind: Optional[bool] = None
    storage_ind: Optional[bool] = None
    sts_load_ind: Optional[bool] = None
    sts_discharge_ind: Optional[bool] = None
    local_trade_ind: Optional[bool] = None

VoyageEvent dataclass

An event associated with a voyage of a vessel.

Voyage events describe the start of the voyage, a stop or a port call that took place during this voyage.

Attributes:

Name Type Description
id Optional[str]

String. Uniquely identifies the event.
port_id Optional[int]

Numeric ID corresponding to the port in which the event took place. A port may be associated with multiple geo assets representing different terminals and anchorages within this port.
voyage_id Optional[str]

String. Uniquely identifies the voyage that this event relates to.
event_type Optional[str]

String. It can take values "Stop", "Portcall" or "VoyageStart".
event_horizon Optional[str]

String. It can take "Historical", "Current" or "Future" values, depending on whether the event is in the past with reference point the latest AIS point of the vessel (ArrivalDate and SailingDate both in the past), is current (ArrivalDate in the past and SailingDate in the future) or future (both ArrivalDate and SailingDate in the future).
purpose Optional[str]

String. It will be "Stop" if EventType="Stop" and "Start" if EventType="VoyageStart". If the event is a portcall, that is an operational stop, this field specifies the type of operation, like "Load", "Discharge" or "Dry dock".
event_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The timestamp of the specific event, for instantaneous events e.g. VoyageStart
arrival_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The beginning of the specific event. The arrival date of an event is calculated based on the first AIS point within the event. In the case of missing AIS data, the arrival date is derived based on the last reported location of the vessel before the event and the time without reported AIS information. If an event is associated with multiple event details, the arrival date of the event reports the arrival date of the first event detail associated with this event.
sailing_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The end of the specific event. The sailing date of an event is calculated based on the last AIS point within the event. In the case of missing AIS data, the sailing date is derived based on the next reported location of the vessel after the event and the time without reported AIS information. If an event is associated with multiple event details, the sailing date of the event reports the sailing date of the final event detail associated with this event.
latitude Optional[float]

Numeric, decimal value representing the latitude of the location where the event took place.
longitude Optional[float]

Numeric, decimal value representing the longitude of the location where the event took place.
geo_asset_id Optional[int]

Numeric ID corresponding to the geo asset in which the event took place. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
geo_asset_name Optional[str]

Name of the GeoAsset in which the event took place. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
port_name Optional[str]

Name of the port in which the event took place. A port may be associated with multiple geo assets representing different terminals and anchorages within this port.
country_id Optional[int]

Numeric ID corresponding to the country in which the event took place.
country Optional[str]

Name of the country in which the event took place.
area_idlevel0 Optional[int]

Numeric ID corresponding to the level 0 area in which the event took place. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
area_name_level0 Optional[str]

Name of the area in which the event took place. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
area_idlevel1 Optional[int]

Numeric ID corresponding to the area in which the event took place. Level 1 areas consist of one or multiple level 0 areas. For example, level 1 area "Mediterranean" groups together the level 0 areas "West Mediterranean", "Central Mediterranean" and "East Mediterranean".
area_name_level1 Optional[str]

Name of the area in which the event took place. Level 1 areas consist of one or multiple level 0 areas. For example, level 1 area "Mediterranean" groups together the level 0 areas "West Mediterranean", "Central Mediterranean" and "East Mediterranean".
area_idlevel2 Optional[int]

Numeric ID corresponding to the area in which the event took place. Level 2 areas consist of one or multiple level 1 areas. For example, level 2 area "Mediterranean/UK Continent" groups together the "Mediterranean" and "UK Continent" level 1 areas.
area_name_level2 Optional[str]

Name of the area in which the event took place. Level 2 areas consist of one or multiple level 1 areas. For example, level 2 area "Mediterranean/UK Continent" groups together the "Mediterranean" and "UK Continent" level 1 areas.
area_idlevel3 Optional[int]

Numeric ID corresponding to the area in which the event took place. Level 3 areas the highest area grouping in our taxonomy. Examples of such areas are "Pacific America" or "Africa". These group together level 2 areas. For instance, "Pacific America" groups together the level 2 areas "West Coast North America", "West Coast Mexico", "West Coast Central America" and "West Coast South America".
area_name_level3 Optional[str]

Name of the area in which the event took place. Level 3 areas the highest area grouping in our taxonomy. Examples of such areas are "Pacific America" or "Africa". These group together level 2 areas. For instance, "Pacific America" groups together the level 2 areas "West Coast North America", "West Coast Mexico", "West Coast Central America" and "West Coast South America".
low_ais_density Optional[bool]

Boolean, indicating whether there is no tracked AIS data for a duration higher that the time required for an operation.
quantity Optional[float]

Numeric, measured in kilotonnes [kt]. It is the cargo quantity reported in at least one of the market reports.
quantity_unit_id Optional[int]

Numeric ID corresponding to the Quantity unit 1 -> MetricTonnes, 2 -> CubicMeters.
quantity_unit Optional[str]

String corresponding to the unit type of the field Quantity (MetricTonnes for Tanker, LPG and Dry, CubicMeters for LNG).
quantity_in_barrels Optional[int]

Numeric, the quantity measured in barrels, applicable for Tanker vessels.
quantity_source_id Optional[int]

"Numeric ID corresponding to the type of Quantity source 0 -> None, 1 -> Estimated, 2 -> MarketInfo, 3 -> Lineup, 20 -> PrivateInfo.
quantity_source Optional[int]

String, it specifies the source of Quantity. If market reports are available this field takes value "MarketInfo". If no market reports are available for this voyage, the quantity is estimated. Market info is considered more accurate and reliable, whenever available.
event_details Optional[Tuple[VoyageEventDetail, ...]]

Specific details regarding the voyage events, e.g. a ship-to-ship operation or a jetty stay.
Source code in signal_ocean/voyages/models.py 
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
@dataclass(frozen=True)
class VoyageEvent:
    """An event associated with a voyage of a vessel.

    Voyage events describe the start of the voyage, a stop or a port call that
    took place during this voyage.

    Attributes:
        id: String. Uniquely identifies the event.
        port_id: Numeric ID corresponding to the port in which the event took
            place. A port may be associated with multiple geo assets
            representing different terminals and anchorages within this port.
        voyage_id: String. Uniquely identifies the voyage that this event
            relates to.
        event_type: String. It can take values "Stop", "Portcall" or
            "VoyageStart".
        event_horizon: String. It can take "Historical", "Current" or "Future"
            values, depending on whether the event is in the past with
            reference point the latest AIS point of the vessel (ArrivalDate
            and SailingDate both in the past), is current (ArrivalDate in the
            past and SailingDate in the future) or future (both ArrivalDate
            and SailingDate in the future).
        purpose: String. It will be "Stop" if EventType="Stop" and "Start" if
            EventType="VoyageStart". If the event is a portcall, that is an
            operational stop, this field specifies the type of operation, like
            "Load", "Discharge" or "Dry dock".
        event_date: Date, format YYYY-MM-DD HH:MM:SS. The timestamp of the
            specific event, for instantaneous events e.g. VoyageStart
        arrival_date: Date, format YYYY-MM-DD HH:MM:SS. The beginning of the
            specific event. The arrival date of an event is calculated based on
            the first AIS point within the event. In the case of missing AIS
            data, the arrival date is derived based on the last reported
            location of the vessel before the event and the time without
            reported AIS information. If an event is associated with multiple
            event details, the arrival date of the event reports the arrival
            date of the first event detail associated with this event.
        sailing_date: Date, format YYYY-MM-DD HH:MM:SS. The end of the specific
            event. The sailing date of an event is calculated based on the last
            AIS point within the event. In the case of missing AIS data, the
            sailing date is derived based on the next reported location of the
            vessel after the event and the time without reported AIS
            information. If an event is associated with multiple event details,
            the sailing date of the event reports the sailing date of the final
            event detail associated with this event.
        latitude: Numeric, decimal value representing the latitude of the
            location where the event took place.
        longitude: Numeric, decimal value representing the longitude of the
            location where the event took place.
        geo_asset_id: Numeric ID corresponding to the geo asset in which the
            event took place. Geo assets represent maritime facilities such as
            terminals, anchorages and lightering zones. Multiple geo assets are
            grouped under the same port.
        geo_asset_name: Name of the GeoAsset in which the event took place. Geo
            assets represent maritime facilities such as terminals, anchorages
            and lightering zones. Multiple geo assets are grouped under the
            same port.
        port_name: Name of the port in which the event took place. A port may
            be associated with multiple geo assets representing different
            terminals and anchorages within this port.
        country_id: Numeric ID corresponding to the country in which the event
            took place.
        country: Name of the country in which the event took place.
        area_idlevel0: Numeric ID corresponding to the level 0 area in which
            the event took place. Level 0 areas offer a detailed breakdown of
            the globe to the areas of maritime interest. Examples of level 0
            areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
        area_name_level0: Name of the area in which the event took place. Level
            0 areas offer a detailed breakdown of the globe to the areas of
            maritime interest. Examples of level 0 areas include "Arabian
            Gulf", "US Gulf" and "East Mediterranean".
        area_idlevel1: Numeric ID corresponding to the area in which the event
            took place. Level 1 areas consist of one or multiple level 0 areas.
            For example, level 1 area "Mediterranean" groups together the level
            0 areas "West Mediterranean", "Central Mediterranean" and "East
            Mediterranean".
        area_name_level1: Name of the area in which the event took place. Level
            1 areas consist of one or multiple level 0 areas. For example,
            level 1 area "Mediterranean" groups together the level 0 areas
            "West Mediterranean", "Central Mediterranean" and "East
            Mediterranean".
        area_idlevel2: Numeric ID corresponding to the area in which the event
            took place. Level 2 areas consist of one or multiple level 1 areas.
            For example, level 2 area "Mediterranean/UK Continent" groups
            together the "Mediterranean" and "UK Continent" level 1 areas.
        area_name_level2: Name of the area in which the event took place. Level
            2 areas consist of one or multiple level 1 areas. For example,
            level 2 area "Mediterranean/UK Continent" groups together the
            "Mediterranean" and "UK Continent" level 1 areas.
        area_idlevel3: Numeric ID corresponding to the area in which the event
            took place. Level 3 areas the highest area grouping in our
            taxonomy. Examples of such areas are "Pacific America" or "Africa".
            These group together level 2 areas. For instance, "Pacific America"
            groups together the level 2 areas "West Coast North America", "West
            Coast Mexico", "West Coast Central America" and "West Coast South
            America".
        area_name_level3: Name of the area in which the event took place. Level
            3 areas the highest area grouping in our taxonomy. Examples of such
            areas are "Pacific America" or "Africa". These group together level
            2 areas. For instance, "Pacific America" groups together the level
            2 areas "West Coast North America", "West Coast Mexico", "West
            Coast Central America" and "West Coast South America".
        low_ais_density: Boolean, indicating whether there is no tracked AIS
            data for a duration higher that the time required for an operation.
        quantity: Numeric, measured in kilotonnes [kt]. It is the cargo
            quantity reported in at least one of the market reports.
        quantity_unit_id: Numeric ID corresponding to the Quantity unit
            1 -> MetricTonnes, 2 -> CubicMeters.
        quantity_unit: String corresponding to the unit type of the field
            Quantity (MetricTonnes for Tanker, LPG and Dry, CubicMeters
            for LNG).
        quantity_in_barrels: Numeric, the quantity measured in barrels,
            applicable for Tanker vessels.
        quantity_source_id: "Numeric ID corresponding to the type of
            Quantity source 0 -> None, 1 -> Estimated, 2 -> MarketInfo,
            3 -> Lineup, 20 -> PrivateInfo.
        quantity_source: String, it specifies the source of Quantity. If market
                reports are available this field takes value "MarketInfo".
                If no market reports are available
                for this voyage, the quantity is estimated.
                Market info is considered more accurate and reliable,
                whenever available.
        event_details: Specific details regarding the voyage events, e.g. a
            ship-to-ship operation or a jetty stay.
    """

    id: Optional[str] = None
    port_id: Optional[int] = None
    voyage_id: Optional[str] = None
    event_type: Optional[str] = None
    event_horizon: Optional[str] = None
    purpose: Optional[str] = None
    event_date: Optional[datetime] = None
    arrival_date: Optional[datetime] = None
    sailing_date: Optional[datetime] = None
    latitude: Optional[float] = None
    longitude: Optional[float] = None
    geo_asset_id: Optional[int] = None
    geo_asset_name: Optional[str] = None
    port_name: Optional[str] = None
    country_id: Optional[int] = None
    country: Optional[str] = None
    area_idlevel0: Optional[int] = None
    area_name_level0: Optional[str] = None
    area_idlevel1: Optional[int] = None
    area_name_level1: Optional[str] = None
    area_idlevel2: Optional[int] = None
    area_name_level2: Optional[str] = None
    area_idlevel3: Optional[int] = None
    area_name_level3: Optional[str] = None
    low_ais_density: Optional[bool] = None
    quantity: Optional[float] = None
    quantity_unit_id: Optional[int] = None
    quantity_unit: Optional[str] = None
    quantity_in_barrels: Optional[int] = None
    event_details: Optional[Tuple[VoyageEventDetail, ...]] = None

VoyageEventDetail dataclass

Detailed information about a voyage events.

Voyage event details provides information a such as a jetty stay or ship-to-ship operation.

Attributes:

Name Type Description
id Optional[str]

String. Uniquely identifies the event detail.
event_id Optional[str]

String. Uniquely identifies the event that this event detail relates to.
event_detail_type Optional[str]

String, denotes the type of the event detail. For instance, "StS" indicates that the event is a ship-to-ship operation, while "Jetty" describes that the event took place in a jetty.
arrival_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The beginning of the specific event. The arrival date of an event is calculated based on the first AIS point within the event. In the case of missing AIS data, the arrival date is derived based on the last reported location of the vessel before the event and the time without reported AIS information.
sailing_date Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. The end of the specific event. The sailing date of an event is calculated based on the last AIS point within the event. In the case of missing AIS data, the sailing date is derived based on the next reported location of the vessel after the event and the time without reported AIS information.
start_time_of_operation Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Timestamp indicating the beginning of the operation described by the event detail. This is the timestamp of the first AIS point the vessel is tracked within a jetty or that is captured performing a ship-to- ship operation.
end_time_of_operation Optional[datetime]

Date, format YYYY-MM-DD HH:MM:SS. Timestamp indicating the end of the operation described by the event detail. This is the timestamp of the final AIS point the vessel is tracked within a jetty or that is captured performing a ship-to-ship operation.
sts_id Optional[str]

String, A unique identifier assigned to each ship-to-ship event. Will be identical for both participating vessels.
geo_asset_id Optional[int]

Numeric ID corresponding to the geo asset in which the event took place. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
geo_asset_name Optional[str]

Name of the GeoAsset in which the event took place. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
latitude Optional[float]

Numeric, decimal value representing the latitude of the location where the event took place. The location of the vessel is identified from AIS data within the duration of the event or, in the case of missing AIS data, from the location of the GeoAsset in which the event took place. If the event represents an operation in a jetty or a STS operation, the latitude reports the location of the first AIS within the jetty or STS operation.
longitude Optional[float]

Numeric, decimal value representing the longitude of the location where the event took place. The location of the vessel is identified from AIS data within the duration of the event or, in the case of missing AIS data, from the location of the GeoAsset in which the event took place. If the event represents an operation in a jetty or a STS operation, the longitude reports the location of the first AIS within the jetty or STS operation.
other_vessel_imo Optional[int]

Numeric, Containing the IMO of the second vessel in case of ship-to-ship operation.
other_vessel_name Optional[str]

String, Containing the name of the second vessel in case of ship-to-ship operation.
Source code in signal_ocean/voyages/models.py 
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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@dataclass(frozen=True)
class VoyageEventDetail:
    """Detailed information about a voyage events.

    Voyage event details provides information a such as a jetty stay
    or ship-to-ship operation.

    Attributes:
        id: String. Uniquely identifies the event detail.
        event_id: String. Uniquely identifies the event that this event detail
            relates to.
        event_detail_type: String, denotes the type of the event detail. For
            instance, "StS" indicates that the event is a ship-to-ship
            operation, while "Jetty" describes that the event took place in a
            jetty.
        arrival_date: Date, format YYYY-MM-DD HH:MM:SS. The beginning of the
            specific event. The arrival date of an event is calculated based on
            the first AIS point within the event. In the case of missing AIS
            data, the arrival date is derived based on the last reported
            location of the vessel before the event and the time without
            reported AIS information.
        sailing_date: Date, format YYYY-MM-DD HH:MM:SS. The end of the specific
            event. The sailing date of an event is calculated based on the last
            AIS point within the event. In the case of missing AIS data, the
            sailing date is derived based on the next reported location of the
            vessel after the event and the time without reported AIS
            information.
        start_time_of_operation: Date, format YYYY-MM-DD HH:MM:SS. Timestamp
            indicating the beginning of the operation described by the event
            detail. This is the timestamp of the first AIS point the vessel is
            tracked within a jetty or that is captured performing a ship-to-
            ship operation.
        end_time_of_operation: Date, format YYYY-MM-DD HH:MM:SS. Timestamp
            indicating the end of the operation described by the event detail.
            This is the timestamp of the final AIS point the vessel is tracked
            within a jetty or that is captured performing a ship-to-ship
            operation.
        sts_id: String, A unique identifier assigned to each ship-to-ship
            event. Will be identical for both participating vessels.
        geo_asset_id: Numeric ID corresponding to the geo asset in which the
            event took place. Geo assets represent maritime facilities such as
            terminals, anchorages and lightering zones. Multiple geo assets are
            grouped under the same port.
        geo_asset_name: Name of the GeoAsset in which the event took place. Geo
            assets represent maritime facilities such as terminals, anchorages
            and lightering zones. Multiple geo assets are grouped under the
            same port.
        latitude: Numeric, decimal value representing the latitude of the
            location where the event took place. The location of the vessel is
            identified from AIS data within the duration of the event or, in
            the case of missing AIS data, from the location of the GeoAsset in
            which the event took place. If the event represents an operation in
            a jetty or a STS operation, the latitude reports the location of
            the first AIS within the jetty or STS operation.
        longitude: Numeric, decimal value representing the longitude of the
            location where the event took place. The location of the vessel is
            identified from AIS data within the duration of the event or, in
            the case of missing AIS data, from the location of the GeoAsset in
            which the event took place. If the event represents an operation in
            a jetty or a STS operation, the longitude reports the location of
            the first AIS within the jetty or STS operation.
        other_vessel_imo: Numeric, Containing the IMO of the second vessel in
            case of ship-to-ship operation.
        other_vessel_name: String, Containing the name of the second vessel in
            case of ship-to-ship operation.
    """

    id: Optional[str] = None
    event_id: Optional[str] = None
    event_detail_type: Optional[str] = None
    arrival_date: Optional[datetime] = None
    sailing_date: Optional[datetime] = None
    start_time_of_operation: Optional[datetime] = None
    end_time_of_operation: Optional[datetime] = None
    sts_id: Optional[str] = None
    geo_asset_id: Optional[int] = None
    geo_asset_name: Optional[str] = None
    latitude: Optional[float] = None
    longitude: Optional[float] = None
    other_vessel_imo: Optional[int] = None
    other_vessel_name: Optional[str] = None
    floating_storage_start_date: Optional[datetime] = None
    floating_storage_duration: Optional[int] = None

VoyageGeo dataclass

Information about a geo asset object associated with a voyage.

Attributes:

Name Type Description
id Optional[int]

Numeric ID of the geo asset. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
name Optional[str]

Name of the geo asset. Geo assets represent maritime facilities such as terminals, anchorages and lightering zones. Multiple geo assets are grouped under the same port.
port_id Optional[int]

Numeric ID corresponding to the port. A port may be associated with multiple geo assets representing different terminals and anchorages within this port.
port_name Optional[str]

Name of the port. A port may be associated with multiple geo assets representing different terminals and anchorages within this port.
country_id Optional[int]

Numeric ID corresponding to the country of the geo asset.
country Optional[str]

Name of the country of the geo asset.
area_idlevel0 Optional[int]

Numeric ID corresponding to the level 0 area of the geo asset. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
area_name_level0 Optional[str]

Name of the level 0 area of the geo asset. Level 0 areas offer a detailed breakdown of the globe to the areas of maritime interest. Examples of level 0 areas include "Arabian Gulf", "US Gulf" and "East Mediterranean".
area_idlevel1 Optional[int]

Numeric ID corresponding to the level 1 area of the geo asset. Level 1 areas consist of one or multiple level 0 areas. For example, level 1 area "Mediterranean" groups together the level 0 areas "West Mediterranean", "Central Mediterranean" and "East Mediterranean".
area_name_level1 Optional[str]

Name of the level 1 area of the geo asset. Level 1 areas consist of one or multiple level 0 areas. For example, level 1 area "Mediterranean" groups together the level 0 areas "West Mediterranean", "Central Mediterranean" and "East Mediterranean".
area_idlevel2 Optional[int]

Numeric ID corresponding to the level 2 area of the geo asset. Level 2 areas consist of one or multiple level 1 areas. For example, level 2 area "Mediterranean/UK Continent" groups together the "Mediterranean" and "UK Continent" level 1 areas.
area_name_level2 Optional[str]

Name of the level 2 area of the geo asset. Level 2 areas consist of one or multiple level 1 areas. For example, level 2 area "Mediterranean/UK Continent" groups together the "Mediterranean" and "UK Continent" level 1 areas.
area_idlevel3 Optional[int]

Numeric ID corresponding to the level 3 area of the geo asset. Level 3 areas the highest area grouping in our taxonomy. Examples of such areas are "Pacific America" or "Africa". These group together level 2 areas. For instance, "Pacific America" groups together the level 2 areas "West Coast North America", "West Coast Mexico", "West Coast Central America" and "West Coast South America".
area_name_level3 Optional[str]

Name of the level 3 area of the geo asset. Level 3 areas the highest area grouping in our taxonomy. Examples of such areas are "Pacific America" or "Africa". These group together level 2 areas. For instance, "Pacific America" groups together the level 2 areas "West Coast North America", "West Coast Mexico", "West Coast Central America" and "West Coast South America".
Source code in signal_ocean/voyages/models.py 
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
@dataclass(frozen=True)
class VoyageGeo:
    """Information about a geo asset object associated with a voyage.

    Attributes:
        id: Numeric ID of the geo asset. Geo assets represent maritime
            facilities such as terminals, anchorages and lightering zones.
            Multiple geo assets are grouped under the same port.
        name: Name of the geo asset. Geo assets represent maritime facilities
            such as terminals, anchorages and lightering zones. Multiple geo
            assets are grouped under the same port.
        port_id: Numeric ID corresponding to the port. A port may be
            associated with multiple geo assets representing different
            terminals and anchorages within this port.
        port_name: Name of the port. A port may be associated with multiple
            geo assets representing different terminals and anchorages within
            this port.
        country_id: Numeric ID corresponding to the country of the geo asset.
        country: Name of the country of the geo asset.
        area_idlevel0: Numeric ID corresponding to the level 0 area of the geo
            asset. Level 0 areas offer a detailed breakdown of the globe to
            the areas of maritime interest. Examples of level 0 areas include
            "Arabian Gulf", "US Gulf" and "East Mediterranean".
        area_name_level0: Name of the level 0 area of the geo asset. Level 0
            areas offer a detailed breakdown of the globe to the areas of
            maritime interest. Examples of level 0 areas include "Arabian
            Gulf", "US Gulf" and "East Mediterranean".
        area_idlevel1: Numeric ID corresponding to the level 1 area of the geo
            asset. Level 1 areas consist of one or multiple level 0 areas. For
            example, level 1 area "Mediterranean" groups together the level 0
            areas "West Mediterranean", "Central Mediterranean" and "East
            Mediterranean".
        area_name_level1: Name of the level 1 area of the geo asset. Level 1
            areas consist of one or multiple level 0 areas. For example, level
            1 area "Mediterranean" groups together the level 0 areas "West
            Mediterranean", "Central Mediterranean" and "East Mediterranean".
        area_idlevel2: Numeric ID corresponding to the level 2 area of the geo
            asset. Level 2 areas consist of one or multiple level 1 areas. For
            example, level 2 area "Mediterranean/UK Continent" groups together
            the "Mediterranean" and "UK Continent" level 1 areas.
        area_name_level2: Name of the level 2 area of the geo asset. Level 2
            areas consist of one or multiple level 1 areas. For example, level
            2 area "Mediterranean/UK Continent" groups together the
            "Mediterranean" and "UK Continent" level 1 areas.
        area_idlevel3: Numeric ID corresponding to the level 3 area of the geo
            asset. Level 3 areas the highest area grouping in our taxonomy.
            Examples of such areas are "Pacific America" or "Africa". These
            group together level 2 areas. For instance, "Pacific America"
            groups together the level 2 areas "West Coast North America",
            "West Coast Mexico", "West Coast Central America" and "West Coast
            South America".
        area_name_level3: Name of the level 3 area of the geo asset. Level 3
            areas the highest area grouping in our taxonomy. Examples of such
            areas are "Pacific America" or "Africa". These group together
            level 2 areas. For instance, "Pacific America" groups together the
            level 2 areas "West Coast North America", "West Coast Mexico",
            "West Coast Central America" and "West Coast South America".
    """

    id: Optional[int] = None
    name: Optional[str] = None
    port_id: Optional[int] = None
    port_name: Optional[str] = None
    country_id: Optional[int] = None
    country: Optional[str] = None
    area_idlevel0: Optional[int] = None
    area_name_level0: Optional[str] = None
    area_idlevel1: Optional[int] = None
    area_name_level1: Optional[str] = None
    area_idlevel2: Optional[int] = None
    area_name_level2: Optional[str] = None
    area_idlevel3: Optional[int] = None
    area_name_level3: Optional[str] = None

VoyagesAPI

Represents Signal's Voyages API.

Source code in signal_ocean/voyages/voyages_api.py 
  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
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
class VoyagesAPI:
    """Represents Signal's Voyages API."""

    relative_url = "voyages-api/v4/"

    def __init__(self, connection: Optional[Connection] = None):
        """Initializes VoyagesAPI.

        Args:
            connection: API connection configuration. If not provided, the
                default connection method is used.
        """
        self.__connection = connection or Connection()

    @staticmethod
    def _get_endpoint(
        imo: Optional[List[int]] = None,
        voyage_keys: Optional[List[str]] = None,
        event_type: Optional[int] = None,
        event_horizons: Optional[List[int]] = None,
        event_purpose: Optional[List[str]] = None,
        vessel_class_id: Optional[List[int]] = None,
        port_ids: Optional[List[int]] = None,
        vessel_type_id: Optional[int] = None,
        voyage_date_from: Optional[date] = None,
        voyage_date_to: Optional[date] = None,
        voyage_number_from: Optional[int] = None,
        voyage_number_to: Optional[int] = None,
        start_date_from: Optional[date] = None,
        start_date_to: Optional[date] = None,
        first_load_arrival_date_from: Optional[date] = None,
        first_load_arrival_date_to: Optional[date] = None,
        end_date_from: Optional[date] = None,
        end_date_to: Optional[date] = None,
        market_info_rate_from: Optional[date] = None,
        market_info_rate_to: Optional[date] = None,
        market_info_rate_type: Optional[date] = None,
        commercial_operator_id: Optional[int] = None,
        charterer_id: Optional[int] = None,
        voyage_horizon: Optional[List[str]] = None,
        token: Optional[str] = None,
        hide_event_details: Optional[bool] = None,
        hide_events: Optional[bool] = None,
        hide_market_info: Optional[bool] = None,
        nested: Optional[bool] = True,
        condensed: Optional[bool] = False,
        incremental: Optional[bool] = False,
    ) -> str:
        """Constructs the VoyagesData v4 endpoint.

        Args:
            endpoint_params: VoyagesData v4 endpoint parameters dictionary.
            Part of get_voyages method arguments.
            Part of get_voyages_incremental arguments.

        Returns:
            The constructed endpoint to call to retrieve the requested \
            voyages for the provided arguments.
        """
        # Special Handling for event purposes and VoyageHorizons
        endpoint_params = locals()
        if condensed:
            format_type = "condensed"
        elif nested:
            format_type = "nested"
        else:
            format_type = "flat"
        endpoint = "voyages/" + \
            format_type + \
            f'{"/incremental?" if incremental else "?"}'

        del endpoint_params["nested"]
        del endpoint_params["condensed"]
        del endpoint_params["incremental"]
        params = urlencode(
            {
                _to_camel_case(key): value
                for key, value in endpoint_params.items()
                if value is not None and value is not []
            }, doseq=True
        )
        endpoint += params
        return urljoin(VoyagesAPI.relative_url, endpoint)

    def _get_voyages_pages(
        self, endpoint: str, token: Optional[str] = None
    ) -> Tuple[Voyages, Optional[NextRequestToken]]:
        """Get voyages paged data.

        Args:
            endpoint: The endpoint to call.
            token: Next request token for incremental voyages.

        Make consecutive requests until no next page token is returned, gather
        and return data.

        Returns:
            Voyages data gathered from the returned pages as a tupple.
            The next request token, to be used for incremental updates.
        """
        results: List[Voyage] = []
        next_page_token = token
        while True:
            params = (
                {"token": next_page_token}
                if next_page_token is not None
                else None
            )
            response = get_single(
                self.__connection,
                endpoint,
                VoyagesPagedResponse,
                query_string=params,
            )
            if response is not None and response.data is not None:
                results.extend(response.data)
            next_page_token = (
                response.next_page_token if response is not None else None
            )

            if next_page_token is None:
                break

        next_request_token = (
            response.next_request_token if response is not None else None
        )
        return tuple(results), next_request_token

    def _get_voyages_flat_pages(
        self, endpoint: str, token: Optional[str] = None
    ) -> Tuple[VoyagesFlat, Optional[NextRequestToken]]:
        """Get voyages flat paged data.

        Args:
            endpoint: The endpoint to call.
            token: Next request token for incremental voyages.

        Make consecutive requests until no next page token is returned, gather
        and return data.

        Returns:
            Voyages flat data gathered from the returned pages as a tupple.
            The next request token, to be used for incremental updates.
        """
        voyages: List[Voyage] = []
        events: List[VoyageEvent] = []
        event_details: List[VoyageEventDetail] = []
        geos: List[VoyageGeo] = []
        next_page_token = token
        while True:
            params = (
                {"token": next_page_token}
                if next_page_token is not None
                else None
            )

            response = get_single(
                self.__connection,
                endpoint,
                VoyagesFlatPagedResponse,
                query_string=params,
            )

            if response is not None and response.data is not None:
                voyages.extend(response.data.voyages or [])
                events.extend(response.data.events or [])
                event_details.extend(response.data.event_details or [])
                geos.extend(response.data.geos or [])

            next_page_token = (
                response.next_page_token if response is not None else None
            )

            if next_page_token is None:
                break

        result = VoyagesFlat(
            voyages=tuple(voyages),
            events=tuple(events),
            event_details=tuple(event_details),
            geos=tuple(geos),
        )

        next_request_token = (
            response.next_request_token if response is not None else None
        )

        return result, next_request_token

    def _get_voyages_condensed_pages(
        self, endpoint: str, token: Optional[str] = None
    ) -> Tuple[VoyagesCondensed, Optional[NextRequestToken]]:
        """Get voyages condensed paged data.

        Args:
            endpoint: The endpoint to call.
            token: Next request token for incremental voyages.

        Make consecutive requests until no next page token is returned, gather
        and return data.

        Returns:
            Voyages condensed data gathered from the returned pages as a
            tupple. The next request token, for incremental updates.
        """
        results: List[VoyageCondensed] = []
        next_page_token = token
        while True:
            params = (
                {"token": next_page_token}
                if next_page_token is not None
                else None
            )
            response = get_single(
                self.__connection,
                endpoint,
                VoyagesCondensedPagedResponse,
                query_string=params,
            )
            if response is not None and response.data is not None:
                results.extend(response.data)
            next_page_token = (
                response.next_page_token if response is not None else None
            )

            if next_page_token is None:
                break

        next_request_token = (
            response.next_request_token if response is not None else None
        )
        return tuple(results), next_request_token

    def get_voyages(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
    ) -> Voyages:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None,
                voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, voyages for all vessels are returned. If
                imo is specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, voyages for all vessels are returned. If either imo
                or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return voyages after provided date. If imo is
                specified, then date_from is ignored.

        Returns:
            Voyages data as a tupple.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []

        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            start_date_from=date_from
        )
        results, _ = self._get_voyages_pages(endpoint)
        return results

    def get_voyages_flat(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
    ) -> Optional[VoyagesFlat]:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None
                voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, voyages for all vessels are returned. If imo
                is specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, voyages for all vessels are returned. If either imo
                or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return voyages after provided date. If imo is
                specified, then date_from is treated as None.

        Returns:
            A VoyagesFlat object containing lists of voyages, voyage events, \
            voyage event details and voyage geos otherwise.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []

        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            start_date_from=date_from,
            nested=False
        )
        results, _ = self._get_voyages_flat_pages(endpoint)
        return results

    def get_voyages_condensed(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
    ) -> VoyagesCondensed:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None
                voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, voyages for all vessels are returned. If imo
                is specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, voyages for all vessels are returned. If either imo
                or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return voyages after provided date. If imo is
                specified, then date_from is treated as None.

        Returns:
            A VoyagesCondensed object containing lists of voyages.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []
        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            start_date_from=date_from,
            nested=False,
            condensed=True
        )
        results, _ = self._get_voyages_condensed_pages(endpoint)
        return results

    def get_incremental_voyages(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
        incremental_token: Optional[str] = None,
    ) -> Tuple[Voyages, Optional[NextRequestToken]]:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None,
                then voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, then voyages for all vessels are returned. If
                imo is specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, then voyages for all vessels are returned. If either
                imo or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return voyages after provided date. If imo is
                specified, then date_from is treated as None.
            incremental_token: Token returned from the previous incremental
                call. If this is the first call, then it can be omitted.

        Returns:
            A tuple containing the returned voyages, including any deleted \
            voyages, and the token for the next incremental request.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []
        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            voyage_date_from=date_from,
            nested=True,
            incremental=True
        )
        results = self._get_voyages_pages(endpoint, token=incremental_token)
        return results

    def get_incremental_voyages_flat(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
        incremental_token: Optional[str] = None,
    ) -> Tuple[VoyagesFlat, Optional[NextRequestToken]]:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None,
                then voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, voyages for all vessels are returned. If imo
                is specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, voyages for all vessels are returned. If either imo
                or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return  after the provided date. If imo is
                specified, then datevoyages_from is treated as None.
            incremental_token: Token returned from the previous incremental
                call. If this is the first call, then it can be omitted.

        Returns:
            A tuple containing the returned voyages in flat format, \
            including any deleted voyages, and the token for the next \
            incremental request.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []
        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            voyage_date_from=date_from,
            nested=False,
            incremental=True
        )
        results = self._get_voyages_flat_pages(
            endpoint, token=incremental_token
        )
        return results

    def get_incremental_voyages_condensed(
        self,
        imo: Optional[int] = None,
        vessel_class_id: Optional[int] = None,
        vessel_type_id: Optional[int] = None,
        date_from: Optional[date] = None,
        incremental_token: Optional[str] = None,
    ) -> Tuple[VoyagesCondensed, Optional[NextRequestToken]]:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imo: Return only voyages for the provided vessel IMO. If None,
                then voyages for all vessels are returned.
            vessel_class_id: Return only voyages for the provided vessel class.
                If None, then voyages for all vessels are returned. If imo is
                specified, then vessel_class_id is ignored.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, then voyages for all vessels are returned. If either
                imo or vessel_class_id is specified, then vessel_type_id is
                ignored.
            date_from: Return voyages after provided date. If imo is
                specified, then date_from is treated as None.
            incremental_token: Token returned from the previous incremental
                call. If this is the first call, then it can be omitted.

        Returns:
            A tuple containing the returned voyages in condensed format, \
            including any deleted voyages, and the token for the next \
            incremental request.
        """
        if vessel_class_id is not None:
            vcids = [vessel_class_id]
        else:
            vcids = []

        if imo is not None:
            imos = [imo]
        else:
            imos = []
        endpoint = self._get_endpoint(
            imo=imos,
            vessel_class_id=vcids,
            vessel_type_id=vessel_type_id,
            voyage_date_from=date_from,
            nested=False,
            incremental=True,
            condensed=True
        )
        results = self._get_voyages_condensed_pages(
            endpoint, token=incremental_token
        )
        return results

    def get_voyages_by_advanced_search(
        self,
        imos: Optional[List[int]] = None,
        voyage_keys: Optional[List[str]] = None,
        event_type: Optional[int] = None,
        event_horizon: Optional[int] = None,
        event_horizons: Optional[List[int]] = None,
        event_purpose: Optional[str] = None,
        event_purposes: Optional[List[str]] = None,
        vessel_class_id: Optional[int] = None,
        vessel_class_ids: Optional[List[int]] = None,
        port_id: Optional[int] = None,
        port_ids: Optional[List[int]] = None,
        vessel_type_id: Optional[int] = None,
        start_date_from: Optional[date] = None,
        start_date_to: Optional[date] = None,
        first_load_arrival_date_from: Optional[date] = None,
        first_load_arrival_date_to: Optional[date] = None,
        end_date_from: Optional[date] = None,
        end_date_to: Optional[date] = None,
        market_info_rate_from: Optional[date] = None,
        market_info_rate_to: Optional[date] = None,
        market_info_rate_type: Optional[date] = None,
        commercial_operator_id: Optional[int] = None,
        charterer_id: Optional[int] = None,
        voyage_horizon: Optional[str] = None,
        voyage_horizons: Optional[List[str]] = None,
        token: Optional[str] = None,
        hide_event_details: Optional[bool] = None,
        hide_events: Optional[bool] = None,
        hide_market_info: Optional[bool] = None,
    ) -> Voyages:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imos: If a list of imos is provided then only voyages of these
                imos will be returned
            voyage_keys: If provided only the voyages with the requested
                keys will be returned
            event_type: If an EventType is provided, then only voyages that
                include at least one event of this type will be returned.
            event_horizon: If an EventHorizon is provided, then only voyages
                of this event horizon will be returned.
            event_horizons: If a list of EventHorizons is provided then only
                voyages that include at least one event of those types
                will be returned
            event_purpose: If an EventPurpose is provided, then only voyages
                that include at least one event of this purpose will be
                returned.
            event_purposes: If a list of EventPurposes is provided then only
                voyages that include at least one event of this type
                will be returned
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, then voyages for all vessels are returned.
            vessel_class_ids: If provided only voyages of those vessel classes
                will be returned.
            port_id: If PortId is provided then only voyages that contains at
                least one event at this port will be returned.
            port_ids: If a list of ports is provided then only voyages that
                contains at least one event at those ports will be returned.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, then voyages for all vessels are returned.
            start_date_from: Return voyages after the provided voyage start
                date.
            start_date_to: Return voyages up to the provided voyage end date.
            first_load_arrival_date_from: Return voyages with a first load
                arrival date after the provided date.
            first_load_arrival_date_to: Return voyages with a first load
                arrival date up to the provided date.
            end_date_from: Return voyages with an end date after the provided
                date.
            end_date_to: Return voyages with an end date up to the provided
                date.
            market_info_rate_from: If provided, then only voyages that have
                market data and with rate greater than this will be returned.
            market_info_rate_to: If provided, then only voyages that have
                market data and with a lower rate will be returned.
            market_info_rate_type: If provided, then only voyages that have
                market data and with the same rate type will be returned.
            commercial_operator_id: If provided, then only voyages that have
                this commercial operator will be returned.
            charterer_id: If provided, then only voyages that have this
                charterer will be returned.
            voyage_horizon: If a VoyageHorizon is provided, then only voyages
                of that type will be returned.
            voyage_horizons: If a list of VoyageHorizon is provided then
                only voyages of that type will be returned.
            token: Token returned from the previous incremental call. If this
                is the first call, then it can be omitted.
            hide_event_details: If True, then event details will be excluded.
            hide_events: If True, then events will be excluded.
            hide_market_info: If True, then market information will be
                excluded.

        Returns:
            Voyages data as a tupple.
        """
        if event_horizon is not None:
            if event_horizons is None:
                event_horizons = []
            event_horizons.append(event_horizon)

        if event_purpose is not None:
            if event_purposes is None:
                event_purposes = []
            event_purposes.append(event_purpose)

        if vessel_class_id is not None:
            if vessel_class_ids is None:
                vessel_class_ids = []
            vessel_class_ids.append(vessel_class_id)

        if port_id is not None:
            if port_ids is None:
                port_ids = []
            port_ids.append(port_id)

        if voyage_horizon is not None:
            if voyage_horizons is None:
                voyage_horizons = []
            voyage_horizons.append(voyage_horizon)
        endpoint = self._get_endpoint(
            imo=imos,
            voyage_keys=voyage_keys,
            event_type=event_type,
            event_horizons=event_horizons,
            event_purpose=event_purposes,
            vessel_class_id=vessel_class_ids,
            port_ids=port_ids,
            vessel_type_id=vessel_type_id,
            start_date_from=start_date_from,
            start_date_to=start_date_to,
            first_load_arrival_date_from=first_load_arrival_date_from,
            first_load_arrival_date_to=first_load_arrival_date_to,
            end_date_from=end_date_from,
            end_date_to=end_date_to,
            market_info_rate_from=market_info_rate_from,
            market_info_rate_to=market_info_rate_to,
            market_info_rate_type=market_info_rate_type,
            commercial_operator_id=commercial_operator_id,
            charterer_id=charterer_id,
            voyage_horizon=voyage_horizons,
            token=token,
            hide_event_details=hide_event_details,
            hide_events=hide_events,
            hide_market_info=hide_market_info,
        )
        results, _ = self._get_voyages_pages(endpoint)
        return results

    def get_voyages_flat_by_advanced_search(
        self,
        imos: Optional[List[int]] = None,
        voyage_keys: Optional[List[str]] = None,
        event_type: Optional[int] = None,
        event_horizon: Optional[int] = None,
        event_horizons: Optional[List[int]] = None,
        event_purpose: Optional[str] = None,
        event_purposes: Optional[List[str]] = None,
        vessel_class_id: Optional[int] = None,
        vessel_class_ids: Optional[List[int]] = None,
        port_id: Optional[int] = None,
        port_ids: Optional[List[int]] = None,
        vessel_type_id: Optional[int] = None,
        start_date_from: Optional[date] = None,
        start_date_to: Optional[date] = None,
        first_load_arrival_date_from: Optional[date] = None,
        first_load_arrival_date_to: Optional[date] = None,
        end_date_from: Optional[date] = None,
        end_date_to: Optional[date] = None,
        market_info_rate_from: Optional[date] = None,
        market_info_rate_to: Optional[date] = None,
        market_info_rate_type: Optional[date] = None,
        commercial_operator_id: Optional[int] = None,
        charterer_id: Optional[int] = None,
        voyage_horizon: Optional[str] = None,
        voyage_horizons: Optional[List[str]] = None,
        token: Optional[str] = None,
        hide_event_details: Optional[bool] = None,
        hide_events: Optional[bool] = None,
        hide_market_info: Optional[bool] = None,
    ) -> VoyagesFlat:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imos: If a list of imos is provided then only voyages of these
                imos will be returned
            voyage_keys: If provided only the voyages with the requested
                keys will be returned
            event_type: If an EventType is provided, then only voyages that
                include at least one event of this type will be returned.
            event_horizon: If an EventHorizon is provided, then only voyages
                of this event horizon will be returned.
            event_horizons: If a list of EventHorizons is provided then only
                voyages that include at least one event of those types
                will be returned
            event_purpose: If an EventPurpose is provided, then only voyages
                that include at least one event of this purpose will be
                returned.
            event_purposes: If a list of EventPurposes is provided then only
                voyages that include at least one event of this type
                will be returned
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, then voyages for all vessels are returned.
            vessel_class_ids: If provided only voyages of those vessel classes
                will be returned.
            port_id: If PortId is provided then only voyages that contains at
                least one event at this port will be returned.
            port_ids: If a list of ports is provided then only voyages that
                contains at least one event at those ports will be returned.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, then voyages for all vessels are returned.
            start_date_from: Return voyages after the provided voyage start
                date.
            start_date_to: Return voyages up to the provided voyage end date.
            first_load_arrival_date_from: Return voyages with a first load
                arrival date after the provided date.
            first_load_arrival_date_to: Return voyages with a first load
                arrival date up to the provided date.
            end_date_from: Return voyages with an end date after the provided
                date.
            end_date_to: Return voyages with an end date up to the provided
                date.
            market_info_rate_from: If provided, then only voyages that have
                market data and with rate greater than this will be returned.
            market_info_rate_to: If provided, then only voyages that have
                market data and with a lower rate will be returned.
            market_info_rate_type: If provided, then only voyages that have
                market data and with the same rate type will be returned.
            commercial_operator_id: If provided, then only voyages that have
                this commercial operator will be returned.
            charterer_id: If provided, then only voyages that have this
                charterer will be returned.
            voyage_horizon: If a VoyageHorizon is provided, then only voyages
                of that type will be returned.
            voyage_horizons: If a list of VoyageHorizon is provided then
                only voyages of that type will be returned.
            token: Token returned from the previous incremental call. If this
                is the first call, then it can be omitted.
            hide_event_details: If True, then event details will be excluded.
            hide_events: If True, then events will be excluded.
            hide_market_info: If True, then market information will be
                excluded.

        Returns:
            Voyages data in flat format as a tupple.
        """
        if event_horizon is not None:
            if event_horizons is None:
                event_horizons = []
            event_horizons.append(event_horizon)

        if event_purpose is not None:
            if event_purposes is None:
                event_purposes = []
            event_purposes.append(event_purpose)

        if vessel_class_id is not None:
            if vessel_class_ids is None:
                vessel_class_ids = []
            vessel_class_ids.append(vessel_class_id)

        if port_id is not None:
            if port_ids is None:
                port_ids = []
            port_ids.append(port_id)

        if voyage_horizon is not None:
            if voyage_horizons is None:
                voyage_horizons = []
            voyage_horizons.append(voyage_horizon)
        endpoint = self._get_endpoint(
            imo=imos,
            voyage_keys=voyage_keys,
            event_type=event_type,
            event_horizons=event_horizons,
            event_purpose=event_purposes,
            vessel_class_id=vessel_class_ids,
            port_ids=port_ids,
            vessel_type_id=vessel_type_id,
            voyage_date_from=start_date_from,
            voyage_date_to=start_date_to,
            start_date_from=start_date_from,
            start_date_to=start_date_to,
            first_load_arrival_date_from=first_load_arrival_date_from,
            first_load_arrival_date_to=first_load_arrival_date_to,
            end_date_from=end_date_from,
            end_date_to=end_date_to,
            market_info_rate_from=market_info_rate_from,
            market_info_rate_to=market_info_rate_to,
            market_info_rate_type=market_info_rate_type,
            commercial_operator_id=commercial_operator_id,
            charterer_id=charterer_id,
            voyage_horizon=voyage_horizons,
            token=token,
            hide_event_details=hide_event_details,
            hide_events=hide_events,
            hide_market_info=hide_market_info,
            nested=False
        )
        results, _ = self._get_voyages_flat_pages(endpoint)
        return results

    def get_voyages_condensed_by_advanced_search(
        self,
        imos: Optional[List[int]] = None,
        voyage_keys: Optional[List[str]] = None,
        event_type: Optional[int] = None,
        event_horizon: Optional[int] = None,
        event_horizons: Optional[List[int]] = None,
        event_purpose: Optional[str] = None,
        event_purposes: Optional[List[str]] = None,
        vessel_class_id: Optional[int] = None,
        vessel_class_ids: Optional[List[int]] = None,
        port_id: Optional[int] = None,
        port_ids: Optional[List[int]] = None,
        vessel_type_id: Optional[int] = None,
        start_date_from: Optional[date] = None,
        start_date_to: Optional[date] = None,
        first_load_arrival_date_from: Optional[date] = None,
        first_load_arrival_date_to: Optional[date] = None,
        end_date_from: Optional[date] = None,
        end_date_to: Optional[date] = None,
        market_info_rate_from: Optional[date] = None,
        market_info_rate_to: Optional[date] = None,
        market_info_rate_type: Optional[date] = None,
        commercial_operator_id: Optional[int] = None,
        charterer_id: Optional[int] = None,
        voyage_horizon: Optional[str] = None,
        voyage_horizons: Optional[List[str]] = None,
        token: Optional[str] = None,
        hide_event_details: Optional[bool] = None,
        hide_events: Optional[bool] = None,
        hide_market_info: Optional[bool] = None,
    ) -> VoyagesCondensed:
        """Retrieves all voyages filtered with the provided parameters.

        Args:
            imos: If a list of imos is provided then only voyages of these
                imos will be returned
            voyage_keys: If provided only the voyages with the requested
                keys will be returned
            event_type: If an EventType is provided, then only voyages that
                include at least one event of this type will be returned.
            event_horizon: If an EventHorizon is provided, then only voyages
                of this event horizon will be returned.
            event_horizons: If a list of EventHorizons is provided then only
                voyages that include at least one event of those types
                will be returned
            event_purpose: If an EventPurpose is provided, then only voyages
                that include at least one event of this purpose will be
                returned.
            event_purposes: If a list of EventPurposes is provided then only
                voyages that include at least one event of this type
                will be returned
            vessel_class_id: Return only voyages for the provided vessel
                class. If None, then voyages for all vessels are returned.
            vessel_class_ids: If provided only voyages of those vessel classes
                will be returned.
            port_id: If PortId is provided then only voyages that contains at
                least one event at this port will be returned.
            port_ids: If a list of ports is provided then only voyages that
                contains at least one event at those ports will be returned.
            vessel_type_id: Return only voyages for the provided vessel type.
                If None, then voyages for all vessels are returned.
            start_date_from: Return voyages after the provided voyage start
                date.
            start_date_to: Return voyages up to the provided voyage end date.
            first_load_arrival_date_from: Return voyages with a first load
                arrival date after the provided date.
            first_load_arrival_date_to: Return voyages with a first load
                arrival date up to the provided date.
            end_date_from: Return voyages with an end date after the provided
                date.
            end_date_to: Return voyages with an end date up to the provided
                date.
            market_info_rate_from: If provided, then only voyages that have
                market data and with rate greater than this will be returned.
            market_info_rate_to: If provided, then only voyages that have
                market data and with a lower rate will be returned.
            market_info_rate_type: If provided, then only voyages that have
                market data and with the same rate type will be returned.
            commercial_operator_id: If provided, then only voyages that have
                this commercial operator will be returned.
            charterer_id: If provided, then only voyages that have this
                charterer will be returned.
            voyage_horizon: If a VoyageHorizon is provided, then only voyages
                of that type will be returned.
            voyage_horizons: If a list of VoyageHorizon is provided then
                only voyages of that type will be returned.
            token: Token returned from the previous incremental call. If this
                is the first call, then it can be omitted.
            hide_event_details: If True, then event details will be excluded.
            hide_events: If True, then events will be excluded.
            hide_market_info: If True, then market information will be
                excluded.

        Returns:
            Voyages data in condensed format as a tupple.
        """
        if event_horizon is not None:
            if event_horizons is None:
                event_horizons = []
            event_horizons.append(event_horizon)

        if event_purpose is not None:
            if event_purposes is None:
                event_purposes = []
            event_purposes.append(event_purpose)

        if vessel_class_id is not None:
            if vessel_class_ids is None:
                vessel_class_ids = []
            vessel_class_ids.append(vessel_class_id)

        if port_id is not None:
            if port_ids is None:
                port_ids = []
            port_ids.append(port_id)

        if voyage_horizon is not None:
            if voyage_horizons is None:
                voyage_horizons = []
            voyage_horizons.append(voyage_horizon)
        endpoint = self._get_endpoint(
            imo=imos,
            voyage_keys=voyage_keys,
            event_type=event_type,
            event_horizons=event_horizons,
            event_purpose=event_purposes,
            vessel_class_id=vessel_class_ids,
            port_ids=port_ids,
            vessel_type_id=vessel_type_id,
            voyage_date_from=start_date_from,
            voyage_date_to=start_date_from,
            start_date_from=start_date_from,
            start_date_to=start_date_to,
            first_load_arrival_date_from=first_load_arrival_date_from,
            first_load_arrival_date_to=first_load_arrival_date_to,
            end_date_from=end_date_from,
            end_date_to=end_date_to,
            market_info_rate_from=market_info_rate_from,
            market_info_rate_to=market_info_rate_to,
            market_info_rate_type=market_info_rate_type,
            commercial_operator_id=commercial_operator_id,
            charterer_id=charterer_id,
            voyage_horizon=voyage_horizons,
            token=token,
            hide_event_details=hide_event_details,
            hide_events=hide_events,
            hide_market_info=hide_market_info,
            nested=False,
            condensed=True
        )
        results, _ = self._get_voyages_condensed_pages(endpoint)
        return results

    def get_vessel_classes(
        self, class_filter: Optional[VesselClassFilter] = None
    ) -> Tuple[VesselClass, ...]:
        """Retrieves available vessel classes.

        Args:
            class_filter: A filter used to find specific vessel classes. If
                not specified, returns all available vessel classes.

        Returns:
            A tuple of available vessel classes that match the filter.
        """
        response = self.__connection._make_get_request(
            "voyages-api/v4/filters/availableVesselClasses"
        )
        response.raise_for_status()

        classes = (parse_model(c, VesselClass) for c in response.json())
        class_filter = class_filter or VesselClassFilter()

        return tuple(class_filter._apply(classes))

    def get_vessel_types(
        self, type_filter: Optional[VesselTypeFilter] = None
    ) -> Tuple[VesselType, ...]:
        """Retrieves available vessel types.

        Args:
            type_filter: A filter used to find specific vessel types. If not
                specified, returns all available vessel types.

        Returns:
            A tuple of available vessel types that match the filter.
        """
        response = self.__connection._make_get_request(
            "voyages-api/v4/filters/availableVesselTypes"
        )
        response.raise_for_status()

        types = (parse_model(c, VesselType) for c in response.json())
        type_filter = type_filter or VesselTypeFilter()

        return tuple(type_filter._apply(types))

    def get_imos(
        self, vessel_filter: Optional[VesselFilter] = None
    ) -> Tuple[Vessel, ...]:
        """Retrieves available vessel types.

        Args:
            vessel_filter: A filter used to find specific vessel . If not
                specified, returns all available vessels .

        Returns:
            A tuple of available vessels that match the filter.
        """
        response = self.__connection._make_get_request(
            "voyages-api/v4/filters/availableVessels"
        )
        response.raise_for_status()

        vessels = (parse_model(c, Vessel) for c in response.json())
        vessel_filter = vessel_filter or VesselFilter()

        return tuple(vessel_filter._apply(vessels))

__init__(connection=None)

Initializes VoyagesAPI.

Parameters:

Name Type Description Default
connection Optional[Connection]

API connection configuration. If not provided, the default connection method is used.

 None
Source code in signal_ocean/voyages/voyages_api.py 
37
38
39
40
41
42
43
44
def __init__(self, connection: Optional[Connection] = None):
    """Initializes VoyagesAPI.

    Args:
        connection: API connection configuration. If not provided, the
            default connection method is used.
    """
    self.__connection = connection or Connection()

get_imos(vessel_filter=None)

Retrieves available vessel types.

Parameters:

Name Type Description Default
vessel_filter Optional[VesselFilter]

A filter used to find specific vessel . If not specified, returns all available vessels .

 None

Returns:

Type Description
Tuple[Vessel, ...]

A tuple of available vessels that match the filter.
Source code in signal_ocean/voyages/voyages_api.py 
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def get_imos(
    self, vessel_filter: Optional[VesselFilter] = None
) -> Tuple[Vessel, ...]:
    """Retrieves available vessel types.

    Args:
        vessel_filter: A filter used to find specific vessel . If not
            specified, returns all available vessels .

    Returns:
        A tuple of available vessels that match the filter.
    """
    response = self.__connection._make_get_request(
        "voyages-api/v4/filters/availableVessels"
    )
    response.raise_for_status()

    vessels = (parse_model(c, Vessel) for c in response.json())
    vessel_filter = vessel_filter or VesselFilter()

    return tuple(vessel_filter._apply(vessels))

get_incremental_voyages(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None, incremental_token=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None, then voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, then voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, then voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return voyages after provided date. If imo is specified, then date_from is treated as None.

 None
incremental_token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None

Returns:

Type Description
Tuple[Voyages, Optional[NextRequestToken]]

A tuple containing the returned voyages, including any deleted voyages, and the token for the next incremental request.
Source code in signal_ocean/voyages/voyages_api.py 
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
def get_incremental_voyages(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
    incremental_token: Optional[str] = None,
) -> Tuple[Voyages, Optional[NextRequestToken]]:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None,
            then voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, then voyages for all vessels are returned. If
            imo is specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, then voyages for all vessels are returned. If either
            imo or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return voyages after provided date. If imo is
            specified, then date_from is treated as None.
        incremental_token: Token returned from the previous incremental
            call. If this is the first call, then it can be omitted.

    Returns:
        A tuple containing the returned voyages, including any deleted \
        voyages, and the token for the next incremental request.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []
    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        voyage_date_from=date_from,
        nested=True,
        incremental=True
    )
    results = self._get_voyages_pages(endpoint, token=incremental_token)
    return results

get_incremental_voyages_condensed(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None, incremental_token=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None, then voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, then voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, then voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return voyages after provided date. If imo is specified, then date_from is treated as None.

 None
incremental_token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None

Returns:

Type Description
Tuple[VoyagesCondensed, Optional[NextRequestToken]]

A tuple containing the returned voyages in condensed format, including any deleted voyages, and the token for the next incremental request.
Source code in signal_ocean/voyages/voyages_api.py 
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
def get_incremental_voyages_condensed(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
    incremental_token: Optional[str] = None,
) -> Tuple[VoyagesCondensed, Optional[NextRequestToken]]:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None,
            then voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel class.
            If None, then voyages for all vessels are returned. If imo is
            specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, then voyages for all vessels are returned. If either
            imo or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return voyages after provided date. If imo is
            specified, then date_from is treated as None.
        incremental_token: Token returned from the previous incremental
            call. If this is the first call, then it can be omitted.

    Returns:
        A tuple containing the returned voyages in condensed format, \
        including any deleted voyages, and the token for the next \
        incremental request.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []
    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        voyage_date_from=date_from,
        nested=False,
        incremental=True,
        condensed=True
    )
    results = self._get_voyages_condensed_pages(
        endpoint, token=incremental_token
    )
    return results

get_incremental_voyages_flat(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None, incremental_token=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None, then voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return after the provided date. If imo is specified, then datevoyages_from is treated as None.

 None
incremental_token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None

Returns:

Type Description
Tuple[VoyagesFlat, Optional[NextRequestToken]]

A tuple containing the returned voyages in flat format, including any deleted voyages, and the token for the next incremental request.
Source code in signal_ocean/voyages/voyages_api.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
def get_incremental_voyages_flat(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
    incremental_token: Optional[str] = None,
) -> Tuple[VoyagesFlat, Optional[NextRequestToken]]:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None,
            then voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, voyages for all vessels are returned. If imo
            is specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, voyages for all vessels are returned. If either imo
            or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return  after the provided date. If imo is
            specified, then datevoyages_from is treated as None.
        incremental_token: Token returned from the previous incremental
            call. If this is the first call, then it can be omitted.

    Returns:
        A tuple containing the returned voyages in flat format, \
        including any deleted voyages, and the token for the next \
        incremental request.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []
    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        voyage_date_from=date_from,
        nested=False,
        incremental=True
    )
    results = self._get_voyages_flat_pages(
        endpoint, token=incremental_token
    )
    return results

get_vessel_classes(class_filter=None)

Retrieves available vessel classes.

Parameters:

Name Type Description Default
class_filter Optional[VesselClassFilter]

A filter used to find specific vessel classes. If not specified, returns all available vessel classes.

 None

Returns:

Type Description
Tuple[VesselClass, ...]

A tuple of available vessel classes that match the filter.
Source code in signal_ocean/voyages/voyages_api.py 
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
def get_vessel_classes(
    self, class_filter: Optional[VesselClassFilter] = None
) -> Tuple[VesselClass, ...]:
    """Retrieves available vessel classes.

    Args:
        class_filter: A filter used to find specific vessel classes. If
            not specified, returns all available vessel classes.

    Returns:
        A tuple of available vessel classes that match the filter.
    """
    response = self.__connection._make_get_request(
        "voyages-api/v4/filters/availableVesselClasses"
    )
    response.raise_for_status()

    classes = (parse_model(c, VesselClass) for c in response.json())
    class_filter = class_filter or VesselClassFilter()

    return tuple(class_filter._apply(classes))

get_vessel_types(type_filter=None)

Retrieves available vessel types.

Parameters:

Name Type Description Default
type_filter Optional[VesselTypeFilter]

A filter used to find specific vessel types. If not specified, returns all available vessel types.

 None

Returns:

Type Description
Tuple[VesselType, ...]

A tuple of available vessel types that match the filter.
Source code in signal_ocean/voyages/voyages_api.py 
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
def get_vessel_types(
    self, type_filter: Optional[VesselTypeFilter] = None
) -> Tuple[VesselType, ...]:
    """Retrieves available vessel types.

    Args:
        type_filter: A filter used to find specific vessel types. If not
            specified, returns all available vessel types.

    Returns:
        A tuple of available vessel types that match the filter.
    """
    response = self.__connection._make_get_request(
        "voyages-api/v4/filters/availableVesselTypes"
    )
    response.raise_for_status()

    types = (parse_model(c, VesselType) for c in response.json())
    type_filter = type_filter or VesselTypeFilter()

    return tuple(type_filter._apply(types))

get_voyages(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None, voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return voyages after provided date. If imo is specified, then date_from is ignored.

 None

Returns:

Type Description
Voyages

Voyages data as a tupple.
Source code in signal_ocean/voyages/voyages_api.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
def get_voyages(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
) -> Voyages:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None,
            voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, voyages for all vessels are returned. If
            imo is specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, voyages for all vessels are returned. If either imo
            or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return voyages after provided date. If imo is
            specified, then date_from is ignored.

    Returns:
        Voyages data as a tupple.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []

    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        start_date_from=date_from
    )
    results, _ = self._get_voyages_pages(endpoint)
    return results

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imos Optional[List[int]]

If a list of imos is provided then only voyages of these imos will be returned

 None
voyage_keys Optional[List[str]]

If provided only the voyages with the requested keys will be returned

 None
event_type Optional[int]

If an EventType is provided, then only voyages that include at least one event of this type will be returned.

 None
event_horizon Optional[int]

If an EventHorizon is provided, then only voyages of this event horizon will be returned.

 None
event_horizons Optional[List[int]]

If a list of EventHorizons is provided then only voyages that include at least one event of those types will be returned

 None
event_purpose Optional[str]

If an EventPurpose is provided, then only voyages that include at least one event of this purpose will be returned.

 None
event_purposes Optional[List[str]]

If a list of EventPurposes is provided then only voyages that include at least one event of this type will be returned

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, then voyages for all vessels are returned.

 None
vessel_class_ids Optional[List[int]]

If provided only voyages of those vessel classes will be returned.

 None
port_id Optional[int]

If PortId is provided then only voyages that contains at least one event at this port will be returned.

 None
port_ids Optional[List[int]]

If a list of ports is provided then only voyages that contains at least one event at those ports will be returned.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, then voyages for all vessels are returned.

 None
start_date_from Optional[date]

Return voyages after the provided voyage start date.

 None
start_date_to Optional[date]

Return voyages up to the provided voyage end date.

 None
first_load_arrival_date_from Optional[date]

Return voyages with a first load arrival date after the provided date.

 None
first_load_arrival_date_to Optional[date]

Return voyages with a first load arrival date up to the provided date.

 None
end_date_from Optional[date]

Return voyages with an end date after the provided date.

 None
end_date_to Optional[date]

Return voyages with an end date up to the provided date.

 None
market_info_rate_from Optional[date]

If provided, then only voyages that have market data and with rate greater than this will be returned.

 None
market_info_rate_to Optional[date]

If provided, then only voyages that have market data and with a lower rate will be returned.

 None
market_info_rate_type Optional[date]

If provided, then only voyages that have market data and with the same rate type will be returned.

 None
commercial_operator_id Optional[int]

If provided, then only voyages that have this commercial operator will be returned.

 None
charterer_id Optional[int]

If provided, then only voyages that have this charterer will be returned.

 None
voyage_horizon Optional[str]

If a VoyageHorizon is provided, then only voyages of that type will be returned.

 None
voyage_horizons Optional[List[str]]

If a list of VoyageHorizon is provided then only voyages of that type will be returned.

 None
token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None
hide_event_details Optional[bool]

If True, then event details will be excluded.

 None
hide_events Optional[bool]

If True, then events will be excluded.

 None
hide_market_info Optional[bool]

If True, then market information will be excluded.

 None

Returns:

Type Description
Voyages

Voyages data as a tupple.
Source code in signal_ocean/voyages/voyages_api.py 
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
def get_voyages_by_advanced_search(
    self,
    imos: Optional[List[int]] = None,
    voyage_keys: Optional[List[str]] = None,
    event_type: Optional[int] = None,
    event_horizon: Optional[int] = None,
    event_horizons: Optional[List[int]] = None,
    event_purpose: Optional[str] = None,
    event_purposes: Optional[List[str]] = None,
    vessel_class_id: Optional[int] = None,
    vessel_class_ids: Optional[List[int]] = None,
    port_id: Optional[int] = None,
    port_ids: Optional[List[int]] = None,
    vessel_type_id: Optional[int] = None,
    start_date_from: Optional[date] = None,
    start_date_to: Optional[date] = None,
    first_load_arrival_date_from: Optional[date] = None,
    first_load_arrival_date_to: Optional[date] = None,
    end_date_from: Optional[date] = None,
    end_date_to: Optional[date] = None,
    market_info_rate_from: Optional[date] = None,
    market_info_rate_to: Optional[date] = None,
    market_info_rate_type: Optional[date] = None,
    commercial_operator_id: Optional[int] = None,
    charterer_id: Optional[int] = None,
    voyage_horizon: Optional[str] = None,
    voyage_horizons: Optional[List[str]] = None,
    token: Optional[str] = None,
    hide_event_details: Optional[bool] = None,
    hide_events: Optional[bool] = None,
    hide_market_info: Optional[bool] = None,
) -> Voyages:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imos: If a list of imos is provided then only voyages of these
            imos will be returned
        voyage_keys: If provided only the voyages with the requested
            keys will be returned
        event_type: If an EventType is provided, then only voyages that
            include at least one event of this type will be returned.
        event_horizon: If an EventHorizon is provided, then only voyages
            of this event horizon will be returned.
        event_horizons: If a list of EventHorizons is provided then only
            voyages that include at least one event of those types
            will be returned
        event_purpose: If an EventPurpose is provided, then only voyages
            that include at least one event of this purpose will be
            returned.
        event_purposes: If a list of EventPurposes is provided then only
            voyages that include at least one event of this type
            will be returned
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, then voyages for all vessels are returned.
        vessel_class_ids: If provided only voyages of those vessel classes
            will be returned.
        port_id: If PortId is provided then only voyages that contains at
            least one event at this port will be returned.
        port_ids: If a list of ports is provided then only voyages that
            contains at least one event at those ports will be returned.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, then voyages for all vessels are returned.
        start_date_from: Return voyages after the provided voyage start
            date.
        start_date_to: Return voyages up to the provided voyage end date.
        first_load_arrival_date_from: Return voyages with a first load
            arrival date after the provided date.
        first_load_arrival_date_to: Return voyages with a first load
            arrival date up to the provided date.
        end_date_from: Return voyages with an end date after the provided
            date.
        end_date_to: Return voyages with an end date up to the provided
            date.
        market_info_rate_from: If provided, then only voyages that have
            market data and with rate greater than this will be returned.
        market_info_rate_to: If provided, then only voyages that have
            market data and with a lower rate will be returned.
        market_info_rate_type: If provided, then only voyages that have
            market data and with the same rate type will be returned.
        commercial_operator_id: If provided, then only voyages that have
            this commercial operator will be returned.
        charterer_id: If provided, then only voyages that have this
            charterer will be returned.
        voyage_horizon: If a VoyageHorizon is provided, then only voyages
            of that type will be returned.
        voyage_horizons: If a list of VoyageHorizon is provided then
            only voyages of that type will be returned.
        token: Token returned from the previous incremental call. If this
            is the first call, then it can be omitted.
        hide_event_details: If True, then event details will be excluded.
        hide_events: If True, then events will be excluded.
        hide_market_info: If True, then market information will be
            excluded.

    Returns:
        Voyages data as a tupple.
    """
    if event_horizon is not None:
        if event_horizons is None:
            event_horizons = []
        event_horizons.append(event_horizon)

    if event_purpose is not None:
        if event_purposes is None:
            event_purposes = []
        event_purposes.append(event_purpose)

    if vessel_class_id is not None:
        if vessel_class_ids is None:
            vessel_class_ids = []
        vessel_class_ids.append(vessel_class_id)

    if port_id is not None:
        if port_ids is None:
            port_ids = []
        port_ids.append(port_id)

    if voyage_horizon is not None:
        if voyage_horizons is None:
            voyage_horizons = []
        voyage_horizons.append(voyage_horizon)
    endpoint = self._get_endpoint(
        imo=imos,
        voyage_keys=voyage_keys,
        event_type=event_type,
        event_horizons=event_horizons,
        event_purpose=event_purposes,
        vessel_class_id=vessel_class_ids,
        port_ids=port_ids,
        vessel_type_id=vessel_type_id,
        start_date_from=start_date_from,
        start_date_to=start_date_to,
        first_load_arrival_date_from=first_load_arrival_date_from,
        first_load_arrival_date_to=first_load_arrival_date_to,
        end_date_from=end_date_from,
        end_date_to=end_date_to,
        market_info_rate_from=market_info_rate_from,
        market_info_rate_to=market_info_rate_to,
        market_info_rate_type=market_info_rate_type,
        commercial_operator_id=commercial_operator_id,
        charterer_id=charterer_id,
        voyage_horizon=voyage_horizons,
        token=token,
        hide_event_details=hide_event_details,
        hide_events=hide_events,
        hide_market_info=hide_market_info,
    )
    results, _ = self._get_voyages_pages(endpoint)
    return results

get_voyages_condensed(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return voyages after provided date. If imo is specified, then date_from is treated as None.

 None

Returns:

Type Description
VoyagesCondensed

A VoyagesCondensed object containing lists of voyages.
Source code in signal_ocean/voyages/voyages_api.py 
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
def get_voyages_condensed(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
) -> VoyagesCondensed:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None
            voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, voyages for all vessels are returned. If imo
            is specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, voyages for all vessels are returned. If either imo
            or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return voyages after provided date. If imo is
            specified, then date_from is treated as None.

    Returns:
        A VoyagesCondensed object containing lists of voyages.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []
    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        start_date_from=date_from,
        nested=False,
        condensed=True
    )
    results, _ = self._get_voyages_condensed_pages(endpoint)
    return results

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imos Optional[List[int]]

If a list of imos is provided then only voyages of these imos will be returned

 None
voyage_keys Optional[List[str]]

If provided only the voyages with the requested keys will be returned

 None
event_type Optional[int]

If an EventType is provided, then only voyages that include at least one event of this type will be returned.

 None
event_horizon Optional[int]

If an EventHorizon is provided, then only voyages of this event horizon will be returned.

 None
event_horizons Optional[List[int]]

If a list of EventHorizons is provided then only voyages that include at least one event of those types will be returned

 None
event_purpose Optional[str]

If an EventPurpose is provided, then only voyages that include at least one event of this purpose will be returned.

 None
event_purposes Optional[List[str]]

If a list of EventPurposes is provided then only voyages that include at least one event of this type will be returned

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, then voyages for all vessels are returned.

 None
vessel_class_ids Optional[List[int]]

If provided only voyages of those vessel classes will be returned.

 None
port_id Optional[int]

If PortId is provided then only voyages that contains at least one event at this port will be returned.

 None
port_ids Optional[List[int]]

If a list of ports is provided then only voyages that contains at least one event at those ports will be returned.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, then voyages for all vessels are returned.

 None
start_date_from Optional[date]

Return voyages after the provided voyage start date.

 None
start_date_to Optional[date]

Return voyages up to the provided voyage end date.

 None
first_load_arrival_date_from Optional[date]

Return voyages with a first load arrival date after the provided date.

 None
first_load_arrival_date_to Optional[date]

Return voyages with a first load arrival date up to the provided date.

 None
end_date_from Optional[date]

Return voyages with an end date after the provided date.

 None
end_date_to Optional[date]

Return voyages with an end date up to the provided date.

 None
market_info_rate_from Optional[date]

If provided, then only voyages that have market data and with rate greater than this will be returned.

 None
market_info_rate_to Optional[date]

If provided, then only voyages that have market data and with a lower rate will be returned.

 None
market_info_rate_type Optional[date]

If provided, then only voyages that have market data and with the same rate type will be returned.

 None
commercial_operator_id Optional[int]

If provided, then only voyages that have this commercial operator will be returned.

 None
charterer_id Optional[int]

If provided, then only voyages that have this charterer will be returned.

 None
voyage_horizon Optional[str]

If a VoyageHorizon is provided, then only voyages of that type will be returned.

 None
voyage_horizons Optional[List[str]]

If a list of VoyageHorizon is provided then only voyages of that type will be returned.

 None
token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None
hide_event_details Optional[bool]

If True, then event details will be excluded.

 None
hide_events Optional[bool]

If True, then events will be excluded.

 None
hide_market_info Optional[bool]

If True, then market information will be excluded.

 None

Returns:

Type Description
VoyagesCondensed

Voyages data in condensed format as a tupple.
Source code in signal_ocean/voyages/voyages_api.py 
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
def get_voyages_condensed_by_advanced_search(
    self,
    imos: Optional[List[int]] = None,
    voyage_keys: Optional[List[str]] = None,
    event_type: Optional[int] = None,
    event_horizon: Optional[int] = None,
    event_horizons: Optional[List[int]] = None,
    event_purpose: Optional[str] = None,
    event_purposes: Optional[List[str]] = None,
    vessel_class_id: Optional[int] = None,
    vessel_class_ids: Optional[List[int]] = None,
    port_id: Optional[int] = None,
    port_ids: Optional[List[int]] = None,
    vessel_type_id: Optional[int] = None,
    start_date_from: Optional[date] = None,
    start_date_to: Optional[date] = None,
    first_load_arrival_date_from: Optional[date] = None,
    first_load_arrival_date_to: Optional[date] = None,
    end_date_from: Optional[date] = None,
    end_date_to: Optional[date] = None,
    market_info_rate_from: Optional[date] = None,
    market_info_rate_to: Optional[date] = None,
    market_info_rate_type: Optional[date] = None,
    commercial_operator_id: Optional[int] = None,
    charterer_id: Optional[int] = None,
    voyage_horizon: Optional[str] = None,
    voyage_horizons: Optional[List[str]] = None,
    token: Optional[str] = None,
    hide_event_details: Optional[bool] = None,
    hide_events: Optional[bool] = None,
    hide_market_info: Optional[bool] = None,
) -> VoyagesCondensed:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imos: If a list of imos is provided then only voyages of these
            imos will be returned
        voyage_keys: If provided only the voyages with the requested
            keys will be returned
        event_type: If an EventType is provided, then only voyages that
            include at least one event of this type will be returned.
        event_horizon: If an EventHorizon is provided, then only voyages
            of this event horizon will be returned.
        event_horizons: If a list of EventHorizons is provided then only
            voyages that include at least one event of those types
            will be returned
        event_purpose: If an EventPurpose is provided, then only voyages
            that include at least one event of this purpose will be
            returned.
        event_purposes: If a list of EventPurposes is provided then only
            voyages that include at least one event of this type
            will be returned
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, then voyages for all vessels are returned.
        vessel_class_ids: If provided only voyages of those vessel classes
            will be returned.
        port_id: If PortId is provided then only voyages that contains at
            least one event at this port will be returned.
        port_ids: If a list of ports is provided then only voyages that
            contains at least one event at those ports will be returned.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, then voyages for all vessels are returned.
        start_date_from: Return voyages after the provided voyage start
            date.
        start_date_to: Return voyages up to the provided voyage end date.
        first_load_arrival_date_from: Return voyages with a first load
            arrival date after the provided date.
        first_load_arrival_date_to: Return voyages with a first load
            arrival date up to the provided date.
        end_date_from: Return voyages with an end date after the provided
            date.
        end_date_to: Return voyages with an end date up to the provided
            date.
        market_info_rate_from: If provided, then only voyages that have
            market data and with rate greater than this will be returned.
        market_info_rate_to: If provided, then only voyages that have
            market data and with a lower rate will be returned.
        market_info_rate_type: If provided, then only voyages that have
            market data and with the same rate type will be returned.
        commercial_operator_id: If provided, then only voyages that have
            this commercial operator will be returned.
        charterer_id: If provided, then only voyages that have this
            charterer will be returned.
        voyage_horizon: If a VoyageHorizon is provided, then only voyages
            of that type will be returned.
        voyage_horizons: If a list of VoyageHorizon is provided then
            only voyages of that type will be returned.
        token: Token returned from the previous incremental call. If this
            is the first call, then it can be omitted.
        hide_event_details: If True, then event details will be excluded.
        hide_events: If True, then events will be excluded.
        hide_market_info: If True, then market information will be
            excluded.

    Returns:
        Voyages data in condensed format as a tupple.
    """
    if event_horizon is not None:
        if event_horizons is None:
            event_horizons = []
        event_horizons.append(event_horizon)

    if event_purpose is not None:
        if event_purposes is None:
            event_purposes = []
        event_purposes.append(event_purpose)

    if vessel_class_id is not None:
        if vessel_class_ids is None:
            vessel_class_ids = []
        vessel_class_ids.append(vessel_class_id)

    if port_id is not None:
        if port_ids is None:
            port_ids = []
        port_ids.append(port_id)

    if voyage_horizon is not None:
        if voyage_horizons is None:
            voyage_horizons = []
        voyage_horizons.append(voyage_horizon)
    endpoint = self._get_endpoint(
        imo=imos,
        voyage_keys=voyage_keys,
        event_type=event_type,
        event_horizons=event_horizons,
        event_purpose=event_purposes,
        vessel_class_id=vessel_class_ids,
        port_ids=port_ids,
        vessel_type_id=vessel_type_id,
        voyage_date_from=start_date_from,
        voyage_date_to=start_date_from,
        start_date_from=start_date_from,
        start_date_to=start_date_to,
        first_load_arrival_date_from=first_load_arrival_date_from,
        first_load_arrival_date_to=first_load_arrival_date_to,
        end_date_from=end_date_from,
        end_date_to=end_date_to,
        market_info_rate_from=market_info_rate_from,
        market_info_rate_to=market_info_rate_to,
        market_info_rate_type=market_info_rate_type,
        commercial_operator_id=commercial_operator_id,
        charterer_id=charterer_id,
        voyage_horizon=voyage_horizons,
        token=token,
        hide_event_details=hide_event_details,
        hide_events=hide_events,
        hide_market_info=hide_market_info,
        nested=False,
        condensed=True
    )
    results, _ = self._get_voyages_condensed_pages(endpoint)
    return results

get_voyages_flat(imo=None, vessel_class_id=None, vessel_type_id=None, date_from=None)

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imo Optional[int]

Return only voyages for the provided vessel IMO. If None voyages for all vessels are returned.

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, voyages for all vessels are returned. If imo is specified, then vessel_class_id is ignored.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, voyages for all vessels are returned. If either imo or vessel_class_id is specified, then vessel_type_id is ignored.

 None
date_from Optional[date]

Return voyages after provided date. If imo is specified, then date_from is treated as None.

 None

Returns:

Type Description
Optional[VoyagesFlat]

A VoyagesFlat object containing lists of voyages, voyage events, voyage event details and voyage geos otherwise.
Source code in signal_ocean/voyages/voyages_api.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
def get_voyages_flat(
    self,
    imo: Optional[int] = None,
    vessel_class_id: Optional[int] = None,
    vessel_type_id: Optional[int] = None,
    date_from: Optional[date] = None,
) -> Optional[VoyagesFlat]:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imo: Return only voyages for the provided vessel IMO. If None
            voyages for all vessels are returned.
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, voyages for all vessels are returned. If imo
            is specified, then vessel_class_id is ignored.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, voyages for all vessels are returned. If either imo
            or vessel_class_id is specified, then vessel_type_id is
            ignored.
        date_from: Return voyages after provided date. If imo is
            specified, then date_from is treated as None.

    Returns:
        A VoyagesFlat object containing lists of voyages, voyage events, \
        voyage event details and voyage geos otherwise.
    """
    if vessel_class_id is not None:
        vcids = [vessel_class_id]
    else:
        vcids = []

    if imo is not None:
        imos = [imo]
    else:
        imos = []

    endpoint = self._get_endpoint(
        imo=imos,
        vessel_class_id=vcids,
        vessel_type_id=vessel_type_id,
        start_date_from=date_from,
        nested=False
    )
    results, _ = self._get_voyages_flat_pages(endpoint)
    return results

Retrieves all voyages filtered with the provided parameters.

Parameters:

Name Type Description Default
imos Optional[List[int]]

If a list of imos is provided then only voyages of these imos will be returned

 None
voyage_keys Optional[List[str]]

If provided only the voyages with the requested keys will be returned

 None
event_type Optional[int]

If an EventType is provided, then only voyages that include at least one event of this type will be returned.

 None
event_horizon Optional[int]

If an EventHorizon is provided, then only voyages of this event horizon will be returned.

 None
event_horizons Optional[List[int]]

If a list of EventHorizons is provided then only voyages that include at least one event of those types will be returned

 None
event_purpose Optional[str]

If an EventPurpose is provided, then only voyages that include at least one event of this purpose will be returned.

 None
event_purposes Optional[List[str]]

If a list of EventPurposes is provided then only voyages that include at least one event of this type will be returned

 None
vessel_class_id Optional[int]

Return only voyages for the provided vessel class. If None, then voyages for all vessels are returned.

 None
vessel_class_ids Optional[List[int]]

If provided only voyages of those vessel classes will be returned.

 None
port_id Optional[int]

If PortId is provided then only voyages that contains at least one event at this port will be returned.

 None
port_ids Optional[List[int]]

If a list of ports is provided then only voyages that contains at least one event at those ports will be returned.

 None
vessel_type_id Optional[int]

Return only voyages for the provided vessel type. If None, then voyages for all vessels are returned.

 None
start_date_from Optional[date]

Return voyages after the provided voyage start date.

 None
start_date_to Optional[date]

Return voyages up to the provided voyage end date.

 None
first_load_arrival_date_from Optional[date]

Return voyages with a first load arrival date after the provided date.

 None
first_load_arrival_date_to Optional[date]

Return voyages with a first load arrival date up to the provided date.

 None
end_date_from Optional[date]

Return voyages with an end date after the provided date.

 None
end_date_to Optional[date]

Return voyages with an end date up to the provided date.

 None
market_info_rate_from Optional[date]

If provided, then only voyages that have market data and with rate greater than this will be returned.

 None
market_info_rate_to Optional[date]

If provided, then only voyages that have market data and with a lower rate will be returned.

 None
market_info_rate_type Optional[date]

If provided, then only voyages that have market data and with the same rate type will be returned.

 None
commercial_operator_id Optional[int]

If provided, then only voyages that have this commercial operator will be returned.

 None
charterer_id Optional[int]

If provided, then only voyages that have this charterer will be returned.

 None
voyage_horizon Optional[str]

If a VoyageHorizon is provided, then only voyages of that type will be returned.

 None
voyage_horizons Optional[List[str]]

If a list of VoyageHorizon is provided then only voyages of that type will be returned.

 None
token Optional[str]

Token returned from the previous incremental call. If this is the first call, then it can be omitted.

 None
hide_event_details Optional[bool]

If True, then event details will be excluded.

 None
hide_events Optional[bool]

If True, then events will be excluded.

 None
hide_market_info Optional[bool]

If True, then market information will be excluded.

 None

Returns:

Type Description
VoyagesFlat

Voyages data in flat format as a tupple.
Source code in signal_ocean/voyages/voyages_api.py 
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
def get_voyages_flat_by_advanced_search(
    self,
    imos: Optional[List[int]] = None,
    voyage_keys: Optional[List[str]] = None,
    event_type: Optional[int] = None,
    event_horizon: Optional[int] = None,
    event_horizons: Optional[List[int]] = None,
    event_purpose: Optional[str] = None,
    event_purposes: Optional[List[str]] = None,
    vessel_class_id: Optional[int] = None,
    vessel_class_ids: Optional[List[int]] = None,
    port_id: Optional[int] = None,
    port_ids: Optional[List[int]] = None,
    vessel_type_id: Optional[int] = None,
    start_date_from: Optional[date] = None,
    start_date_to: Optional[date] = None,
    first_load_arrival_date_from: Optional[date] = None,
    first_load_arrival_date_to: Optional[date] = None,
    end_date_from: Optional[date] = None,
    end_date_to: Optional[date] = None,
    market_info_rate_from: Optional[date] = None,
    market_info_rate_to: Optional[date] = None,
    market_info_rate_type: Optional[date] = None,
    commercial_operator_id: Optional[int] = None,
    charterer_id: Optional[int] = None,
    voyage_horizon: Optional[str] = None,
    voyage_horizons: Optional[List[str]] = None,
    token: Optional[str] = None,
    hide_event_details: Optional[bool] = None,
    hide_events: Optional[bool] = None,
    hide_market_info: Optional[bool] = None,
) -> VoyagesFlat:
    """Retrieves all voyages filtered with the provided parameters.

    Args:
        imos: If a list of imos is provided then only voyages of these
            imos will be returned
        voyage_keys: If provided only the voyages with the requested
            keys will be returned
        event_type: If an EventType is provided, then only voyages that
            include at least one event of this type will be returned.
        event_horizon: If an EventHorizon is provided, then only voyages
            of this event horizon will be returned.
        event_horizons: If a list of EventHorizons is provided then only
            voyages that include at least one event of those types
            will be returned
        event_purpose: If an EventPurpose is provided, then only voyages
            that include at least one event of this purpose will be
            returned.
        event_purposes: If a list of EventPurposes is provided then only
            voyages that include at least one event of this type
            will be returned
        vessel_class_id: Return only voyages for the provided vessel
            class. If None, then voyages for all vessels are returned.
        vessel_class_ids: If provided only voyages of those vessel classes
            will be returned.
        port_id: If PortId is provided then only voyages that contains at
            least one event at this port will be returned.
        port_ids: If a list of ports is provided then only voyages that
            contains at least one event at those ports will be returned.
        vessel_type_id: Return only voyages for the provided vessel type.
            If None, then voyages for all vessels are returned.
        start_date_from: Return voyages after the provided voyage start
            date.
        start_date_to: Return voyages up to the provided voyage end date.
        first_load_arrival_date_from: Return voyages with a first load
            arrival date after the provided date.
        first_load_arrival_date_to: Return voyages with a first load
            arrival date up to the provided date.
        end_date_from: Return voyages with an end date after the provided
            date.
        end_date_to: Return voyages with an end date up to the provided
            date.
        market_info_rate_from: If provided, then only voyages that have
            market data and with rate greater than this will be returned.
        market_info_rate_to: If provided, then only voyages that have
            market data and with a lower rate will be returned.
        market_info_rate_type: If provided, then only voyages that have
            market data and with the same rate type will be returned.
        commercial_operator_id: If provided, then only voyages that have
            this commercial operator will be returned.
        charterer_id: If provided, then only voyages that have this
            charterer will be returned.
        voyage_horizon: If a VoyageHorizon is provided, then only voyages
            of that type will be returned.
        voyage_horizons: If a list of VoyageHorizon is provided then
            only voyages of that type will be returned.
        token: Token returned from the previous incremental call. If this
            is the first call, then it can be omitted.
        hide_event_details: If True, then event details will be excluded.
        hide_events: If True, then events will be excluded.
        hide_market_info: If True, then market information will be
            excluded.

    Returns:
        Voyages data in flat format as a tupple.
    """
    if event_horizon is not None:
        if event_horizons is None:
            event_horizons = []
        event_horizons.append(event_horizon)

    if event_purpose is not None:
        if event_purposes is None:
            event_purposes = []
        event_purposes.append(event_purpose)

    if vessel_class_id is not None:
        if vessel_class_ids is None:
            vessel_class_ids = []
        vessel_class_ids.append(vessel_class_id)

    if port_id is not None:
        if port_ids is None:
            port_ids = []
        port_ids.append(port_id)

    if voyage_horizon is not None:
        if voyage_horizons is None:
            voyage_horizons = []
        voyage_horizons.append(voyage_horizon)
    endpoint = self._get_endpoint(
        imo=imos,
        voyage_keys=voyage_keys,
        event_type=event_type,
        event_horizons=event_horizons,
        event_purpose=event_purposes,
        vessel_class_id=vessel_class_ids,
        port_ids=port_ids,
        vessel_type_id=vessel_type_id,
        voyage_date_from=start_date_from,
        voyage_date_to=start_date_to,
        start_date_from=start_date_from,
        start_date_to=start_date_to,
        first_load_arrival_date_from=first_load_arrival_date_from,
        first_load_arrival_date_to=first_load_arrival_date_to,
        end_date_from=end_date_from,
        end_date_to=end_date_to,
        market_info_rate_from=market_info_rate_from,
        market_info_rate_to=market_info_rate_to,
        market_info_rate_type=market_info_rate_type,
        commercial_operator_id=commercial_operator_id,
        charterer_id=charterer_id,
        voyage_horizon=voyage_horizons,
        token=token,
        hide_event_details=hide_event_details,
        hide_events=hide_events,
        hide_market_info=hide_market_info,
        nested=False
    )
    results, _ = self._get_voyages_flat_pages(endpoint)
    return results