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
time_delay_between_calls float

Minimum delay between API calls in seconds. Defaults to 0.5 for this client.
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 
 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
 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
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
        time_delay_between_calls (float): Minimum delay between API calls in
            seconds. Defaults to 0.5 for this client.
        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'
    """

    #: Resolving PubChem links is rate-sensitive; throttle by default.
    default_time_delay: float = 0.5

    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
            AuthenticationError: If the API key is missing, invalid, or lacks access.
            NotFoundError: If the requested identifier does not exist.
            RateLimitError: If the API rate limit is exceeded.
            APIError: For any other unsuccessful API response.

        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
            AuthenticationError: If the API key is missing, invalid, or lacks access.
            NotFoundError: If the requested identifier does not exist.
            RateLimitError: If the API rate limit is exceeded.
            APIError: For any other unsuccessful API response.

        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)

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
AuthenticationError

If the API key is missing, invalid, or lacks access.
NotFoundError

If the requested identifier does not exist.
RateLimitError

If the API rate limit is exceeded.
APIError

For any other unsuccessful API response.

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 
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
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
        AuthenticationError: If the API key is missing, invalid, or lacks access.
        NotFoundError: If the requested identifier does not exist.
        RateLimitError: If the API rate limit is exceeded.
        APIError: For any other unsuccessful API response.

    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
AuthenticationError

If the API key is missing, invalid, or lacks access.
NotFoundError

If the requested identifier does not exist.
RateLimitError

If the API rate limit is exceeded.
APIError

For any other unsuccessful API response.

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 
 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
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
        AuthenticationError: If the API key is missing, invalid, or lacks access.
        NotFoundError: If the requested identifier does not exist.
        RateLimitError: If the API rate limit is exceeded.
        APIError: For any other unsuccessful API response.

    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)