biocontext_kb.core.clinicaltrials

biocontext_kb.core.clinicaltrials#

Functions#

get_recruiting_studies_by_location(location_country[, ...])

Find recruiting clinical trials by geographic location. Returns paginated results with summary breakdowns.

get_studies_by_condition(condition[, status, ...])

Search trials by condition with summary statistics. Returns paginated results with breakdowns by status, study type, and phase.

get_studies_by_intervention(intervention[, condition, ...])

Search trials by intervention with condition and phase filters. Returns paginated results with breakdowns.

get_study_details(nct_id[, fields])

Get complete trial details by NCT ID. Retrieves study design, eligibility, outcomes, locations, contacts, and metadata.

search_studies([condition, intervention, sponsor, ...])

Advanced search for trials with flexible multi-field filtering. Specify at least one search parameter.

Package Contents#

biocontext_kb.core.clinicaltrials.get_recruiting_studies_by_location(location_country, location_state=None, location_city=None, condition=None, study_type='ALL', age_range='ALL', page_size=50)#

Find recruiting clinical trials by geographic location. Returns paginated results with summary breakdowns.

Returns:

Studies list with summary containing search location, total studies, study type/phase/condition breakdowns, recruiting locations or error message.

Return type:

dict

Parameters:

  • location_country (Annotated[str, Field(description="Country name (e.g., 'United States', 'Germany')")])

  • location_state (Annotated[Optional[str], Field(description="State/province (e.g., 'California')")])

  • location_city (Annotated[Optional[str], Field(description='City name')])

  • condition (Annotated[Optional[str], Field(description="Medical condition filter (e.g., 'cancer')")])

  • study_type (Annotated[Optional[str], Field(description="'INTERVENTIONAL', 'OBSERVATIONAL', or 'ALL'")])

  • age_range (Annotated[Optional[str], Field(description="'CHILD', 'ADULT', 'OLDER_ADULT', or 'ALL'")])

  • page_size (Annotated[int, Field(description='Results per page (1-1000)', ge=1, le=1000)])

biocontext_kb.core.clinicaltrials.get_studies_by_condition(condition, status='ALL', study_type='ALL', location_country=None, page_size=50, sort='LastUpdatePostDate:desc')#

Search trials by condition with summary statistics. Returns paginated results with breakdowns by status, study type, and phase.

Returns:

Studies list with summary containing condition searched, total studies, status/study type/phase breakdowns or error message.

Return type:

dict

Parameters:

  • condition (Annotated[str, Field(description="Medical condition/disease (e.g., 'cancer', 'diabetes')")])

  • status (Annotated[Optional[str], Field(description="'RECRUITING', 'ACTIVE_NOT_RECRUITING', 'COMPLETED', or 'ALL'")])

  • study_type (Annotated[Optional[str], Field(description="'INTERVENTIONAL', 'OBSERVATIONAL', or 'ALL'")])

  • location_country (Annotated[Optional[str], Field(description="Country filter (e.g., 'United States')")])

  • page_size (Annotated[int, Field(description='Results per page (1-1000)', ge=1, le=1000)])

  • sort (Annotated[str, Field(description="'LastUpdatePostDate:desc', 'StudyFirstPostDate:desc', or 'EnrollmentCount:desc'")])

biocontext_kb.core.clinicaltrials.get_studies_by_intervention(intervention, condition=None, phase=None, status='ALL', intervention_type='ALL', page_size=50, sort='LastUpdatePostDate:desc')#

Search trials by intervention with condition and phase filters. Returns paginated results with breakdowns.

Returns:

Studies list with summary containing intervention searched, total studies, status/phase breakdowns, top conditions/sponsors or error message.

Return type:

dict

Parameters:

  • intervention (Annotated[str, Field(description="Drug/therapy name (e.g., 'aspirin', 'pembrolizumab', 'radiation')")])

  • condition (Annotated[Optional[str], Field(description="Medical condition filter (e.g., 'cancer')")])

  • phase (Annotated[Optional[str], Field(description="'PHASE1', 'PHASE2', 'PHASE3', 'PHASE4', or 'EARLY_PHASE1'")])

  • status (Annotated[Optional[str], Field(description="'RECRUITING', 'ACTIVE_NOT_RECRUITING', 'COMPLETED', or 'ALL'")])

  • intervention_type (Annotated[Optional[str], Field(description="'DRUG', 'BIOLOGICAL', 'DEVICE', 'PROCEDURE', 'RADIATION', 'BEHAVIORAL', or 'ALL'")])

  • page_size (Annotated[int, Field(description='Results per page (1-1000)', ge=1, le=1000)])

  • sort (Annotated[str, Field(description="'LastUpdatePostDate:desc', 'StudyFirstPostDate:desc', or 'EnrollmentCount:desc'")])

biocontext_kb.core.clinicaltrials.get_study_details(nct_id, fields='IdentificationModule,StatusModule,SponsorCollaboratorsModule,DescriptionModule,ConditionsModule,DesignModule,ArmsInterventionsModule,OutcomesModule,EligibilityModule,ContactsLocationsModule')#

Get complete trial details by NCT ID. Retrieves study design, eligibility, outcomes, locations, contacts, and metadata.

Returns:

Study details with protocol sections including identification, status, sponsors, description, conditions, design, interventions, outcomes, eligibility, locations or error message.

Return type:

dict

Parameters:

  • nct_id (Annotated[str, Field(description="NCT ID (e.g., 'NCT01234567')")])

  • fields (Annotated[str, Field(description="Comma-separated fields or 'all' for complete data. Default includes key modules.")])

biocontext_kb.core.clinicaltrials.search_studies(condition=None, intervention=None, sponsor=None, status=None, phase=None, study_type=None, location_country=None, min_age=None, max_age=None, sex=None, page_size=25, sort='LastUpdatePostDate:desc')#

Advanced search for trials with flexible multi-field filtering. Specify at least one search parameter.

Returns:

Paginated search results containing studies list with trial metadata or error message.

Return type:

dict

Parameters:

  • condition (Annotated[Optional[str], Field(description="Medical condition (e.g., 'cancer')")])

  • intervention (Annotated[Optional[str], Field(description="Drug/therapy name (e.g., 'aspirin')")])

  • sponsor (Annotated[Optional[str], Field(description="Sponsor org (e.g., 'Pfizer')")])

  • status (Annotated[Optional[str], Field(description="'RECRUITING', 'ACTIVE_NOT_RECRUITING', 'COMPLETED', 'TERMINATED', 'SUSPENDED', 'WITHDRAWN', or 'NOT_YET_RECRUITING'")])

  • phase (Annotated[Optional[str], Field(description="'PHASE1', 'PHASE2', 'PHASE3', 'PHASE4', 'EARLY_PHASE1', or 'NA'")])

  • study_type (Annotated[Optional[str], Field(description="'INTERVENTIONAL', 'OBSERVATIONAL', or 'EXPANDED_ACCESS'")])

  • location_country (Annotated[Optional[str], Field(description="Country (e.g., 'United States')")])

  • min_age (Annotated[Optional[int], Field(description='Min participant age (years)', ge=0)])

  • max_age (Annotated[Optional[int], Field(description='Max participant age (years)', ge=0)])

  • sex (Annotated[Optional[str], Field(description="'ALL', 'FEMALE', or 'MALE'")])

  • page_size (Annotated[int, Field(description='Results per page (1-1000)', ge=1, le=1000)])

  • sort (Annotated[str, Field(description="'LastUpdatePostDate:desc', 'StudyFirstPostDate:desc', or 'EnrollmentCount:desc'")])

Contents