STEPSTools

Location Skip Navigation LinksAPI DocumentationAPI Indexmethod: GetMatchingMedNames

Rounding: GetMatchingMedNames


Table of Contents

Description

Takes a "starts with" string and returns a list of matching medications from the STEPSTools knowledge base which match the string. When available, the returned matches also include encoding using the specified vocabulary. This method is intended to support an e-prescribing workflow in which a user enters a search stem such as "augmen" and get back matching choices in the e-prescribing system. By calling this very light-weight method, the e-prescribing system can know if STEPSTools has rounding knowledge for a med and only call STEPSTools GetRoundedDosesForMedByFrequency method if a medication the user selects is in the STEPSTools knowledge base.

Example HTTP GET Message

Request
GET http://dev.pedstep.org/Rounding/GetMatchingMedNames.aspx?_
  authToken=0c849415-5f3d-4005-af0e-fa631b893804&
  vocab=NDDF&_
  searchString=augmen HTTP/1.1
Host: www.pedstep.org

Additional notes:
  • Underscores in the above example are not actual characters which should be used in a real web service request. These are included only to indicate continuation of a single line.
  • During development, you will use the STEPSTools test platform at dev.pedstep.org as shown above. When you are ready to go live, you will need to request that you account be upgraded to production level and use our production domain at www.pedstep.org. The test domain is designated for both STEPSTools and vendor testing so as to minimally affect production users. The production domain is reserved for production users and a more stable platform with less-frequent, managed changes to the STEPSTools codebase.
  • Explanations of the input parameters and output values of the service are detailed in the following sections.
Response

Input Parameters

Tag name Type Description Required
authToken string Token for authenticating to the service. Read more here yes
vocab string An abbreviation identifying the medication vocabulary that your system uses (Example: "NDDF").   Currently, STEPSTools only supports abbreviations for First DataBank ("NDDF") and Medispan ("MDDB"). We hope, in the future, to add support for all vocabularies covered by RxNorm. To see a list of these, click here.   If the vocabulary you specify is supported, codes for your specified vocabulary will be included in the return message. yes
searchString string A "starts with" string that can be a stem of a generic or brand name of a medication.  The service will search the knowledge base and return matching medications for which STEPSTools has rounding knowledge.  So, for example, you could specify a searchString of "amox" and STEPSTools would return "Amoxicillin", among other med names. yes
 

Output XML

This method of the service returns a collection of "MatchingSTEPSToolsMedication" nodes - one for each match to the searchString you specified.  Each of these nodes contains the following child nodes:

Tag name Type Description
MedName string This is the generic name of the medication as it is represented in the STEPSTools knowledge base (ie. "Amoxicillin-Clavulanate").
MatchedName string This is the name that was found as a soft-match to the searchString you specified.  For any one MedName, there may be several MatchingSTEPSToolsMedication nodes with different MatchedNames.  For example, a searchString of "augmen" returns nodes with MatchedNames of "Augmentin", "Augmentin Junior", etc.  For all these nodes, however, the MedName is "Amoxicillin-Clavulanate".
StepstoolsMedicationId int This is a unique numeric identifier for the MedName in the STEPSTools knowledge base.
RxCuis string This will contain one or more rxcuis, separated by commas, for the ingredient level components of the drug. (ie. "723, 48203")
Vocab string An abbreviation identifying the medication vocabulary that your system uses (Example: "NDDF").   Currently, STEPSTools only supports abbreviations for First DataBank ("NDDF") and Medispan ("MDDB"). We hope, in the future, to add support for all vocabularies covered by RxNorm. To see a list of these, click here.   Here, this value is just provided as feedback to confirm the vocabulary that the vocab Id (next node) comes from.
VocabId string A code from the vocabulary specified in "vocab" which identifies the medication at the ingredient level (Example: "003675").
 

Practice Tool


Enter some test parameters in the fields below to test the web service.  A test authorization key has been entered for you as a read-only value.  When you click submit, the HTTP GET call that was sent will be displayed below the form as well as the XML return message that came back from the service.



(ie. "NDDF")

(ie. "amox")

Additonal notes:
  • Do not use the authToken in this test tool for your development as it changes frequently. It's only purpose is to allow you to play with the service initially using this practice tool. For further testing and development, you should get your own authToken associated with your account. This will enable you to use our getAuthToken method of the service to gracefully handle token changes. It will also enable you to take advantage of our service logging to see what's happening on the STEPSTools end when you call the service.