Skip to content

Package Documentation

Companies API Package.

Classes:

Name Description
CompaniesAPI

Represents Signal's Companies API.
Company

Represents a Company.

CompaniesAPI

Represents Signal's Companies API.

Source code in signal_ocean/companies/companies_api.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class CompaniesAPI:
    """Represents Signal's Companies API."""

    relative_url = "companies-api/v1/"

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

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

    def get_company(self, company_id: int) -> Optional[Company]:
        """Retrieves a company by its id.

        Args:
            company_id: Unique id of the company to retrieve.

        Returns:
            A company or None if no company with the specified id has
            been found.
        """
        url = urljoin(CompaniesAPI.relative_url, f"companies/{company_id}")
        return get_single(self.__connection, url, Company)

    def get_companies(self, name: Optional[str] = None) -> Tuple[Company, ...]:
        """Retrieves all available companies.

        Args:
            name: String to filter and return only companies the name
                of which contains the provided string. If None, all
                companies are returned.

        Returns:
            A tuple of all available companies.
        """
        endpoint = (
            "companies/all"
            if name is None
            else f"companies/searchByName/{name}"
        )
        url = urljoin(CompaniesAPI.relative_url, endpoint)
        return get_multiple(self.__connection, url, Company)

__init__(connection=None)

Initializes CompaniesAPI.

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/companies/companies_api.py 
15
16
17
18
19
20
21
22
def __init__(self, connection: Optional[Connection] = None):
    """Initializes CompaniesAPI.

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

get_companies(name=None)

Retrieves all available companies.

Parameters:

Name Type Description Default
name Optional[str]

String to filter and return only companies the name of which contains the provided string. If None, all companies are returned.

 None

Returns:

Type Description
Tuple[Company, ...]

A tuple of all available companies.
Source code in signal_ocean/companies/companies_api.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def get_companies(self, name: Optional[str] = None) -> Tuple[Company, ...]:
    """Retrieves all available companies.

    Args:
        name: String to filter and return only companies the name
            of which contains the provided string. If None, all
            companies are returned.

    Returns:
        A tuple of all available companies.
    """
    endpoint = (
        "companies/all"
        if name is None
        else f"companies/searchByName/{name}"
    )
    url = urljoin(CompaniesAPI.relative_url, endpoint)
    return get_multiple(self.__connection, url, Company)

get_company(company_id)

Retrieves a company by its id.

Parameters:

Name Type Description Default
company_id int

Unique id of the company to retrieve.

 required

Returns:

Type Description
Optional[Company]

A company or None if no company with the specified id has
Optional[Company]

been found.
Source code in signal_ocean/companies/companies_api.py 
24
25
26
27
28
29
30
31
32
33
34
35
def get_company(self, company_id: int) -> Optional[Company]:
    """Retrieves a company by its id.

    Args:
        company_id: Unique id of the company to retrieve.

    Returns:
        A company or None if no company with the specified id has
        been found.
    """
    url = urljoin(CompaniesAPI.relative_url, f"companies/{company_id}")
    return get_single(self.__connection, url, Company)

Company dataclass

Contains all details of a company.

Attributes:

Name Type Description
id int

Numeric unique ID identifying a maritime company.
updated_date datetime

Date, format YYYY-MM-DD HH:MM:SS, corresponding to the latest update.
company_name Optional[str]

String, official name of the maritime company.
website Optional[str]

String, website of the company.
fleet_list Optional[str]

String, link to the fleet list of the company if it has vessels under commercial management.
synonyms Optional[Tuple[str, ...]]

Strings representing synonyms, acronyms or other names the company goes by in the shipping market.
charterer_vessel_types Optional[Tuple[str, ...]]

String, indicates in which market segments the company operates as charterer. Possible VesselTypes are "Tanker, Dry, Containers, LNG, LPG".
commercial_operator_vessel_types Optional[Tuple[str, ...]]

String, indicates in which market segments the company operates as commercial operator, therefore commercially manages vessel. Possible VesselTypes are "Tanker, Dry, Containers, LNG, LPG".
geo_asset_owner_vessel_types Optional[Tuple[str, ...]]

String, indicates if the company owns specific facilities such as shipyards or refineries relative to a particular vessel type. Possible VesselTypes are "Tanker, Dry, Containers, LNG, LPG".
broker_vessel_types Optional[Tuple[str, ...]]

String, indicates for which market segments the company operates as broker. Possible VesselTypes are "Tanker, Dry, Containers, LNG, LPG".
port_agent_vessel_types Optional[Tuple[str, ...]]

String, indicates for which market segments the company operates as port agent. Possible VesselTypes are "Tanker, Dry, Containers, LNG, LPG".
parent_company_id Optional[int]

Companies can have parent-child relationships, that is being legally related and having common interests. This numeric ID corresponds to the parent company or umbrella under which the company is.
children_companies_ids Optional[Tuple[int, ...]]

ID(s) of all companies acting as children of the initial company. Please note that a company can either have parent or children. We do not support two degrees relationships.
Source code in signal_ocean/companies/models.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
@dataclass(frozen=True)
class Company:
    """Contains all details of a company.

    Attributes:
        id: Numeric unique ID identifying a maritime company.
        updated_date: Date, format YYYY-MM-DD HH:MM:SS, corresponding to the
            latest update.
        company_name: String, official name of the maritime company.
        website: String, website of the company.
        fleet_list: String, link to the fleet list of the company if it has
            vessels under commercial management.
        synonyms: Strings representing synonyms, acronyms or other names the
            company goes by in the shipping market.
        charterer_vessel_types: String, indicates in which market segments the
            company operates as charterer. Possible VesselTypes are "Tanker,
            Dry, Containers, LNG, LPG".
        commercial_operator_vessel_types: String, indicates in which market
            segments the company operates as commercial operator, therefore
            commercially manages vessel. Possible VesselTypes are "Tanker, Dry,
            Containers, LNG, LPG".
        geo_asset_owner_vessel_types: String, indicates if the company owns
            specific facilities such as shipyards or refineries relative to a
            particular vessel type. Possible VesselTypes are "Tanker, Dry,
            Containers, LNG, LPG".
        broker_vessel_types: String, indicates for which market segments the
            company operates as broker. Possible VesselTypes are "Tanker, Dry,
            Containers, LNG, LPG".
        port_agent_vessel_types: String, indicates for which market segments
            the company operates as port agent. Possible VesselTypes are
            "Tanker, Dry, Containers, LNG, LPG".
        parent_company_id: Companies can have parent-child relationships, that
            is being legally related and having common interests. This numeric
            ID corresponds to the parent company or umbrella under which the
            company is.
        children_companies_ids: ID(s) of all companies acting as children of
            the initial company. Please note that a company can either have
            parent or children. We do not support two degrees relationships.
    """

    id: int
    updated_date: datetime
    company_name: Optional[str] = None
    website: Optional[str] = None
    fleet_list: Optional[str] = None
    synonyms: Optional[Tuple[str, ...]] = None
    charterer_vessel_types: Optional[Tuple[str, ...]] = None
    commercial_operator_vessel_types: Optional[Tuple[str, ...]] = None
    geo_asset_owner_vessel_types: Optional[Tuple[str, ...]] = None
    broker_vessel_types: Optional[Tuple[str, ...]] = None
    port_agent_vessel_types: Optional[Tuple[str, ...]] = None
    parent_company_id: Optional[int] = None
    children_companies_ids: Optional[Tuple[int, ...]] = None