Skip to content

ChemSynonym

pycomptox.chemical.chemsynonym.ChemSynonym

Bases: CachedAPIClient

Client for accessing chemical synonym data from EPA CompTox Dashboard.

This class provides methods for retrieving chemical synonyms and alternative identifiers including: - Beilstein registry numbers - Alternate CAS Registry Numbers - Valid and good quality synonyms - Other synonym categories - Flat list or structured views

Parameters:

Name Type Description Default
api_key str

CompTox API key. If not provided, will attempt to load from saved configuration or COMPTOX_API_KEY environment variable.

 None
base_url str

Base URL for the CompTox API. Defaults to EPA's endpoint.

 DEFAULT_BASE_URL
time_delay_between_calls float, **kwargs

Delay in seconds between API calls for rate limiting. Default is 0.0 (no delay).

 None
Example

from pycomptox import ChemSynonym synonym_client = ChemSynonym()

Get synonyms for Bisphenol A

synonyms = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182") print(f"Valid names: {synonyms['valid']}")

Get flat list of synonyms

flat_synonyms = synonym_client.get_synonyms_by_dtxsid( ... "DTXSID7020182", ... projection="ccd-synonyms" ... )

Source code in src/pycomptox/chemical/chemsynonym.py 
 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
166
167
168
169
170
171
172
173
174
175
class ChemSynonym(CachedAPIClient):
    """
    Client for accessing chemical synonym data from EPA CompTox Dashboard.

    This class provides methods for retrieving chemical synonyms and alternative
    identifiers including:
    - Beilstein registry numbers
    - Alternate CAS Registry Numbers
    - Valid and good quality synonyms
    - Other synonym categories
    - Flat list or structured views

    Args:
        api_key (str, optional): CompTox API key. If not provided, will attempt
            to load from saved configuration or COMPTOX_API_KEY environment variable.
        base_url (str): Base URL for the CompTox API. Defaults to EPA's endpoint.
        time_delay_between_calls (float, **kwargs): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).

    Example:
        >>> from pycomptox import ChemSynonym
        >>> synonym_client = ChemSynonym()
        >>> 
        >>> # Get synonyms for Bisphenol A
        >>> synonyms = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
        >>> print(f"Valid names: {synonyms['valid']}")
        >>> 
        >>> # Get flat list of synonyms
        >>> flat_synonyms = synonym_client.get_synonyms_by_dtxsid(
        ...     "DTXSID7020182", 
        ...     projection="ccd-synonyms"
        ... )
    """

    def get_synonyms_by_dtxsid(
        self,
        dtxsid: str,
        projection: Optional[str] = None,
        use_cache: Optional[bool] = None,
    ) -> Dict[str, Any]:
        """
        Get synonyms for a chemical by DTXSID with optional projection.

        Fetches synonyms based on the specified projection. Available projections:
        - `ccd-synonyms`: Returns a flat list of synonym objects with quality ratings
        - `chemical-synonym-all` (default): Returns structured view with categorized synonyms

        GET /chemical/synonym/search/by-dtxsid/{dtxsid}

        Args:
            dtxsid (str): DSSTox Substance Identifier (e.g., "DTXSID7020182")
            projection (str, optional): Projection type ("ccd-synonyms" or None for default)

        Returns:
            Dict[str, Any]: Synonym data. Structure depends on projection:

            Default projection returns:
                - `beilstein` (List[str]): Beilstein registry numbers
                - `alternate` (List[str]): Alternate CAS Registry Numbers
                - `dtxsid` (str): DSSTox Substance Identifier
                - `pcCode` (str): PC code
                - `deleted` (List[str]): Deleted CAS Registry Numbers
                - `other` (List[str]): Other synonyms
                - `valid` (List[str]): Valid synonyms
                - `good` (List[str]): Good quality synonyms

            ccd-synonyms projection returns a list of:
                - `synonym` (str): Synonym text
                - `quality` (str): Quality rating

        Raises:
            ValueError: If DTXSID is not found or request fails
            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.

        Example:
            >>> synonym_client = ChemSynonym()
            >>> 
            >>> # Get structured synonyms
            >>> data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
            >>> print(f"Valid names: {data.get('valid', [])}")
            >>> print(f"Alternate CAS: {data.get('alternate', [])}")
            >>> 
            >>> # Get flat list with quality ratings
            >>> flat_data = synonym_client.get_synonyms_by_dtxsid(
            ...     "DTXSID7020182",
            ...     projection="ccd-synonyms"
            ... )
            >>> for item in flat_data[:5]:
            ...     print(f"{item.get('synonym')}: {item.get('quality')}")
        """
        params = {}
        if projection:
            params["projection"] = projection

        endpoint = f"chemical/synonym/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

    def get_synonyms_by_dtxsid_batch(
        self,
        dtxsid_list: List[str],
        use_cache: Optional[bool] = None,
    ) -> List[Dict[str, Any]]:
        """
        Get synonyms for multiple chemicals in a single batch request.

        Batch retrieval of synonym data for up to 1000 chemicals. More efficient
        than making individual requests when querying multiple chemicals.

        POST /chemical/synonym/search/by-dtxsid/

        Args:
            dtxsid_list (List[str]): List of DSSTox Substance Identifiers
                (maximum 1000 DTXSIDs)

        Returns:
            List[Dict[str, Any]]: List of synonym data dictionaries, each containing:
                - `beilstein` (List[str]): Beilstein registry numbers
                - `alternate` (List[str]): Alternate CAS Registry Numbers
                - `dtxsid` (str): DSSTox Substance Identifier
                - `pcCode` (str): PC code
                - `deleted` (List[str]): Deleted CAS Registry Numbers
                - `other` (List[str]): Other synonyms
                - `valid` (List[str]): Valid synonyms
                - `good` (List[str]): Good quality synonyms

        Raises:
            ValueError: If more than 1000 DTXSIDs provided or request fails
            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.

        Example:
            >>> synonym_client = ChemSynonym()
            >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
            >>> results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)
            >>> 
            >>> for data in results:
            ...     dtxsid = data.get("dtxsid", "")
            ...     valid_names = data.get("valid", [])
            ...     print(f"{dtxsid}: {len(valid_names)} valid synonyms")
            >>> 
            >>> # Find chemicals with alternate CAS numbers
            >>> for data in results:
            ...     alt_cas = data.get("alternate", [])
            ...     if alt_cas:
            ...         print(f"{data.get('dtxsid')}: {alt_cas}")
        """
        if len(dtxsid_list) > 1000:
            raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsid_list)}")

        endpoint = "chemical/synonym/search/by-dtxsid/"
        return self._make_cached_request(endpoint, method='POST', json=dtxsid_list, use_cache=use_cache)

