# Provider Search Responses The Provider Search endpoint ([API docs](https://docs.ideonapi.com/#providers-providers-post)) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ideonapi.gitbook.io/quote-and-select/provider-network-directory-search/search-for-a-specific-provider/provider-search-responses.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.