Skip to content

ProductData API Reference

pycomptox.exposure.productdata.ProductData

Bases: CachedAPIClient

Client for accessing product data from EPA CompTox Dashboard.

This class provides methods for retrieving information about consumer products that contain chemicals, including product use categories (PUC) and composition data.

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.

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

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

 0.0
Example

from pycomptox import ProductData prod_data = ProductData()

Get product data for a chemical

products = prod_data.products_data_by_dtxsid("DTXSID0020232")

Source code in src/pycomptox/exposure/productdata.py 
 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
class ProductData(CachedAPIClient):
    """
    Client for accessing product data from EPA CompTox Dashboard.

    This class provides methods for retrieving information about consumer products
    that contain chemicals, including product use categories (PUC) and composition data.

    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 ProductData
        >>> prod_data = ProductData()
        >>> 
        >>> # Get product data for a chemical
        >>> products = prod_data.products_data_by_dtxsid("DTXSID0020232")
    """

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

        Args:
            api_key: CompTox API key (optional, will be loaded from config if not provided)
            base_url: Base URL for the CompTox API
            time_delay_between_calls: Delay between API calls in seconds

        Raises:
            ValueError: If no API key is provided or found in configuration
        """
        super().__init__(
            api_key=api_key,
            base_url=base_url,
            time_delay_between_calls=time_delay_between_calls,
            **kwargs
        )

    def products_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get product data for a chemical.

        Retrieves information about consumer products that contain a specific chemical
        identified by its DSSTox Substance Identifier (DTXSID). This includes product
        names, manufacturers, product use categories (PUC), and composition information.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

        Returns:
            List of dictionaries containing product data. Each entry includes product
            information such as name, manufacturer, PUC classification, and chemical
            composition details.

        Raises:
            ValueError: If dtxsid is not a valid non-empty string

        Example:
            >>> prod_data = ProductData()
            >>> products = prod_data.products_data_by_dtxsid("DTXSID0020232")
            >>> for product in products:
            ...     print(f"{product.get('productName', 'N/A')}: {product.get('pucCode', 'N/A')}")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/product-data/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def list_all_puc_product(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get all Product Use Category (PUC) classifications.

        Retrieves a complete list of Product Use Category (PUC) codes and their
        definitions. PUCs provide a hierarchical classification system for categorizing
        consumer product types based on their use and function.

        Returns:
            List of dictionaries containing PUC information including codes,
            descriptions, and hierarchical relationships.

        Example:
            >>> prod_data = ProductData()
            >>> pucs = prod_data.list_all_puc_product()
            >>> for puc in pucs:
            ...     print(f"{puc.get('pucCode', 'N/A')}: {puc.get('pucDescription', '')}")
        """
        endpoint = "exposure/product-data/puc"
        return self._make_cached_request(endpoint, use_cache=use_cache)

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

        Retrieves product information for multiple chemicals at once using a batch
        API call. This is more efficient than making individual requests for each
        chemical when working with multiple DTXSIDs.

        Args:
            dtxsid_list: List of DSSTox Substance Identifiers

        Returns:
            List of dictionaries containing product data for all requested chemicals.
            Results include the DTXSID and associated product information for each
            chemical.

        Raises:
            ValueError: If dtxsid_list is not a valid non-empty list

        Example:
            >>> prod_data = ProductData()
            >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
            >>> batch_results = prod_data.product_data_by_dtxsid_batch(dtxsids)
            >>> for result in batch_results:
            ...     print(f"{result.get('dtxsid')}: {result.get('productName')}")
        """
        if not dtxsid_list or not isinstance(dtxsid_list, list) or len(dtxsid_list) == 0:
            raise ValueError("dtxsid_list must be a non-empty list of strings")

        if not all(isinstance(dtxsid, str) for dtxsid in dtxsid_list):
            raise ValueError("All elements in dtxsid_list must be strings")

        endpoint = "exposure/product-data/search/by-dtxsid/"
        return self._make_request("POST", endpoint, json_data=dtxsid_list)

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

Initialize the ProductData client.

Parameters:

Name Type Description Default
api_key Optional[str]

CompTox API key (optional, will be loaded from config if not provided)

 None
base_url str

Base URL for the CompTox API

 'https://comptox.epa.gov/ctx-api/'
time_delay_between_calls float

Delay between API calls in seconds

 0.0

Raises:

Type Description
ValueError

If no API key is provided or found in configuration
Source code in src/pycomptox/exposure/productdata.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: str = "https://comptox.epa.gov/ctx-api/",
    time_delay_between_calls: float = 0.0
, **kwargs):
    """
    Initialize the ProductData client.

    Args:
        api_key: CompTox API key (optional, will be loaded from config if not provided)
        base_url: Base URL for the CompTox API
        time_delay_between_calls: Delay between API calls in seconds

    Raises:
        ValueError: If no API key is provided or found in configuration
    """
    super().__init__(
        api_key=api_key,
        base_url=base_url,
        time_delay_between_calls=time_delay_between_calls,
        **kwargs
    )

list_all_puc_product(use_cache=None)

Get all Product Use Category (PUC) classifications.

Retrieves a complete list of Product Use Category (PUC) codes and their definitions. PUCs provide a hierarchical classification system for categorizing consumer product types based on their use and function.

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing PUC information including codes,
List[Dict[str, Any]]

descriptions, and hierarchical relationships.
Example

prod_data = ProductData() pucs = prod_data.list_all_puc_product() for puc in pucs: ... print(f"{puc.get('pucCode', 'N/A')}: {puc.get('pucDescription', '')}")

Source code in src/pycomptox/exposure/productdata.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def list_all_puc_product(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get all Product Use Category (PUC) classifications.

    Retrieves a complete list of Product Use Category (PUC) codes and their
    definitions. PUCs provide a hierarchical classification system for categorizing
    consumer product types based on their use and function.

    Returns:
        List of dictionaries containing PUC information including codes,
        descriptions, and hierarchical relationships.

    Example:
        >>> prod_data = ProductData()
        >>> pucs = prod_data.list_all_puc_product()
        >>> for puc in pucs:
        ...     print(f"{puc.get('pucCode', 'N/A')}: {puc.get('pucDescription', '')}")
    """
    endpoint = "exposure/product-data/puc"
    return self._make_cached_request(endpoint, use_cache=use_cache)