get_synonyms_by_dtxsid(dtxsid, projection=None, use_cache=None)

Get synonyms for a chemical by DTXSID with optional projection.

Fetches synonyms based on the specified projection. Available projections: - ccd-synonyms: Returns a flat list of synonym objects with quality ratings - chemical-synonym-all (default): Returns structured view with categorized synonyms

GET /chemical/synonym/search/by-dtxsid/{dtxsid}

Parameters:

Name Type Description Default
dtxsid str

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

 required
projection str

Projection type ("ccd-synonyms" or None for default)

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: Synonym data. Structure depends on projection:
Dict[str, Any]

Default projection returns: - beilstein (List[str]): Beilstein registry numbers - alternate (List[str]): Alternate CAS Registry Numbers - dtxsid (str): DSSTox Substance Identifier - pcCode (str): PC code - deleted (List[str]): Deleted CAS Registry Numbers - other (List[str]): Other synonyms - valid (List[str]): Valid synonyms - good (List[str]): Good quality synonyms
Dict[str, Any]

ccd-synonyms projection returns a list of: - synonym (str): Synonym text - quality (str): Quality rating

Raises:

Type Description
ValueError

If DTXSID is not found or request fails
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.
Example

synonym_client = ChemSynonym()

Get structured synonyms

data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182") print(f"Valid names: {data.get('valid', [])}") print(f"Alternate CAS: {data.get('alternate', [])}")

Get flat list with quality ratings

flat_data = synonym_client.get_synonyms_by_dtxsid( ... "DTXSID7020182", ... projection="ccd-synonyms" ... ) for item in flat_data[:5]: ... print(f"{item.get('synonym')}: {item.get('quality')}")

Source code in src/pycomptox/chemical/chemsynonym.py 
 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
