Configuring Search Requests
Optimize integration requests when searching for a specific provider
Ideon's "Provider Search" endpoint (API docs) enables queries against the IdeonSelect dataset using flexible criteria such as geography, name, and specialty. Well-structured search requests reduce response size, minimize unnecessary API calls, and improve both accuracy and performance of the integration. Request parameters should be aligned with the intended use case to ensure efficient and reliable integration.
Recommended Search Structure
When searching for a specific provider, we recommend limiting search criteria to the following data. Geography, provider type, and accepts insurance define the filtering of results; the search term and pagination affect the ranking, or sorting, of the results.
Search Term - the primary means for provider identification. Provider name matching accuracy affects filtering and the ranking (sorting) of results based on other filter criteria.
Geography - one of the three types of supported geography parameters is required for provider search requests that include a search term in order to limit results for endpoint performance.
Provider Specialty - one or more specialty identifiers can be included to filter results to the specific healthcare need of the user.
Provider Type - including a provider type in all requests is considered best practice for endpoint performance. This also improves end user experiences, as results will consistently be either all individual doctors or medical organizations.
Accepts Insurance - we recommend hard-coding this parameter to true for all requests. This limits results to providers who participate in at least one network in Ideon's dataset.
Pagination - the "Provider Search" endpoint enforces a default maximum
per_pageof 25 results if no pagination parameters are passed. A maximum of 200 resultsper_pagecan be requested. Given that results are sorted by best match and pagination can significantly impact endpoint latency, we strongly recommend limiting theper_pagerequested to be in range of 25-50 results.
An example request to the "Provider Search" endpoint incorporating the above search criteria is shown below. This request can be translated to: show me all individual providers who are within 10 miles of the center point of ZIP code 10010 and participate in at least one network; filter and sort these results based on the closeness of their name matching "John Smith" and their proximity to the center point of ZIP 10010.
{
"provider_name_search": "Smith",
"zip_code": "10010",
"radius": 10,
"type": "individual",
"accepts_insurance": true
}Provider Name Search Term
The provider_name_search term impacts both the filtering and the ranking, or sorting, of the provider search results. Results are weighted based on the closeness to which the search term matches Ideon's provider name data. The provider_name_search term searches across all data fields that support provider names. These include the standardized first_name, middle_name, last_name, organization_name, and doing_business_as_name in the provider search response. Additionally, the term searches against names that are collected for each provider from the source data but not present in the response.
In order to reliably and consistently match providers based on name, we recommend incorporating the following tips into integrations or end user recommendations for searches.
Do not include "Dr." or other titles in the search term.
First, last, and middle names can all be included in one string.
We do not recommend incorporating type-ahead search features - provider search requests should be sent with completed search strings from end users.
Searching for full provider names - first and last name, for example - will generally produce more accurate results for the top-ranked providers, assuming names are spelled correctly. It is important to note that each space-delimited term in the provider_name_search string is searched independently and together for filtering and ranking purposes. Because of this, full provider name searches can often produce more total results than single-name searches (first or last name, for example). However, the full provider name searches will likely yield better matches for the top-ranked providers: the top results on the first page.
Filtering by Geographies
There are three supported methods for defining a search area in the request. Provider search requests that include a Search Term parameter must also include a geography filter as well. Search results are limited to providers that are associated with at least one address in the geography.
ZIP Code and Radius
The zip_code and radius parameters define a search area based on the area created by drawing a radius around the center point of the ZIP code. The units for the radius parameter is miles. If a request is made with a zip_code and no radius parameter, the radius of the search will default to 25 miles.
Center Point and Radius
The center_point and radius parameters define a search area based on the area created by drawing a radius around a given point. The center_point is defined as an object with lat (latitude) and lon (longitude) values. The units for the radius parameter is miles. If a request is made with a center_point and no radius parameter, the radius of the search will default to 25 miles. The center_point offers greater flexibility than zip_code searches, and is recommended for use cases requiring precise location targeting: for example, users selecting a map pin and interacting with an adjustable radius slider.
Polygon
The polygon parameter allows custom geographic boundaries to be specified by a set of latitude and longitude points. This supports filtering to more complex geographies, and user interface components such as search to a user-defined map area. The polygon is an array of point objects defined by lat and lon; an example is given below.
Filtering by Provider Specialty
Provider specialty can be an important search parameter for searches in more densely-populated, urban areas or for those seeking providers with more common names. For example, a search for the provider name "Smith" in New York City can produce 5,000+ results. To give users a more manageable search experience, either narrowing the geography or adding a filter for specialty can be helpful. For more detailed recommendations on how to incorporate specialty into searches, see the Filtering by Provider Specialty section in the search for in-network providers guide; the specialty filtering logic is consistent between these two workflows.
Provider Type
The type parameter filters results to one of individual (individual doctors), organization (medical group practices, urgent care centers, etc.), or hospital provider records. We highly recommend including this parameter for all provider search requests for two reasons. First, it can reduce results, making it easier to select the desired provider. Second, including type significantly improves endpoint response latency.
Accepts Insurance
The accepts_insurance boolean parameter, when set to true, filters results to only return providers that participate in at least one network in Ideon's dataset. For context, Ideon's dataset includes the over 8 million providers that are registered through NPPES, unique by NPI. Of that, roughly 4 million providers participate in one or more network.
We recommend filtering to this set of providers that participate in at least one network when searching for a specific provider due to the subsequent use case of quoting available plans with provider participation. If a user cannot find a provider with accepts_insurance set to true, this indicates the provider they are looking for does not exist or does not participate in at least one network in Ideon's data. By including this parameter, this information can be conveyed to the user earlier in the shopping process. For the vast majority of users searching for a provider that does participate in at least one network, the results presented to them will be better filtered.
Last updated
Was this helpful?