trial_locations_getter
Fetch comprehensive clinical trial location details, including facility addresses, principal investigator info, contact data, and recruitment status, using the NCT ID. Ideal for accessing study teams and identifying nearby trials.
Instructions
Fetch contact and location details for a clinical trial.
Retrieves all study locations including:
- Facility names and addresses
- Principal investigator information
- Contact details (when recruiting)
- Recruitment status by site
Useful for finding trials near specific locations or contacting study teams.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nct_id | Yes | NCT ID (e.g., 'NCT06524388') |
Implementation Reference
- src/biomcp/individual_tools.py:431-453 (handler)Primary handler function for the 'trial_locations_getter' MCP tool. Includes @mcp_app.tool() decorator for registration and Pydantic schema definition via Annotated types. Calls the core _trial_locations helper.@mcp_app.tool() @track_performance("biomcp.trial_locations_getter") async def trial_locations_getter( nct_id: Annotated[ str, Field(description="NCT ID (e.g., 'NCT06524388')"), ], ) -> str: """Fetch contact and location details for a clinical trial. Retrieves all study locations including: - Facility names and addresses - Principal investigator information - Contact details (when recruiting) - Recruitment status by site Useful for finding trials near specific locations or contacting study teams. """ return await _trial_locations( call_benefit="Fetch trial locations and contacts for enrollment information", nct_id=nct_id, )
- Input schema definition for the tool: single parameter 'nct_id' as string with description.nct_id: Annotated[ str, Field(description="NCT ID (e.g., 'NCT06524388')"), ],
- src/biomcp/trials/getter.py:152-174 (helper)Core helper function implementing the trial locations fetch logic by calling ClinicalTrials.gov API with specific module 'ContactsLocationsModule'.async def _trial_locations( call_benefit: Annotated[ str, "Define and summarize why this function is being called and the intended benefit", ], nct_id: str, ) -> str: """ Retrieves contact and location details for a single clinical trial identified by its NCT ID. Parameters: - call_benefit: Define and summarize why this function is being called and the intended benefit - nct_id: A single NCT ID (string, e.g., "NCT04280705") Process: Fetches the `ContactsLocationsModule` from the ClinicalTrials.gov v2 API for the given NCT ID. Output: A Markdown formatted string detailing facility names, addresses (city, state, country), and contact info. Returns an error message if the NCT ID is invalid. """ return await get_trial(nct_id, Module.LOCATIONS)
- src/biomcp/trials/getter.py:53-125 (helper)Supporting utility function that performs the actual API request to ClinicalTrials.gov and formats the response for the locations module.async def get_trial( nct_id: str, module: Module = Module.PROTOCOL, output_json: bool = False, ) -> str: """Get details of a clinical trial by module.""" fields = ",".join(modules[module]) params = {"fields": fields} url = f"{CLINICAL_TRIALS_BASE_URL}/{nct_id}" logger.debug(f"Fetching trial {nct_id} with module {module.value}") logger.debug(f"URL: {url}, Params: {params}") parsed_data: dict[str, Any] | None error_obj: http_client.RequestError | None parsed_data, error_obj = await http_client.request_api( url=url, request=params, method="GET", tls_version=TLSVersion.TLSv1_2, response_model_type=None, domain="clinicaltrials", ) data_to_return: dict[str, Any] if error_obj: logger.error( f"API Error for {nct_id}: {error_obj.code} - {error_obj.message}" ) data_to_return = { "error": f"API Error {error_obj.code}", "details": error_obj.message, } elif parsed_data: # ClinicalTrials.gov API returns data wrapped in a "studies" array # Extract the first study if it exists if isinstance(parsed_data, dict) and "studies" in parsed_data: studies = parsed_data.get("studies", []) if studies and len(studies) > 0: data_to_return = studies[0] data_to_return["URL"] = ( f"https://clinicaltrials.gov/study/{nct_id}" ) else: logger.warning(f"No studies found in response for {nct_id}") data_to_return = { "error": f"No studies found for {nct_id}", "details": "API returned empty studies array", } else: # Handle case where API returns data in unexpected format logger.debug( f"Unexpected response format for {nct_id}: {type(parsed_data)}" ) data_to_return = parsed_data data_to_return["URL"] = ( f"https://clinicaltrials.gov/study/{nct_id}" ) else: logger.warning( f"No data received for {nct_id} with module {module.value}" ) data_to_return = { "error": f"No data found for {nct_id} with module {module.value}", "details": "API returned no data", } if output_json: return json.dumps(data_to_return, indent=2) else: return render.to_markdown(data_to_return)