Unified Search

Performing a Unified Search

Overview

The searchHealthResources method enables comprehensive searching across resource types within the b.well ecosystem. It allows users to find and retrieve information about healthcare providers, facilities, and support services, including practitioners, clinics, hospitals, health systems, insurance providers, and laboratories, from a single search.

Method Signature

suspend fun searchHealthResources(request: HealthResourceSearchRequest): BWellResult<HealthResource>

• request: Encapsulates search parameters.
• BWellResult<HealthResource>: Returns a collection of matching search results, FHIR OperationOutcome, and paging information.

Search Parameters

• Search Term (String):
  • Key filter for searches, applicable for names, specialties, locations, or addresses.
• Filters (SearchHealthResourcesInput):
  • Type (Enum) - Filters results based on organization type.
    • PRACTICE used for hospitals, clinics, and health system connections.
    • PRACTITIONER used for healthcare providers.
    • LABORATORY used for laboratory connections.
    • INSURANCE used for insurance provider connections
    • PHARMACY used for pharmacy connections
  • ID (Array):
    • Only return search results included in the array of IDs
  • Include Populated PROA Only:
    • Return only results that have PROA connections
  • Location:
    • Sorts results by geographical location using latitude and longitude

• Sort Options:
  • By default, results are sorted by relevance in descending (DESC) order when no sortBy value is specified.
    • The most relevant results have the highest score so sorting by DESC is required to see the most relevant results first
  • Available sorting options include:
    • Relevance (default)
    • Distance
    • Content
• Pagination:
  • page: Specifies the page number for results.
  • pageSize: Determines the number of results per page.

Example Usage

The following example demonstrates how to use the searchHealthResources method and configure a HealthResourceSearchRequest specific to the Providers data connection category:

val request = HealthResourceSearchRequest.Builder()
    .id(ids)
    .searchTerm(searchTerm)
    .searchResultType(listOf(SearchResultType.PRACTITIONER))
    .includePopulatedPROAonly()
    .location(latitude, longitude)
    .sortBy(HealthResourceSortField.RELEVANCE, SortOrder.DESC)
    .page(page)
    .pageSize(pageSize)
    .build()

Reading Results

Each item in BWellResult<HealthResource> carries the display fields you need to render a result row — including the organization's logo.

Organization logos (logoUrl)

logoUrl is a nullable String holding a public URL to the organization's logo image. Use it so users can visually confirm they are connecting to the right health system.

val request = HealthResourceSearchRequest.Builder()
    .searchTerm("cardiologist")
    .build()

val response = BWellSdk.search.searchHealthResources(request)

if (response is BWellResult.SearchResults) {
    response.data?.forEach { result ->
        // result.logoUrl: String?
        val logoUrl = result.logoUrl

        // Nested organization logos:
        val orgLogoUrl = result.organization?.firstOrNull()?.logoUrl
    }
} else {
    // handle response.error
}

Which logo to use. Prefer result.logoUrl. Fall back to result.organization?.firstOrNull()?.logoUrl only when the top-level value is null, and only for PRACTITIONER results — organization is empty for every other result type.

Fetching the image. Logo URLs are public and unauthenticated — request them with a standard image load and do not attach your SDK credentials or API token.

Available in Kotlin SDK v1.19.0 and later.