> For the complete documentation index, see [llms.txt](https://ideonapi.gitbook.io/quote-and-select/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ideonapi.gitbook.io/quote-and-select/provider-network-directory-search/search-for-a-specific-provider/provider-search-responses.md).

# Provider Search Responses

Interpret provider results when searching for a specific provider

The Provider Search endpoint ([API docs](https://docs.ideonapi.com/#tag/Providers/operation/getProviders)) returns filtered and ranked results for providers based on the search criteria passed. The response is structured as a list of provider objects, each with complete provider metadata and address information. For responses to requests without plan or network IDs included - as described in this section on searching for a specific provider details - network participation is *not* included. This page includes sections detailing important information and tips on how to best integrate provider search responses into user-facing interfaces.

## Result Schema and Data Dictionary

Responses in the Provider Search endpoint are structured as an array of provider objects. The response schema is fully documented in the [technical API docs](https://docs.ideonapi.com/#providers-providers-post) as well as the [Provider Data Dictionary section](/quote-and-select/flat-file-data-dictionaries/select-provider-network-data/provider-data-dictionary.md); responses for searches without any network or plan IDs included - as detailed in this section on searching for specific provider without network participation - contain minor schema differences, listed below.

* The `networks` array is not included, as network participation is not evaluated if plan or network IDs are not included in the request.
* The addresses the provider practices at are included in a top-level `addresses` array. The schema for the address objects in this array matches the schema in the Data Dictionary's Addresses section. However, the network-specific address fields (`pcp`, `pcp_id`, `external_id`, and `accepting_new_patients`) will return as *null*. 

For selected providers, the Shop by Doc workflow supports provider-network participation evaluations by provider NPI or by provider NPI at a specific address. The NPI for the provider can be found in the provider object's `id` field. The specific address IDs can be found in the `id` field for each address object in the `addresses` array.

## Provider Address Filtering

When considering the geography-based filtering for a provider search, providers are included if they are associated with one or more addresses within the defined geography. All of the provider's associated addresses are included for this check: both the providers NPPES registry address as well as all participating addresses sourced from carrier data. 

The data in the `addresses` arrays for matched providers is additionally filtered to only included addresses that are within the geography defined in the request. For example, consider a provider associated with three addresses: A, B, and C. If a search with geography criteria that is met for address A but not for addresses B or C is made, the provider will be returned in the results. However, only address A will be included in the `addresses` array for the provider. Note that the `npi_address` is returned for each provider regardless of whether or not it meets geography search criteria.

## Ranking and Sorting of Results

The Provider Search endpoint supports two methodologies for ranking, or sorting, of results: a multi-faceted best match function and a strict distance evaluation. The default for any request is to rank by best match, which can also be defined by passing the `sort` parameter as *best\_match*. A ranking with higher weights on provider address distance can be requested by passing the `sort` parameter as *distance*.

Both ranking methodologies evaluate the following parameters, if included in the search request.

* The distance to the center point of the defined geography. This considers all addresses for the providers; the address closest to the geography's center point is used for ranking.
* The closeness of the `provider_name_search` term match. 
* Provider specialty match, when searching without a plan or network ID. All specialties associated with a provider - from NPPES and all carrier sources - are considered when filtering a search based on specialty. Ranking weighs a match against the NPPES specialty higher than carrier (or network) specialties when searches do not include a plan or network ID.

The *best\_match* methodology weighs all above criteria for searches without a plan or network ID. Given algorithm weights, it is possible for a provider that is further away but with a higher degree of name matching to be ranked above a provider with an address that is closer. The *distance* methodology also considers all the above parameters, but weighs provider distance significantly higher.