The suggest query is used to get autocomplete suggestions for a term or location being inputted into a field for a search. Autocomplete suggestions involve the following 5 interconnected text fields for a search:
HCP name
HCP specialties
HCP medical terms
HCO name
addresses
Schema |
|
type Query { suggestions( first: Int=10, offset: Int=0, criteria: String, scope: SuggestionScope=Individual, locale: String, location: GeopointQuery, country: String, county: CountyQuery, city: CityQuery, specialties: [String!], medTerms: [String!], addresses: [String!], individuals: [String!], workplaces: [String!] ): SuggestionsResult }
|
|
Field |
Type |
Description |
first |
Int |
Optional for pagination. Specifies ... 10 (default) ... to limit the number of results to get for the first page. The same number to limit results can be specified again to limit results for each of the following pages. |
offset |
Int |
Optional for pagination. Specifies ... 0 (default) ... to not offset the first number of results for the first page. However, offset is required for a following page to skip <total number results already retrieved on previous pages> to the next number to get from remaining results. For example: ● "offset: Int = 0" and "first: Int = 10" gets first 10 results for page 1 ● "offset: Int = 10" and "first: Int = 10" skips first 10 results to get next 10 results for page 2 ● "offset: Int = 20" and "first: Int = 10" skips first 20 results to get next 10 results for page 3 |
criteria |
String! |
Optional. Specifies free text criteria for the search. Usage of free text criteria is internally bound to the scope field. For example, the free text criteria ... criteria: "John doe" ... is a name search to find suggestions for "John doe" because the scope field is set to "Individual". If not specified, then the default criteria is an empty string. |
scope |
Optional. Specifies the scope of search to find suggestions, such as an individual name, address, specialty, or medical term search to find suggestions. Value is one of the following: ● "Individual" scope specifies a name search using free text in the criteria field to find suggestions ● "Address" scope specifies an address search using free text in the criteria field to find suggestions (address can include street, city, county, label, and/or building) ● "Specialty" scope specifies a speciality search using free text in the criteria field to find suggestions (text is matched against the relevant translation of specialty labels according to the locale field) ● "MedTerm" scope specifies a medical term search using free text in the criteria field to find suggestions (text is matched against the relevant translation of medical term labels according to the locale field) If not specified, then the default scope is used: scope:
SuggestScopeIndividual (default) |
|
locale |
String |
Optional. Specifies the language in which translatable fields are translated. If not specified, then the default locale "en" is used. |
location |
Optional. Restrict the search to activities around a specific geolocation. |
|
country |
String |
Optional. Restrict the search to activities within a specific country. |
county |
Optional. Restrict the search to activities within a specific county. |
|
city |
Optional. Restrict the search to activities into a specific city. |
|
specialties |
[String!] |
Optional. Restrict the search to activities involving an HCP who is profiled with one of the specialties. Expected values are specialty or international specialty codes. Review the specialties that come with your subscription. |
medTerms |
[String!] |
Optional. Restrict the search to activities involving an HCP who is profiled with one of the medical terms. Expected values are medical term codes. Review the medical terms that come with your subscription. |
addresses |
[String!] |
Optional. Restrict the search to records associated with an activity involving an HCO that is profiled with one of the addresses. Expected values are address IDs. |
individuals |
[String!] |
Optional. Restrict the search to activities associated with a set of HCPs. Expected values are individual IDs. Review the HCPs that come with your subscription. |
workplaces |
[String!] |
Optional. Restrict the search to activities associated with a set of HCOs. Expected values are workplace IDs. Review the HCOs that come with your subscription. |
|
|
|
SuggestionsResult
A JSON response with an object of the SuggestionsResult type as a result.
SuggestionsException
If a server error occurs or an incorrect input is specified.
Input validation is done by GraphQL.
Criteria in this query is from an on-the-fly "suggestion request" made by your app to get suggestions for text being inputted/typed as criteria for a search. This might be suggestions for a name as a user types it on the prebuilt Search block integrated within your app. After inputting suggestions and submitting a search, the "search request" made by your app provides the criteria to a search query, such as the activities query.
Both filters and free text search are supported to narrow down suggestions.
Bound to the scope of search in the scope field (such as name search to find suggestions) and limited by filters in other fields (such as speciality and city filters to narrow down suggestions), the partial or full text inputted in the criteria field is used to find matching data on HCPs to return results (names) as suggestions in the response. The fields are interconnected.
For example, a name search ("Individual" is set in the scope field) with the "eri" free text (in the criteria field) might return names like "Eric Warren", "Erin Erickson", and "Eri Matsumoto" as suggestions in the response.
The following scenario illustrates how autocomplete suggestions are filtered successively in the interconnected text fields as a user types an address and then a specialty in the fields for a search:
1. A user starts typing in a text field of the search form, such as the field dedicated to an "address" lookup.
2. The user gets a list of suggestions restricted to the scope of the current text field. Since "address" is the scope, only the "address" field is populated with suggestions.
3. The user selects one suggestion among the displayed addresses. The address ID of the selected suggestion is further used in autocomplete suggestions that are made when the user types in other text fields of the search form.
4. The user starts typing in another text field of the search form, such as the field dedicated to a "specialty” lookup.
5. The user gets a list of suggestions restricted to the scope of the current text field ("specialty”) but also filtered by the address ID selected in step 3. In other words, only specialties belonging to individuals having at least one activity located at the input address will be fetched by this last query. (The suggestions query aims at interconnecting the distinct fields of the search form.)
If the requesting app's subscription API key is associated with additional countries or specialties, then results can be maximized by not limiting/specifying the country or specialties.
This query is sent to the Suggest endpoint of the Activity API.
HealthCare Locator SDK 1.2.15 and higher
GraphQL Activity API 2.0