Substances

albert.collections.substance.SubstanceCollection

SubstanceCollection(*, session: AlbertSession)

Bases: BaseCollection

Look up regulatory and hazard information for chemical substances.

A Substance is the regulatory/compliance profile of a chemical, keyed by its CAS number. Each SubstanceInfo bundles the data Albert holds for that chemical, including GHS hazard classifications, toxicity and ecotoxicity data, exposure limits, physical properties, and membership on regulatory lists across many jurisdictions. Results can be scoped to a region, since regulatory status varies by country.

Substances are read-only reference data: this collection only retrieves information and does not create or modify it. They are addressed by CAS number (e.g. "64-17-5") rather than by an Albert ID, and relate to Cas records used elsewhere in the platform.

This collection is accessed as client.substances.

Example

from albert import Albert

client = Albert()
substance = client.substances.get_by_id(cas_id="64-17-5")
substance.cas_id
# '64-17-5'

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 substance requests.

Methods:

Name	Description
get_by_ids	Get regulatory information for several CAS numbers at once.
get_by_id	Get regulatory information for a single CAS number.

Parameters:

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

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

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

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

base_path

base_path = (
    f"/api/{SubstanceCollection._api_version}/substances"
)

get_by_ids

get_by_ids(
    *,
    cas_ids: list[str],
    region: str = "US",
    catch_errors: bool | None = None,
) -> list[SubstanceInfo]

Get regulatory information for several CAS numbers at once.

For a single CAS number, use get_by_id.

Example

from albert import Albert

client = Albert()
substances = client.substances.get_by_ids(cas_ids=["64-17-5", "67-64-1"])
[s.cas_id for s in substances]
# ['64-17-5', '67-64-1']

Parameters:

Name	Type	Description	Default
cas_ids	list[str]	The CAS numbers to retrieve substances for (e.g. ["64-17-5"]).	required
region	str	The region to scope regulatory status to. Defaults to "US".	'US'
catch_errors	bool	How to handle requested substances that are missing hazard data. When True, the request fails if any requested substance is missing hazard data. When False, such errors are absorbed and the affected substances are omitted from the result, so fewer substances may be returned than CAS numbers requested. When None (default), the server default applies. Only governs missing hazard data; it does not affect how unknown CAS numbers are handled.	None

Returns:

Type	Description
list[SubstanceInfo]	The substances found for the given CAS numbers.

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

def get_by_ids(
    self,
    *,
    cas_ids: list[str],
    region: str = "US",
    catch_errors: bool | None = None,
) -> list[SubstanceInfo]:
    """Get regulatory information for several CAS numbers at once.

    For a single CAS number, use [`get_by_id`][albert.collections.substance.SubstanceCollection.get_by_id].

    !!! example
        ```python
        from albert import Albert

        client = Albert()
        substances = client.substances.get_by_ids(cas_ids=["64-17-5", "67-64-1"])
        [s.cas_id for s in substances]
        # ['64-17-5', '67-64-1']
        ```

    Parameters
    ----------
    cas_ids : list[str]
        The CAS numbers to retrieve substances for (e.g. ``["64-17-5"]``).
    region : str, optional
        The region to scope regulatory status to. Defaults to ``"US"``.
    catch_errors : bool, optional
        How to handle requested substances that are missing hazard data.
        When True, the request fails if any requested substance is missing
        hazard data. When False, such errors are absorbed and the affected
        substances are omitted from the result, so fewer substances may be
        returned than CAS numbers requested. When None (default), the server
        default applies. Only governs missing hazard data; it does not
        affect how unknown CAS numbers are handled.

    Returns
    -------
    list[SubstanceInfo]
        The substances found for the given CAS numbers.
    """
    params = {
        "casIDs": ",".join(cas_ids),
        "region": region,
        "catchErrors": json.dumps(catch_errors) if catch_errors is not None else None,
    }
    params = {k: v for k, v in params.items() if v is not None}
    response = self.session.get(self.base_path, params=params)
    return SubstanceResponse.model_validate(response.json()).substances

get_by_id

get_by_id(
    *,
    cas_id: str,
    region: str = "US",
    catch_errors: bool | None = None,
) -> SubstanceInfo | None

Get regulatory information for a single CAS number.

To look up several CAS numbers in one call, use get_by_ids.

Example

from albert import Albert

client = Albert()
substance = client.substances.get_by_id(cas_id="64-17-5")
substance.is_known
# True

Parameters:

Name	Type	Description	Default
cas_id	str	The CAS number of the substance to retrieve (e.g. "64-17-5").	required
region	str	The region to scope regulatory status to. Defaults to "US".	'US'
catch_errors	bool	How to handle a substance that is missing hazard data. When True, the request fails if the substance is missing hazard data. When False, the error is absorbed and None is returned instead. When None (default), the server default applies. Only governs missing hazard data; it does not affect how unknown CAS numbers are handled.	None

Returns:

Type	Description
SubstanceInfo or None	The fully populated substance, or None if it is not found.

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

def get_by_id(
    self,
    *,
    cas_id: str,
    region: str = "US",
    catch_errors: bool | None = None,
) -> SubstanceInfo | None:
    """Get regulatory information for a single CAS number.

    To look up several CAS numbers in one call, use [`get_by_ids`][albert.collections.substance.SubstanceCollection.get_by_ids].

    !!! example
        ```python
        from albert import Albert

        client = Albert()
        substance = client.substances.get_by_id(cas_id="64-17-5")
        substance.is_known
        # True
        ```

    Parameters
    ----------
    cas_id : str
        The CAS number of the substance to retrieve (e.g. ``"64-17-5"``).
    region : str, optional
        The region to scope regulatory status to. Defaults to ``"US"``.
    catch_errors : bool, optional
        How to handle a substance that is missing hazard data. When True,
        the request fails if the substance is missing hazard data. When
        False, the error is absorbed and None is returned instead. When None
        (default), the server default applies. Only governs missing hazard
        data; it does not affect how unknown CAS numbers are handled.

    Returns
    -------
    SubstanceInfo or None
        The fully populated substance, or None if it is not found.
    """
    results = self.get_by_ids(cas_ids=[cas_id], region=region, catch_errors=catch_errors)
    return results[0] if results else None