UN Numbers

albert.collections.un_numbers.UnNumberCollection

UnNumberCollection(*, session: AlbertSession)

Bases: BaseCollection

Look up UN Numbers in the Albert platform.

A UN Number is the four-digit United Nations identifier assigned to a hazardous material for transport (e.g. UN1090 for acetone). In Albert, UN Numbers carry the associated shipping and storage-class metadata used when classifying substances and inventory items for shipping. Use this collection to look them up by ID or name.

This collection is accessed as client.un_numbers.

Example

from albert import Albert

client = Albert()
un_number = client.un_numbers.get_by_name(name="UN1090")
un_number.shipping_description

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for UN Number requests.

Methods:

Name	Description
get_by_id	Get a single UN Number by its ID.
get_by_name	Get a UN Number by its exact name, or None if not found.
get_all	Iterate over UN Numbers, optionally filtered by name.
create	Not supported; UN Numbers cannot be created through the SDK.

Note

Creating UN Numbers is not supported via the SDK, as UN Numbers are highly controlled by Albert.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Source code in src/albert/collections/un_numbers.py

def __init__(self, *, session: AlbertSession):
    """Initialize a UnNumberCollection.

    Parameters
    ----------
    session : AlbertSession
        The authenticated Albert session used for API calls.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{UnNumberCollection._api_version}/unnumbers"

base_path

base_path = (
    f"/api/{UnNumberCollection._api_version}/unnumbers"
)

create

create() -> None

Not supported; UN Numbers cannot be created through the SDK.

UN Numbers are highly controlled by Albert and are managed centrally, so this method always raises.

Returns:

Type	Description
None

Raises:

Type	Description
NotImplementedError	Always, because UN Numbers cannot be created through the SDK.

Source code in src/albert/collections/un_numbers.py

def create(self) -> None:
    """Not supported; UN Numbers cannot be created through the SDK.

    UN Numbers are highly controlled by Albert and are managed centrally, so
    this method always raises.

    Returns
    -------
    None

    Raises
    ------
    NotImplementedError
        Always, because UN Numbers cannot be created through the SDK.
    """
    raise NotImplementedError()

get_by_id

get_by_id(*, id: str) -> UnNumber

Get a single UN Number by its ID.

Example

un_number = client.un_numbers.get_by_id(id="...")
un_number.un_number

Parameters:

Name	Type	Description	Default
id	str	The Albert ID of the UN Number to retrieve.	required

Returns:

Type	Description
UnNumber	The fully populated UN Number.

Source code in src/albert/collections/un_numbers.py

def get_by_id(self, *, id: str) -> UnNumber:
    """Get a single UN Number by its ID.

    !!! example
        ```python
        un_number = client.un_numbers.get_by_id(id="...")
        un_number.un_number
        ```

    Parameters
    ----------
    id : str
        The Albert ID of the UN Number to retrieve.

    Returns
    -------
    UnNumber
        The fully populated UN Number.
    """
    url = f"{self.base_path}/{id}"
    response = self.session.get(url)
    return UnNumber(**response.json())

get_by_name

get_by_name(*, name: str) -> UnNumber | None

Get a UN Number by its exact name.

Runs an exact-match lookup and returns the first result. To browse or do partial-name matching, use get_all.

Example

un_number = client.un_numbers.get_by_name(name="UN1090")
un_number.storage_class_name if un_number else "not found"

Parameters:

Name	Type	Description	Default
name	str	The exact name of the UN Number to retrieve.	required

Returns:

Type	Description
UnNumber | None	The matching UN Number, or None if no exact match is found.

Source code in src/albert/collections/un_numbers.py

def get_by_name(self, *, name: str) -> UnNumber | None:
    """Get a UN Number by its exact name.

    Runs an exact-match lookup and returns the first result. To browse or
    do partial-name matching, use [`get_all`][albert.collections.un_numbers.UnNumberCollection.get_all].

    !!! example
        ```python
        un_number = client.un_numbers.get_by_name(name="UN1090")
        un_number.storage_class_name if un_number else "not found"
        ```

    Parameters
    ----------
    name : str
        The exact name of the UN Number to retrieve.

    Returns
    -------
    UnNumber | None
        The matching UN Number, or None if no exact match is found.
    """
    found = self.get_all(exact_match=True, name=name)
    return next(found, None)

get_all

get_all(
    *,
    name: str | None = None,
    exact_match: bool = False,
    start_key: str | None = None,
    max_items: int | None = None,
) -> Iterator[UnNumber]

Iterate over UN Numbers, optionally filtered by name.

Results are returned as a lazily paginated iterator, so iterating fetches additional pages on demand. With no name, iterates over all UN Numbers.

Example

for un_number in client.un_numbers.get_all(name="acetone", max_items=10):
    print(un_number.un_number, un_number.shipping_description)

Parameters:

Name	Type	Description	Default
name	str	Filter to UN Numbers whose name matches. Combine with exact_match to control whether matching is exact or partial.	None
exact_match	bool	When True, return only exact name matches. Default False.	False
start_key	str	Pagination key of the first record to evaluate; used to resume paging.	None
max_items	int	Maximum number of items to return in total. If None, iterates over all matches.	None

Yields:

Type	Description
Iterator[UnNumber]	The UN Numbers matching the search criteria.

Source code in src/albert/collections/un_numbers.py

def get_all(
    self,
    *,
    name: str | None = None,
    exact_match: bool = False,
    start_key: str | None = None,
    max_items: int | None = None,
) -> Iterator[UnNumber]:
    """Iterate over UN Numbers, optionally filtered by name.

    Results are returned as a lazily paginated iterator, so iterating fetches
    additional pages on demand. With no ``name``, iterates over all UN Numbers.

    !!! example
        ```python
        for un_number in client.un_numbers.get_all(name="acetone", max_items=10):
            print(un_number.un_number, un_number.shipping_description)
        ```

    Parameters
    ----------
    name : str, optional
        Filter to UN Numbers whose name matches. Combine with ``exact_match``
        to control whether matching is exact or partial.
    exact_match : bool, optional
        When True, return only exact name matches. Default False.
    start_key : str, optional
        Pagination key of the first record to evaluate; used to resume paging.
    max_items : int, optional
        Maximum number of items to return in total. If None, iterates over all
        matches.

    Yields
    ------
    Iterator[UnNumber]
        The UN Numbers matching the search criteria.
    """
    params = {"startKey": start_key}
    if name:
        params["name"] = name
        params["exactMatch"] = exact_match

    return AlbertPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        session=self.session,
        params=params,
        max_items=max_items,
        deserialize=lambda items: [UnNumber(**item) for item in items],
    )