Skip to content

PubChemLink API Reference

Bases: CachedAPIClient

Client for accessing PubChem GHS Safety Data Link information from the CompTox Dashboard API.

This class provides methods to check whether chemicals have GHS (Globally Harmonized System) safety data available on PubChem.

Attributes:

Name Type Description
base_url str

Base URL for the CompTox Dashboard API
api_key Optional[str]

API key for authentication
rate_limit_delay float

Minimum delay between API calls in seconds
session Session

HTTP session for making requests

Examples:

>>> from pycomptox import PubChemLink
>>> client = PubChemLink()
>>> result = client.check_existence_by_dtxsid("DTXSID7020182")
>>> print(result['isSafetyData'])
True
>>> print(result['safetyUrl'])
'https://pubchem.ncbi.nlm.nih.gov/compound/DTXSID7020182#section=GHS-Classification'
Source code in src/pycomptox/chemical/pubchemlink.py 
 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
 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
class PubChemLink(CachedAPIClient):
    """
    Client for accessing PubChem GHS Safety Data Link information from the CompTox Dashboard API.

    This class provides methods to check whether chemicals have GHS (Globally Harmonized System)
    safety data available on PubChem.

    Attributes:
        base_url (str): Base URL for the CompTox Dashboard API
        api_key (Optional[str]): API key for authentication
        rate_limit_delay (float): Minimum delay between API calls in seconds
        session (requests.Session): HTTP session for making requests

    Examples:
        >>> from pycomptox import PubChemLink
        >>> client = PubChemLink()
        >>> result = client.check_existence_by_dtxsid("DTXSID7020182")
        >>> print(result['isSafetyData'])
        True
        >>> print(result['safetyUrl'])
        'https://pubchem.ncbi.nlm.nih.gov/compound/DTXSID7020182#section=GHS-Classification'
    """

    def __init__(
        self,
        api_key: Optional[str] = None,
        rate_limit_delay: float = 0.5,
        base_url: str = "https://comptox.epa.gov/ctx-api",
        **kwargs
    ):
        """
        Initialize the PubChemLink client.

        Args:
            api_key: Optional API key for authentication. If not provided,
                    will attempt to load from saved configuration.
            rate_limit_delay: Minimum delay between API calls in seconds (default: 0.5)
            base_url: Base URL for the CompTox Dashboard API
            **kwargs: Additional arguments for CachedAPIClient

        Examples:
            >>> # Initialize with default settings (loads saved API key)
            >>> client = PubChemLink()

            >>> # Initialize with custom API key
            >>> client = PubChemLink(api_key="your-api-key-here")

            >>> # Initialize with custom rate limiting
            >>> client = PubChemLink(rate_limit_delay=1.0)
        """
        super().__init__(
            api_key=api_key,
            base_url=base_url,
            time_delay_between_calls=rate_limit_delay,
            **kwargs
        )

    def check_existence_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Check if PubChem has GHS Safety data for a chemical identified by DTXSID.

        This method queries the CompTox Dashboard API to determine whether PubChem
        contains GHS (Globally Harmonized System) safety data for the specified chemical.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., "DTXSID7020182")

        Returns:
            Dictionary containing:
                - dtxsid (str): The chemical's DTXSID
                - isSafetyData (bool): True if PubChem has GHS safety data
                - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

        Raises:
            ValueError: If dtxsid is empty or invalid format
            RuntimeError: If the API request fails

        Examples:
            >>> from pycomptox import PubChemLink
            >>> client = PubChemLink()

            >>> # Check for Bisphenol A
            >>> result = client.check_existence_by_dtxsid("DTXSID7020182")
            >>> print(f"Has PubChem data: {result['isSafetyData']}")
            Has PubChem data: True
            >>> print(f"URL: {result['safetyUrl']}")
            URL: https://pubchem.ncbi.nlm.nih.gov/compound/DTXSID7020182#section=GHS-Classification

            >>> # Check chemical without PubChem data
            >>> result = client.check_existence_by_dtxsid("DTXSID0000001")
            >>> print(f"Has PubChem data: {result['isSafetyData']}")
            Has PubChem data: False
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"chemical/ghslink/to-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def check_existence_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Check if PubChem has GHS Safety data for multiple chemicals by DTXSID.

        This method performs a batch query to check PubChem GHS safety data availability
        for multiple chemicals at once. This is more efficient than making individual
        requests for each chemical.

        Args:
            dtxsids: List of DSSTox Substance Identifiers (e.g., ["DTXSID7020182", "DTXSID2021315"])
                    Maximum 1000 DTXSIDs per request.

        Returns:
            List of dictionaries, each containing:
                - dtxsid (str): The chemical's DTXSID
                - isSafetyData (bool): True if PubChem has GHS safety data
                - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

        Raises:
            ValueError: If dtxsids is empty, not a list, or contains more than 1000 items
            RuntimeError: If the API request fails

        Examples:
            >>> from pycomptox import PubChemLink
            >>> client = PubChemLink()

            >>> # Check multiple chemicals
            >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
            >>> results = client.check_existence_by_dtxsid_batch(dtxsids)
            >>> for result in results:
            ...     print(f"{result['dtxsid']}: {result['isSafetyData']}")
            DTXSID7020182: True
            DTXSID2021315: True
            DTXSID5020001: False

            >>> # Find chemicals with PubChem data
            >>> with_data = [r for r in results if r['isSafetyData']]
            >>> print(f"Found {len(with_data)} chemicals with PubChem GHS data")
            Found 2 chemicals with PubChem GHS data
        """
        if not dtxsids or not isinstance(dtxsids, list):
            raise ValueError("dtxsids must be a non-empty list")

        if len(dtxsids) > 1000:
            raise ValueError("Maximum 1000 DTXSIDs allowed per batch request")

        endpoint = "chemical/ghslink/to-dtxsid/"
        return self._make_cached_request(endpoint, method='POST', json=dtxsids, use_cache=use_cache)

__init__(api_key=None, rate_limit_delay=0.5, base_url='https://comptox.epa.gov/ctx-api', **kwargs)

Initialize the PubChemLink client.

Parameters:

Name Type Description Default
api_key Optional[str]

Optional API key for authentication. If not provided, will attempt to load from saved configuration.

 None
rate_limit_delay float

Minimum delay between API calls in seconds (default: 0.5)

 0.5
base_url str

Base URL for the CompTox Dashboard API

 'https://comptox.epa.gov/ctx-api'
**kwargs

Additional arguments for CachedAPIClient

 {}

Examples:

>>> # Initialize with default settings (loads saved API key)
>>> client = PubChemLink()

>>> # Initialize with custom API key
>>> client = PubChemLink(api_key="your-api-key-here")

>>> # Initialize with custom rate limiting
>>> client = PubChemLink(rate_limit_delay=1.0)
Source code in src/pycomptox/chemical/pubchemlink.py 
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
def __init__(
    self,
    api_key: Optional[str] = None,
    rate_limit_delay: float = 0.5,
    base_url: str = "https://comptox.epa.gov/ctx-api",
    **kwargs
):
    """
    Initialize the PubChemLink client.

    Args:
        api_key: Optional API key for authentication. If not provided,
                will attempt to load from saved configuration.
        rate_limit_delay: Minimum delay between API calls in seconds (default: 0.5)
        base_url: Base URL for the CompTox Dashboard API
        **kwargs: Additional arguments for CachedAPIClient

    Examples:
        >>> # Initialize with default settings (loads saved API key)
        >>> client = PubChemLink()

        >>> # Initialize with custom API key
        >>> client = PubChemLink(api_key="your-api-key-here")

        >>> # Initialize with custom rate limiting
        >>> client = PubChemLink(rate_limit_delay=1.0)
    """
    super().__init__(
        api_key=api_key,
        base_url=base_url,
        time_delay_between_calls=rate_limit_delay,
        **kwargs
    )

check_existence_by_dtxsid(dtxsid, use_cache=None)

Check if PubChem has GHS Safety data for a chemical identified by DTXSID.

This method queries the CompTox Dashboard API to determine whether PubChem contains GHS (Globally Harmonized System) safety data for the specified chemical.

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., "DTXSID7020182")

 required

Returns:

Type Description
Dict[str, Any]

Dictionary containing: - dtxsid (str): The chemical's DTXSID - isSafetyData (bool): True if PubChem has GHS safety data - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

Raises:

Type Description
ValueError

If dtxsid is empty or invalid format
RuntimeError

If the API request fails

Examples:

>>> from pycomptox import PubChemLink
>>> client = PubChemLink()

>>> # Check for Bisphenol A
>>> result = client.check_existence_by_dtxsid("DTXSID7020182")
>>> print(f"Has PubChem data: {result['isSafetyData']}")
Has PubChem data: True
>>> print(f"URL: {result['safetyUrl']}")
URL: https://pubchem.ncbi.nlm.nih.gov/compound/DTXSID7020182#section=GHS-Classification

>>> # Check chemical without PubChem data
>>> result = client.check_existence_by_dtxsid("DTXSID0000001")
>>> print(f"Has PubChem data: {result['isSafetyData']}")
Has PubChem data: False
Source code in src/pycomptox/chemical/pubchemlink.py 
 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
def check_existence_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Check if PubChem has GHS Safety data for a chemical identified by DTXSID.

    This method queries the CompTox Dashboard API to determine whether PubChem
    contains GHS (Globally Harmonized System) safety data for the specified chemical.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., "DTXSID7020182")

    Returns:
        Dictionary containing:
            - dtxsid (str): The chemical's DTXSID
            - isSafetyData (bool): True if PubChem has GHS safety data
            - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

    Raises:
        ValueError: If dtxsid is empty or invalid format
        RuntimeError: If the API request fails

    Examples:
        >>> from pycomptox import PubChemLink
        >>> client = PubChemLink()

        >>> # Check for Bisphenol A
        >>> result = client.check_existence_by_dtxsid("DTXSID7020182")
        >>> print(f"Has PubChem data: {result['isSafetyData']}")
        Has PubChem data: True
        >>> print(f"URL: {result['safetyUrl']}")
        URL: https://pubchem.ncbi.nlm.nih.gov/compound/DTXSID7020182#section=GHS-Classification

        >>> # Check chemical without PubChem data
        >>> result = client.check_existence_by_dtxsid("DTXSID0000001")
        >>> print(f"Has PubChem data: {result['isSafetyData']}")
        Has PubChem data: False
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"chemical/ghslink/to-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

check_existence_by_dtxsid_batch(dtxsids, use_cache=None)

Check if PubChem has GHS Safety data for multiple chemicals by DTXSID.

This method performs a batch query to check PubChem GHS safety data availability for multiple chemicals at once. This is more efficient than making individual requests for each chemical.

Parameters:

Name Type Description Default
dtxsids List[str]

List of DSSTox Substance Identifiers (e.g., ["DTXSID7020182", "DTXSID2021315"]) Maximum 1000 DTXSIDs per request.

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries, each containing: - dtxsid (str): The chemical's DTXSID - isSafetyData (bool): True if PubChem has GHS safety data - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

Raises:

Type Description
ValueError

If dtxsids is empty, not a list, or contains more than 1000 items
RuntimeError

If the API request fails

Examples:

>>> from pycomptox import PubChemLink
>>> client = PubChemLink()

>>> # Check multiple chemicals
>>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
>>> results = client.check_existence_by_dtxsid_batch(dtxsids)
>>> for result in results:
...     print(f"{result['dtxsid']}: {result['isSafetyData']}")
DTXSID7020182: True
DTXSID2021315: True
DTXSID5020001: False

>>> # Find chemicals with PubChem data
>>> with_data = [r for r in results if r['isSafetyData']]
>>> print(f"Found {len(with_data)} chemicals with PubChem GHS data")
Found 2 chemicals with PubChem GHS data
Source code in src/pycomptox/chemical/pubchemlink.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
def check_existence_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Check if PubChem has GHS Safety data for multiple chemicals by DTXSID.

    This method performs a batch query to check PubChem GHS safety data availability
    for multiple chemicals at once. This is more efficient than making individual
    requests for each chemical.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (e.g., ["DTXSID7020182", "DTXSID2021315"])
                Maximum 1000 DTXSIDs per request.

    Returns:
        List of dictionaries, each containing:
            - dtxsid (str): The chemical's DTXSID
            - isSafetyData (bool): True if PubChem has GHS safety data
            - safetyUrl (str): URL to the PubChem GHS classification page, or empty string if no data

    Raises:
        ValueError: If dtxsids is empty, not a list, or contains more than 1000 items
        RuntimeError: If the API request fails

    Examples:
        >>> from pycomptox import PubChemLink
        >>> client = PubChemLink()

        >>> # Check multiple chemicals
        >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
        >>> results = client.check_existence_by_dtxsid_batch(dtxsids)
        >>> for result in results:
        ...     print(f"{result['dtxsid']}: {result['isSafetyData']}")
        DTXSID7020182: True
        DTXSID2021315: True
        DTXSID5020001: False

        >>> # Find chemicals with PubChem data
        >>> with_data = [r for r in results if r['isSafetyData']]
        >>> print(f"Found {len(with_data)} chemicals with PubChem GHS data")
        Found 2 chemicals with PubChem GHS data
    """
    if not dtxsids or not isinstance(dtxsids, list):
        raise ValueError("dtxsids must be a non-empty list")

    if len(dtxsids) > 1000:
        raise ValueError("Maximum 1000 DTXSIDs allowed per batch request")

    endpoint = "chemical/ghslink/to-dtxsid/"
    return self._make_cached_request(endpoint, method='POST', json=dtxsids, use_cache=use_cache)