Skip to content

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 
55
56
57
58
59
60
61
62
63
64
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 CAS numbers that cannot be resolved. When True, such errors are absorbed and those substances are simply omitted from the result, so fewer substances may be returned than CAS numbers requested. When None (default), the server default applies.

 None

Returns:

Type Description
list[SubstanceInfo]

The substances found for the given CAS numbers.
Source code in src/albert/collections/substance.py 
 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
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 CAS numbers that cannot be resolved. When True, such
        errors are absorbed and those substances are simply omitted from the
        result, so fewer substances may be returned than CAS numbers
        requested. When None (default), the server default applies.

    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 CAS number that cannot be resolved. When True, the error is absorbed and None is returned instead. When None (default), the server default applies.

 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 
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
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 CAS number that cannot be resolved. When True, the
        error is absorbed and None is returned instead. When None (default),
        the server default applies.

    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