Provider Search Responses

Interpret provider results when searching for a specific provider

The "Provider Search" endpoint (API docs) 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 as well as the Provider Data Dictionary section; 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.