Skip to content

Extra Data API Reference

pycomptox.chemical.extradata.ExtraData

Bases: CachedAPIClient

Client for accessing chemical extra data from EPA CompTox Dashboard.

This class provides methods for retrieving reference counts and additional metadata for chemicals including: - Total reference counts - Literature references - PubMed citations - Google Patent references

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 ExtraData extra = ExtraData()

Get extra data for Bisphenol A

data = extra.get_data_by_dtxsid("DTXSID7020182") print(f"PubMed refs: {data['pubmed']}") print(f"Patents: {data['googlePatent']}")

Source code in src/pycomptox/chemical/extradata.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
class ExtraData(CachedAPIClient):
    """
    Client for accessing chemical extra data from EPA CompTox Dashboard.

    This class provides methods for retrieving reference counts and
    additional metadata for chemicals including:
    - Total reference counts
    - Literature references
    - PubMed citations
    - Google Patent references

    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 ExtraData
        >>> extra = ExtraData()
        >>> 
        >>> # Get extra data for Bisphenol A
        >>> data = extra.get_data_by_dtxsid("DTXSID7020182")
        >>> print(f"PubMed refs: {data['pubmed']}")
        >>> print(f"Patents: {data['googlePatent']}")
    """

    def get_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get extra reference data for a chemical by DTXSID.

        Returns counts of various reference sources including literature,
        PubMed citations, Google Patents, and total reference counts.

        Args:
            dtxsid (str): CompTox substance identifier (e.g., "DTXSID7020182")

        Returns:
            dict: Extra data with fields:
                - dtxsid: DSSTox Substance Identifier
                - dtxcid: DSSTox Compound Identifier
                - refs: Total reference count
                - googlePatent: Number of Google Patent references
                - literature: Number of literature references
                - pubmed: Number of PubMed citations

        Raises:
            NotFoundError: If the chemical is not found.
            ValueError: If the DTXSID is not a valid non-empty string.
            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:
            >>> extra = ExtraData()
            >>> data = extra.get_data_by_dtxsid("DTXSID7020182")
            >>> print(f"DTXSID: {data['dtxsid']}")
            >>> print(f"Total references: {data['refs']}")
            >>> print(f"PubMed citations: {data['pubmed']}")
            >>> print(f"Patents: {data['googlePatent']}")
            >>> print(f"Literature: {data['literature']}")
        """
        endpoint = f"chemical/extra-data/search/by-dtxsid/{dtxsid}"
        result = self._make_cached_request(endpoint, use_cache=use_cache)
        # API returns a list, return first element if available
        if isinstance(result, list) and len(result) > 0:
            return result[0]
        return result

    def get_data_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get extra reference data for multiple chemicals in a single request.

        Batch retrieval of reference counts and metadata for up to 1000 chemicals.
        More efficient than making individual requests when querying multiple chemicals.

        Args:
            dtxsids (List[str]): List of CompTox substance identifiers
                (maximum 1000 DTXSIDs)

        Returns:
            List[dict]: List of extra data dictionaries, each containing:
                - `dtxsid`: DSSTox Substance Identifier
                - `dtxcid`: DSSTox Compound Identifier
                - `refs`: Total reference count
                - `googlePatent`: Number of Google Patent references
                - `literature`: Number of literature references
                - `pubmed`: Number of PubMed citations

        Raises:
            ValueError: If more than 1000 DTXSIDs provided
            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:
            >>> extra = ExtraData()
            >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
            >>> results = extra.get_data_by_dtxsid_batch(dtxsids)
            >>> 
            >>> for data in results:
            ...     pubmed_count = data.get("pubmed", 0)
            ...     dtxsid = data.get("dtxsid", "")
            ...     print(f"{dtxsid}: {pubmed_count} PubMed refs")
            >>> 
            >>> # Find chemicals with most references
            >>> sorted_data = sorted(results, key=lambda x: x.get("refs", 0), reverse=True)
            >>> top = sorted_data[0]
            >>> print(f"Most referenced: {top.get('dtxsid')} with {top.get('refs')} refs")
        """
        if len(dtxsids) > 1000:
            raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsids)}")

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

get_data_by_dtxsid(dtxsid, use_cache=None)

Get extra reference data for a chemical by DTXSID.

Returns counts of various reference sources including literature, PubMed citations, Google Patents, and total reference counts.

Parameters:

Name Type Description Default
dtxsid str

CompTox substance identifier (e.g., "DTXSID7020182")

 required

Returns:

Name Type Description
dict Dict[str, Any]

Extra data with fields: - dtxsid: DSSTox Substance Identifier - dtxcid: DSSTox Compound Identifier - refs: Total reference count - googlePatent: Number of Google Patent references - literature: Number of literature references - pubmed: Number of PubMed citations

Raises:

Type Description
NotFoundError

If the chemical is not found.
ValueError

If the DTXSID is not a valid non-empty string.
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

extra = ExtraData() data = extra.get_data_by_dtxsid("DTXSID7020182") print(f"DTXSID: {data['dtxsid']}") print(f"Total references: {data['refs']}") print(f"PubMed citations: {data['pubmed']}") print(f"Patents: {data['googlePatent']}") print(f"Literature: {data['literature']}")

Source code in src/pycomptox/chemical/extradata.py 
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
def get_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get extra reference data for a chemical by DTXSID.

    Returns counts of various reference sources including literature,
    PubMed citations, Google Patents, and total reference counts.

    Args:
        dtxsid (str): CompTox substance identifier (e.g., "DTXSID7020182")

    Returns:
        dict: Extra data with fields:
            - dtxsid: DSSTox Substance Identifier
            - dtxcid: DSSTox Compound Identifier
            - refs: Total reference count
            - googlePatent: Number of Google Patent references
            - literature: Number of literature references
            - pubmed: Number of PubMed citations

    Raises:
        NotFoundError: If the chemical is not found.
        ValueError: If the DTXSID is not a valid non-empty string.
        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:
        >>> extra = ExtraData()
        >>> data = extra.get_data_by_dtxsid("DTXSID7020182")
        >>> print(f"DTXSID: {data['dtxsid']}")
        >>> print(f"Total references: {data['refs']}")
        >>> print(f"PubMed citations: {data['pubmed']}")
        >>> print(f"Patents: {data['googlePatent']}")
        >>> print(f"Literature: {data['literature']}")
    """
    endpoint = f"chemical/extra-data/search/by-dtxsid/{dtxsid}"
    result = self._make_cached_request(endpoint, use_cache=use_cache)
    # API returns a list, return first element if available
    if isinstance(result, list) and len(result) > 0:
        return result[0]
    return result

get_data_by_dtxsid_batch(dtxsids, use_cache=None)

Get extra reference data for multiple chemicals in a single request.

Batch retrieval of reference counts and metadata for up to 1000 chemicals. More efficient than making individual requests when querying multiple chemicals.

Parameters:

Name Type Description Default
dtxsids List[str]

List of CompTox substance identifiers (maximum 1000 DTXSIDs)

 required

Returns:

Type Description
List[Dict[str, Any]]

List[dict]: List of extra data dictionaries, each containing: - dtxsid: DSSTox Substance Identifier - dtxcid: DSSTox Compound Identifier - refs: Total reference count - googlePatent: Number of Google Patent references - literature: Number of literature references - pubmed: Number of PubMed citations

Raises:

Type Description
ValueError

If more than 1000 DTXSIDs provided
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

extra = ExtraData() dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"] results = extra.get_data_by_dtxsid_batch(dtxsids)

for data in results: ... pubmed_count = data.get("pubmed", 0) ... dtxsid = data.get("dtxsid", "") ... print(f"{dtxsid}: {pubmed_count} PubMed refs")

Find chemicals with most references

sorted_data = sorted(results, key=lambda x: x.get("refs", 0), reverse=True) top = sorted_data[0] print(f"Most referenced: {top.get('dtxsid')} with {top.get('refs')} refs")

Source code in src/pycomptox/chemical/extradata.py 
 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
def get_data_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get extra reference data for multiple chemicals in a single request.

    Batch retrieval of reference counts and metadata for up to 1000 chemicals.
    More efficient than making individual requests when querying multiple chemicals.

    Args:
        dtxsids (List[str]): List of CompTox substance identifiers
            (maximum 1000 DTXSIDs)

    Returns:
        List[dict]: List of extra data dictionaries, each containing:
            - `dtxsid`: DSSTox Substance Identifier
            - `dtxcid`: DSSTox Compound Identifier
            - `refs`: Total reference count
            - `googlePatent`: Number of Google Patent references
            - `literature`: Number of literature references
            - `pubmed`: Number of PubMed citations

    Raises:
        ValueError: If more than 1000 DTXSIDs provided
        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:
        >>> extra = ExtraData()
        >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
        >>> results = extra.get_data_by_dtxsid_batch(dtxsids)
        >>> 
        >>> for data in results:
        ...     pubmed_count = data.get("pubmed", 0)
        ...     dtxsid = data.get("dtxsid", "")
        ...     print(f"{dtxsid}: {pubmed_count} PubMed refs")
        >>> 
        >>> # Find chemicals with most references
        >>> sorted_data = sorted(results, key=lambda x: x.get("refs", 0), reverse=True)
        >>> top = sorted_data[0]
        >>> print(f"Most referenced: {top.get('dtxsid')} with {top.get('refs')} refs")
    """
    if len(dtxsids) > 1000:
        raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsids)}")

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