def get_synonyms_by_dtxsid(
    self,
    dtxsid: str,
    projection: Optional[str] = None,
    use_cache: Optional[bool] = None,
) -> Dict[str, Any]:
    """
    Get synonyms for a chemical by DTXSID with optional projection.

    Fetches synonyms based on the specified projection. Available projections:
    - `ccd-synonyms`: Returns a flat list of synonym objects with quality ratings
    - `chemical-synonym-all` (default): Returns structured view with categorized synonyms

    GET /chemical/synonym/search/by-dtxsid/{dtxsid}

    Args:
        dtxsid (str): DSSTox Substance Identifier (e.g., "DTXSID7020182")
        projection (str, optional): Projection type ("ccd-synonyms" or None for default)

    Returns:
        Dict[str, Any]: Synonym data. Structure depends on projection:

        Default projection returns:
            - `beilstein` (List[str]): Beilstein registry numbers
            - `alternate` (List[str]): Alternate CAS Registry Numbers
            - `dtxsid` (str): DSSTox Substance Identifier
            - `pcCode` (str): PC code
            - `deleted` (List[str]): Deleted CAS Registry Numbers
            - `other` (List[str]): Other synonyms
            - `valid` (List[str]): Valid synonyms
            - `good` (List[str]): Good quality synonyms

        ccd-synonyms projection returns a list of:
            - `synonym` (str): Synonym text
            - `quality` (str): Quality rating

    Raises:
        ValueError: If DTXSID is not found or request fails
        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.

    Example:
        >>> synonym_client = ChemSynonym()
        >>> 
        >>> # Get structured synonyms
        >>> data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
        >>> print(f"Valid names: {data.get('valid', [])}")
        >>> print(f"Alternate CAS: {data.get('alternate', [])}")
        >>> 
        >>> # Get flat list with quality ratings
        >>> flat_data = synonym_client.get_synonyms_by_dtxsid(
        ...     "DTXSID7020182",
        ...     projection="ccd-synonyms"
        ... )
        >>> for item in flat_data[:5]:
        ...     print(f"{item.get('synonym')}: {item.get('quality')}")
    """
    params = {}
    if projection:
        params["projection"] = projection

    endpoint = f"chemical/synonym/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

get_synonyms_by_dtxsid_batch(dtxsid_list, use_cache=None)

Get synonyms for multiple chemicals in a single batch request.

Batch retrieval of synonym data for up to 1000 chemicals. More efficient than making individual requests when querying multiple chemicals.

POST /chemical/synonym/search/by-dtxsid/

Parameters:

Name Type Description Default
dtxsid_list List[str]

List of DSSTox Substance Identifiers (maximum 1000 DTXSIDs)

 required

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: List of synonym data dictionaries, each containing: - beilstein (List[str]): Beilstein registry numbers - alternate (List[str]): Alternate CAS Registry Numbers - dtxsid (str): DSSTox Substance Identifier - pcCode (str): PC code - deleted (List[str]): Deleted CAS Registry Numbers - other (List[str]): Other synonyms - valid (List[str]): Valid synonyms - good (List[str]): Good quality synonyms

Raises:

Type Description
ValueError

If more than 1000 DTXSIDs provided or request fails
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.
Example

synonym_client = ChemSynonym() dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"] results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)

for data in results: ... dtxsid = data.get("dtxsid", "") ... valid_names = data.get("valid", []) ... print(f"{dtxsid}: {len(valid_names)} valid synonyms")

Find chemicals with alternate CAS numbers

for data in results: ... alt_cas = data.get("alternate", []) ... if alt_cas: ... print(f"{data.get('dtxsid')}: {alt_cas}")

Source code in src/pycomptox/chemical/chemsynonym.py 
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
166
167
168
169
170
171
172
173
174
175
def get_synonyms_by_dtxsid_batch(
    self,
    dtxsid_list: List[str],
    use_cache: Optional[bool] = None,
) -> List[Dict[str, Any]]:
    """
    Get synonyms for multiple chemicals in a single batch request.

    Batch retrieval of synonym data for up to 1000 chemicals. More efficient
    than making individual requests when querying multiple chemicals.

    POST /chemical/synonym/search/by-dtxsid/

    Args:
        dtxsid_list (List[str]): List of DSSTox Substance Identifiers
            (maximum 1000 DTXSIDs)

    Returns:
        List[Dict[str, Any]]: List of synonym data dictionaries, each containing:
            - `beilstein` (List[str]): Beilstein registry numbers
            - `alternate` (List[str]): Alternate CAS Registry Numbers
            - `dtxsid` (str): DSSTox Substance Identifier
            - `pcCode` (str): PC code
            - `deleted` (List[str]): Deleted CAS Registry Numbers
            - `other` (List[str]): Other synonyms
            - `valid` (List[str]): Valid synonyms
            - `good` (List[str]): Good quality synonyms

    Raises:
        ValueError: If more than 1000 DTXSIDs provided or request fails
        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.

    Example:
        >>> synonym_client = ChemSynonym()
        >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
        >>> results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)
        >>> 
        >>> for data in results:
        ...     dtxsid = data.get("dtxsid", "")
        ...     valid_names = data.get("valid", [])
        ...     print(f"{dtxsid}: {len(valid_names)} valid synonyms")
        >>> 
        >>> # Find chemicals with alternate CAS numbers
        >>> for data in results:
        ...     alt_cas = data.get("alternate", [])
        ...     if alt_cas:
        ...         print(f"{data.get('dtxsid')}: {alt_cas}")
    """
    if len(dtxsid_list) > 1000:
        raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsid_list)}")

    endpoint = "chemical/synonym/search/by-dtxsid/"
    return self._make_cached_request(endpoint, method='POST', json=dtxsid_list, use_cache=use_cache)