Skip to content

MMDB API Reference

pycomptox.exposure.mmdb.MMDB

Bases: CachedAPIClient

Client for accessing Molecular Modeling Database (MMDB) from EPA CompTox Dashboard.

This class provides methods for retrieving environmental monitoring and measurement data, including harmonized single-sample records organized by environmental medium.

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 MMDB mmdb = MMDB()

Get single-sample records for surface water

data = mmdb.harmonized_single_sample_by_medium("surface water")

Source code in src/pycomptox/exposure/mmdb.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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class MMDB(CachedAPIClient):
    """
    Client for accessing Molecular Modeling Database (MMDB) from EPA CompTox Dashboard.

    This class provides methods for retrieving environmental monitoring and measurement
    data, including harmonized single-sample records organized by environmental medium.

    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 MMDB
        >>> mmdb = MMDB()
        >>> 
        >>> # Get single-sample records for surface water
        >>> data = mmdb.harmonized_single_sample_by_medium("surface water")
    """

    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 MMDB 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 harmonized_single_sample_by_medium(self, medium: str, page_number: int = 1, use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get harmonized single-sample records by environmental medium.

        Retrieves harmonized single-sample environmental monitoring records filtered
        by the type of environmental medium (e.g., surface water, air, soil). The data
        is paginated to handle large result sets.

        Args:
            medium: Harmonized medium type (e.g., 'surface water', 'air', 'soil',
                'groundwater', 'sediment', 'biota')
            page_number: Page number for pagination (default: 1)

        Returns:
            Dictionary containing paginated single-sample records for the specified medium.
            The structure typically includes:
                - data: List of sample records
                - pagination information (page number, total pages, etc.)

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

        Example:
            >>> mmdb = MMDB()
            >>> # Get first page of surface water samples
            >>> data = mmdb.harmonized_single_sample_by_medium("surface water")
            >>> 
            >>> # Get second page
            >>> data_page2 = mmdb.harmonized_single_sample_by_medium("surface water", page_number=2)
        """
        if not medium or not isinstance(medium, str):
            raise ValueError("medium must be a non-empty string")

        if not isinstance(page_number, int) or page_number < 1:
            raise ValueError("page_number must be a positive integer")

        endpoint = "exposure/mmdb/single-sample/by-medium"
        params = {
            "medium": medium,
            "pageNumber": page_number
        }
        return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

    def harmonized_single_sample_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get harmonized single-sample records for a chemical.

        Retrieves harmonized single-sample environmental monitoring records for a
        specific chemical identified by its DSSTox Substance Identifier (DTXSID).
        This provides environmental occurrence data across different media and locations.

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

        Returns:
            Dictionary containing single-sample records for the specified chemical.
            Includes environmental measurements and detection information.

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

        Example:
            >>> mmdb = MMDB()
            >>> samples = mmdb.harmonized_single_sample_by_dtxsid("DTXSID7020182")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/mmdb/single-sample/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def searchable_harmonized_medium_categories(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get all searchable harmonized medium categories.

        Retrieves a complete list of harmonized environmental medium categories
        available in the MMDB database, along with their definitions. This is useful
        for discovering valid medium types to use in other queries.

        Returns:
            List of dictionaries containing medium categories and their definitions.
            Each entry includes the medium name and description.

        Example:
            >>> mmdb = MMDB()
            >>> mediums = mmdb.searchable_harmonized_medium_categories()
            >>> for medium in mediums:
            ...     print(f"{medium['name']}: {medium.get('definition', '')}")
        """
        endpoint = "exposure/mmdb/mediums"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def harmonized_aggregate_records_by_medium(self, medium: str, page_number: int = 1, use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get harmonized aggregate records by environmental medium.

        Retrieves aggregated (summarized) environmental monitoring records filtered
        by the type of environmental medium. Aggregate records provide summary
        statistics across multiple samples, useful for trend analysis and overview.
        The data is paginated to handle large result sets.

        Args:
            medium: Harmonized medium type (e.g., 'surface water', 'air', 'soil',
                'groundwater', 'sediment', 'biota')
            page_number: Page number for pagination (default: 1)

        Returns:
            Dictionary containing paginated aggregate records for the specified medium.
            Includes summary statistics and aggregated measurements.

        Raises:
            ValueError: If medium is not a valid non-empty string or page_number is invalid

        Example:
            >>> mmdb = MMDB()
            >>> # Get first page of surface water aggregates
            >>> agg_data = mmdb.harmonized_aggregate_records_by_medium("surface water")
            >>> 
            >>> # Get second page
            >>> agg_page2 = mmdb.harmonized_aggregate_records_by_medium("surface water", page_number=2)
        """
        if not medium or not isinstance(medium, str):
            raise ValueError("medium must be a non-empty string")

        if not isinstance(page_number, int) or page_number < 1:
            raise ValueError("page_number must be a positive integer")

        endpoint = "exposure/mmdb/aggregate/by-medium"
        params = {
            "medium": medium,
            "pageNumber": page_number
        }
        return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

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

Initialize the MMDB 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/mmdb.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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 MMDB 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
    )

harmonized_aggregate_records_by_medium(medium, page_number=1, use_cache=None)

Get harmonized aggregate records by environmental medium.

Retrieves aggregated (summarized) environmental monitoring records filtered by the type of environmental medium. Aggregate records provide summary statistics across multiple samples, useful for trend analysis and overview. The data is paginated to handle large result sets.

Parameters:

Name Type Description Default
medium str

Harmonized medium type (e.g., 'surface water', 'air', 'soil', 'groundwater', 'sediment', 'biota')

 required
page_number int

Page number for pagination (default: 1)

 1

Returns:

Type Description
Dict[str, Any]

Dictionary containing paginated aggregate records for the specified medium.
Dict[str, Any]

Includes summary statistics and aggregated measurements.

Raises:

Type Description
ValueError

If medium is not a valid non-empty string or page_number is invalid
Example

mmdb = MMDB()

Get first page of surface water aggregates

agg_data = mmdb.harmonized_aggregate_records_by_medium("surface water")

Get second page

agg_page2 = mmdb.harmonized_aggregate_records_by_medium("surface water", page_number=2)

Source code in src/pycomptox/exposure/mmdb.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def harmonized_aggregate_records_by_medium(self, medium: str, page_number: int = 1, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get harmonized aggregate records by environmental medium.

    Retrieves aggregated (summarized) environmental monitoring records filtered
    by the type of environmental medium. Aggregate records provide summary
    statistics across multiple samples, useful for trend analysis and overview.
    The data is paginated to handle large result sets.

    Args:
        medium: Harmonized medium type (e.g., 'surface water', 'air', 'soil',
            'groundwater', 'sediment', 'biota')
        page_number: Page number for pagination (default: 1)

    Returns:
        Dictionary containing paginated aggregate records for the specified medium.
        Includes summary statistics and aggregated measurements.

    Raises:
        ValueError: If medium is not a valid non-empty string or page_number is invalid

    Example:
        >>> mmdb = MMDB()
        >>> # Get first page of surface water aggregates
        >>> agg_data = mmdb.harmonized_aggregate_records_by_medium("surface water")
        >>> 
        >>> # Get second page
        >>> agg_page2 = mmdb.harmonized_aggregate_records_by_medium("surface water", page_number=2)
    """
    if not medium or not isinstance(medium, str):
        raise ValueError("medium must be a non-empty string")

    if not isinstance(page_number, int) or page_number < 1:
        raise ValueError("page_number must be a positive integer")

    endpoint = "exposure/mmdb/aggregate/by-medium"
    params = {
        "medium": medium,
        "pageNumber": page_number
    }
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

harmonized_single_sample_by_dtxsid(dtxsid, use_cache=None)

Get harmonized single-sample records for a chemical.

Retrieves harmonized single-sample environmental monitoring records for a specific chemical identified by its DSSTox Substance Identifier (DTXSID). This provides environmental occurrence data across different media and locations.

Parameters:

Name Type Description Default
dtxsid str

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

 required

Returns:

Type Description
Dict[str, Any]

Dictionary containing single-sample records for the specified chemical.
Dict[str, Any]

Includes environmental measurements and detection information.

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

mmdb = MMDB() samples = mmdb.harmonized_single_sample_by_dtxsid("DTXSID7020182")

Source code in src/pycomptox/exposure/mmdb.py 
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
def harmonized_single_sample_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get harmonized single-sample records for a chemical.

    Retrieves harmonized single-sample environmental monitoring records for a
    specific chemical identified by its DSSTox Substance Identifier (DTXSID).
    This provides environmental occurrence data across different media and locations.

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

    Returns:
        Dictionary containing single-sample records for the specified chemical.
        Includes environmental measurements and detection information.

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

    Example:
        >>> mmdb = MMDB()
        >>> samples = mmdb.harmonized_single_sample_by_dtxsid("DTXSID7020182")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/mmdb/single-sample/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

harmonized_single_sample_by_medium(medium, page_number=1, use_cache=None)

Get harmonized single-sample records by environmental medium.

Retrieves harmonized single-sample environmental monitoring records filtered by the type of environmental medium (e.g., surface water, air, soil). The data is paginated to handle large result sets.

Parameters:

Name Type Description Default
medium str

Harmonized medium type (e.g., 'surface water', 'air', 'soil', 'groundwater', 'sediment', 'biota')

 required
page_number int

Page number for pagination (default: 1)

 1

Returns:

Type Description
Dict[str, Any]

Dictionary containing paginated single-sample records for the specified medium.
Dict[str, Any]

The structure typically includes: - data: List of sample records - pagination information (page number, total pages, etc.)

Raises:

Type Description
ValueError

If medium is not a valid non-empty string
Example

mmdb = MMDB()

Get first page of surface water samples

data = mmdb.harmonized_single_sample_by_medium("surface water")

Get second page

data_page2 = mmdb.harmonized_single_sample_by_medium("surface water", page_number=2)

Source code in src/pycomptox/exposure/mmdb.py 
 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
def harmonized_single_sample_by_medium(self, medium: str, page_number: int = 1, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get harmonized single-sample records by environmental medium.

    Retrieves harmonized single-sample environmental monitoring records filtered
    by the type of environmental medium (e.g., surface water, air, soil). The data
    is paginated to handle large result sets.

    Args:
        medium: Harmonized medium type (e.g., 'surface water', 'air', 'soil',
            'groundwater', 'sediment', 'biota')
        page_number: Page number for pagination (default: 1)

    Returns:
        Dictionary containing paginated single-sample records for the specified medium.
        The structure typically includes:
            - data: List of sample records
            - pagination information (page number, total pages, etc.)

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

    Example:
        >>> mmdb = MMDB()
        >>> # Get first page of surface water samples
        >>> data = mmdb.harmonized_single_sample_by_medium("surface water")
        >>> 
        >>> # Get second page
        >>> data_page2 = mmdb.harmonized_single_sample_by_medium("surface water", page_number=2)
    """
    if not medium or not isinstance(medium, str):
        raise ValueError("medium must be a non-empty string")

    if not isinstance(page_number, int) or page_number < 1:
        raise ValueError("page_number must be a positive integer")

    endpoint = "exposure/mmdb/single-sample/by-medium"
    params = {
        "medium": medium,
        "pageNumber": page_number
    }
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

searchable_harmonized_medium_categories(use_cache=None)

Get all searchable harmonized medium categories.

Retrieves a complete list of harmonized environmental medium categories available in the MMDB database, along with their definitions. This is useful for discovering valid medium types to use in other queries.

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing medium categories and their definitions.
List[Dict[str, Any]]

Each entry includes the medium name and description.
Example

mmdb = MMDB() mediums = mmdb.searchable_harmonized_medium_categories() for medium in mediums: ... print(f"{medium['name']}: {medium.get('definition', '')}")

Source code in src/pycomptox/exposure/mmdb.py 
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def searchable_harmonized_medium_categories(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get all searchable harmonized medium categories.

    Retrieves a complete list of harmonized environmental medium categories
    available in the MMDB database, along with their definitions. This is useful
    for discovering valid medium types to use in other queries.

    Returns:
        List of dictionaries containing medium categories and their definitions.
        Each entry includes the medium name and description.

    Example:
        >>> mmdb = MMDB()
        >>> mediums = mmdb.searchable_harmonized_medium_categories()
        >>> for medium in mediums:
        ...     print(f"{medium['name']}: {medium.get('definition', '')}")
    """
    endpoint = "exposure/mmdb/mediums"
    return self._make_cached_request(endpoint, use_cache=use_cache)