product_data_by_dtxsid_batch(dtxsid_list, use_cache=None)

Get product data for multiple chemicals in a single request.

Retrieves product information for multiple chemicals at once using a batch API call. This is more efficient than making individual requests for each chemical when working with multiple DTXSIDs.

Parameters:

Name Type Description Default
dtxsid_list List[str]

List of DSSTox Substance Identifiers

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing product data for all requested chemicals.
List[Dict[str, Any]]

Results include the DTXSID and associated product information for each
List[Dict[str, Any]]

chemical.

Raises:

Type Description
ValueError

If dtxsid_list is not a valid non-empty list
Example

prod_data = ProductData() dtxsids = ["DTXSID0020232", "DTXSID7020182"] batch_results = prod_data.product_data_by_dtxsid_batch(dtxsids) for result in batch_results: ... print(f"{result.get('dtxsid')}: {result.get('productName')}")

Source code in src/pycomptox/exposure/productdata.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
def product_data_by_dtxsid_batch(self, dtxsid_list: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get product data for multiple chemicals in a single request.

    Retrieves product information for multiple chemicals at once using a batch
    API call. This is more efficient than making individual requests for each
    chemical when working with multiple DTXSIDs.

    Args:
        dtxsid_list: List of DSSTox Substance Identifiers

    Returns:
        List of dictionaries containing product data for all requested chemicals.
        Results include the DTXSID and associated product information for each
        chemical.

    Raises:
        ValueError: If dtxsid_list is not a valid non-empty list

    Example:
        >>> prod_data = ProductData()
        >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
        >>> batch_results = prod_data.product_data_by_dtxsid_batch(dtxsids)
        >>> for result in batch_results:
        ...     print(f"{result.get('dtxsid')}: {result.get('productName')}")
    """
    if not dtxsid_list or not isinstance(dtxsid_list, list) or len(dtxsid_list) == 0:
        raise ValueError("dtxsid_list must be a non-empty list of strings")

    if not all(isinstance(dtxsid, str) for dtxsid in dtxsid_list):
        raise ValueError("All elements in dtxsid_list must be strings")

    endpoint = "exposure/product-data/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsid_list)

products_data_by_dtxsid(dtxsid, use_cache=None)

Get product data for a chemical.

Retrieves information about consumer products that contain a specific chemical identified by its DSSTox Substance Identifier (DTXSID). This includes product names, manufacturers, product use categories (PUC), and composition information.

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., 'DTXSID0020232')

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing product data. Each entry includes product
List[Dict[str, Any]]

information such as name, manufacturer, PUC classification, and chemical
List[Dict[str, Any]]

composition details.

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

prod_data = ProductData() products = prod_data.products_data_by_dtxsid("DTXSID0020232") for product in products: ... print(f"{product.get('productName', 'N/A')}: {product.get('pucCode', 'N/A')}")

Source code in src/pycomptox/exposure/productdata.py 
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
def products_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get product data for a chemical.

    Retrieves information about consumer products that contain a specific chemical
    identified by its DSSTox Substance Identifier (DTXSID). This includes product
    names, manufacturers, product use categories (PUC), and composition information.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

    Returns:
        List of dictionaries containing product data. Each entry includes product
        information such as name, manufacturer, PUC classification, and chemical
        composition details.

    Raises:
        ValueError: If dtxsid is not a valid non-empty string

    Example:
        >>> prod_data = ProductData()
        >>> products = prod_data.products_data_by_dtxsid("DTXSID0020232")
        >>> for product in products:
        ...     print(f"{product.get('productName', 'N/A')}: {product.get('pucCode', 'N/A')}")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/product-data/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)