MedlinePlus Connect is available as a Web application or Web service. Below are the technical details for implementing the Web service, which responds to requests based on:
- diagnosis (problem) codes
- medication codes,
- and lab test codes.
You are welcome to link to and display the data returned by MedlinePlus Connect. You may not copy MedlinePlus pages onto your site. If you use data from the MedlinePlus Connect Web Service, please indicate that the information is from MedlinePlus.gov but do not use the MedlinePlus logo or otherwise imply that MedlinePlus endorses your particular product. Please see NLM’s API page for further guidance. For more information on how to link to MedlinePlus content outside of this service, please see our guidelines and instructions on linking.
If you decide to use MedlinePlus Connect, sign up for the email list to keep up with developments and exchange ideas with your colleagues. Please tell us if you implement MedlinePlus Connect by contacting us.
Web Service Overview
The parameters for the Web service requests conform to the HL7 Context-Aware Knowledge Retrieval (Infobutton) Knowledge Request URL-Based Implementation Guide. The REST-based response conforms to the HL7 Context-Aware Knowledge Retrieval (Infobutton) Service-Oriented Architecture Implementation Guide. The output of the request can be XML in the Atom feed format, JSON, or JSONP.
The structure of the request indicates what type of code you are sending. In all cases, the base URL for the Web service is: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm
MedlinePlus Connect uses HTTPS connections. HTTP requests will not be accepted and existing implementations using HTTP should update to HTTPS.
Output Parameters
These parameters are optional. If you leave them out, the default response is English information in XML format.
Language
Identify if you would like the response to be in English or Spanish.
MedlinePlus Connect will assume English is the language if it is not specified.
If you wish the response to the problem code lookup to be in Spanish, use :
informationRecipient.languageCode.c=es
(=sp also accepted)
To specify English, use the following: informationRecipient.languageCode.c=en
Format
Identify if you would like the response format to be XML, JSON, or JSONP. XML is the default.
- To request JSON, use:
- knowledgeResponseType=application/json
- For JSONP, use:
- knowledgeResponseType=application/javascript&callback=CallbackFunction where CallbackFunction is a name you give the call back function.
- For a response in XML, use:
- knowledgeResponseType=text/xml or leave the knowledgeResponseType parameter out of the request.
Requests for Diagnosis (Problem) Codes
For a problem code, MedlinePlus Connect will return links and information for up to three MedlinePlus health topic pages. The service can provide a response to a diagnosis code request in English or Spanish.
MedlinePlus Connect will return the following:
- MedlinePlus health topic page title (up to three matches). To see the range of possible matches, refer to the full list of MedlinePlus health topics.
- MedlinePlus health topic page URL
- Synonyms for that topic ("Also called")
- MedlinePlus health topic summary, including formatting and links to other appropriate MedlinePlus topics
- Summary attribution
- Selected links for patients, including formatting, the page name, URL, and associated organization (when applicable)
For SNOMED CT and ICD-10-CM codes, some requests may yield up to twenty responses from Genetics Home Reference (GHR) in addition to or instead of MedlinePlus responses. If there are GHR responses, they will follow any MedlinePlus responses and can be distinguished by the URL. Currently GHR responses are available only for English SNOMED CT or ICD-10-CM requests. MedlinePlus Connect will return the following for each response:
- GHR page title
- GHR page URL
- GHR page summary
There may not always be a match for each code. In those cases, MedlinePlus Connect will return a null response.
The base URL of the service is:
https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm
There are two required parameters for any query to this service:
-
Code System
Identify the problem code system you will be using.- For ICD-10-CM use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.90
- For ICD-9-CM use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.103
- For SNOMED CT use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.96
-
Code
Identify the actual code that you are trying to look up: mainSearchCriteria.v.c=250.33
Optional Parameters
Code Title
You may also identify the name/title of the problem code. However, this information does not impact the response (unlike the MedlinePlus Connect Web application where the name/title information may be used).
mainSearchCriteria.v.dn=Diabetes mellitus with other coma type 1 uncontrolled
See the above section on Output Parameters for details on language and output formats.
Description of Selected Atom Elements (or JSON objects) in Response to Problem Code Requests
Element | Class node | Description |
---|---|---|
title | Title of matched MedlinePlus health topic page or GHR page | |
link | URL for matched MedlinePlus health topic page or GHR page | |
summary | The full summary for the health topic. This includes embedded links to other relevant health topics, and all formatting, including bullets and paragraph spacing. The summary is in HTML. For GHR pages, the first section of the full page is provided. | |
summary | class="NLMalsoCalled" | Synonyms for the topic. These are referred to as "Also called" on a health topic page. Not all topics have "Also called" terms. |
summary | class="NLMattribution" | Attribution acknowledgement for summary text, if the majority of the summary was from another federal agency. Not all summaries have an attribution. Unattributed text is original to MedlinePlus. |
summary | class="NLMrelatedLinks" | Selected links associated with the topic. This includes the page name, URL, and associated organization (when applicable). The links are formatted in a bulleted list. Not all topics have these links. The number of links can range from zero to dozens. |
Examples of Requests for Problem Codes
A complete request for Diabetes Mellitus with other coma type 1 uncontrolled, ICD-9 code 250.33, for a Spanish speaking patient would have the following URL address: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.103&mainSearchCriteria.v.c=250.33&mainSearchCriteria.v.dn=Diabetes%20mellitus%20with%20other%20coma%20type%201%20uncontrolled&informationRecipient.languageCode.c=es
A patient with the same diagnosis but the requested format is JSON and the language is English: https://apps2.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.103&mainSearchCriteria.v.c=250.33&knowledgeResponseType=application/json
A patient diagnosed with "Pneumonia due to Pseudomonas" using SNOMED CT code 41381004: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.96&mainSearchCriteria.v.c=41381004&mainSearchCriteria.v.dn=Pneumonia%20due%20to%20Pseudomonas%20%28disorder%29&informationRecipient.languageCode.c=en
A patient with the same diagnosis but the requested format is JSONP: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.96&mainSearchCriteria.v.c=41381004&knowledgeResponseType=application/javascript&callback=CallbackFunction
Related Services and Files
To receive MedlinePlus health topics in response to text requests, as opposed to problem codes, investigate the MedlinePlus Web service. Also, if you need the full set of MedlinePlus health topics in XML format, see our XML files page.
Requests for Drug Information
MedlinePlus Connect provides the best drug information matches when receiving an RXCUI. It also provides good results when receiving an NDC code. MedlinePlus Connect can provide responses in English or Spanish.
For requests for English medication information, if you do not send an NDC or RXCUI or if we find no match based on the code, the application will use the text string that you send to display the best drug information match. For requests for Spanish medication information, MedlinePlus Connect responds only to NDCs or RXCUIs and does not use text strings. It is possible to have a reponse in English but no response in Spanish.
The MedlinePlus Connect Web service will return the following:
- MedlinePlus medication page title
- MedlinePlus medication page URL
- Source attribution for the content
There could be multiple responses to one medication request. There may not always be a match for each request. In those cases, MedlinePlus Connect will return a null response.
For requests for drug information, the base URL is: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm
To send a request, include these pieces of information:
-
Code System
Identify the type of medication code you are sending. (Required for English and Spanish)
- For RXCUI use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.88
- For NDC use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.69
-
Code
Identify the actual code that you are trying to look up. (Preferred for English, Required for Spanish) mainSearchCriteria.v.c=637188 -
Drug Name
Identify the name of the drug with a text string. (Optional for English, Not used for Spanish) mainSearchCriteria.v.dn=Chantix 0.5 MG Oral Tablet
Optional Parameters
Code TitleWhen sending a request for English information, you may include the optional parameter of the name of the medication. This is detailed in the above section. mainSearchCriteria.v.dn=Chantix 0.5 MG Oral Tablet
See the above section on Output Parameters for details on language and output formats.
Description of Selected Atom Elements (or JSON objects) in Response to Medication Requests
Element | Description |
---|---|
title | Title for matched MedlinePlus medication page |
link | URL for the matched MedlinePlus medication page |
author | Source attribution for medication information |
Examples of Requests for Drug Codes
Your medication information request should look like one of the following.
To request information by an RXCUI, your request should look like this: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.88&mainSearchCriteria.v.c=637188&mainSearchCriteria.v.dn=Chantix%200.5%20MG%20Oral%20Tablet&informationRecipient.languageCode.c=en
To request information by an NDC for a Spanish speaker, your request should look like this: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.69&mainSearchCriteria.v.c=00310-0751-39&informationRecipient.languageCode.c=es
To send a text string without a medication code, you must identify your query as an NDC-type request so MedlinePlus Connect knows you are looking for medication information. This will work for English requests only. Your request could look like this: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.69&mainSearchCriteria.v.dn=Chantix%200.5%20MG%20Oral%20Tablet&informationRecipient.languageCode.c=en
Requests for Lab Test Information
MedlinePlus Connect provides matches to laboratory test information when receiving a LOINC request. The service can provide a response in English or Spanish.
The MedlinePlus Connect Web service will return the following:
- MedlinePlus lab test page title
- MedlinePlus lab test page URL
- Snippet of the content of the lab test information
- Source attribution for the content
There may not always be a match for each code. In those cases, MedlinePlus Connect will return a null response.
The base URL of the service is:
https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm
These are two required parameters for any lab test query to this service:
-
Code System
- Identify that you are using the LOINC code system. Use:
- mainSearchCriteria.v.cs=2.16.840.1.113883.6.1
- MedlinePlus Connect will also accept:
- mainSearchCriteria.v.cs=2.16.840.1.113883.11.79
-
Code
identify the actual code you are trying to look up: mainSearchCriteria.v.c=3187-2
Optional Parameters
Code TitleYou may also identify the name of the lab test. However, this information does not impact the response. mainSearchCriteria.v.dn=Factor IX assay
See the above section on Output Parameters for details on language and output formats.
Description of Selected Atom Elements (or JSON objects) in Response to Lab Test Requests
Element | Description |
---|---|
title | Title of matched MedlinePlus lab test page |
link | URL for matched MedlinePlus lab test page |
summary | Snippet from the page content |
author | Source attribution for the lab test content |
Examples of Requests for Lab Tests
To request information for an English speaker, your request may look like one of the following: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.1&mainSearchCriteria.v.c=3187-2&mainSearchCriteria.v.dn=Factor%20IX%20assay&informationRecipient.languageCode.c=en https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.1&mainSearchCriteria.v.c=3187-2&informationRecipient.languageCode.c=en
To request information for a Spanish speaker, your request may look like one of the following: https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.1&mainSearchCriteria.v.c=3187-2&mainSearchCriteria.v.dn=Factor%20IX%20assay&informationRecipient.languageCode.c=es https://apps.nlm.nih.gov/medlineplus/services/mpconnect_service.cfm?mainSearchCriteria.v.cs=2.16.840.1.113883.6.1&mainSearchCriteria.v.c=3187-2&informationRecipient.languageCode.c=es
Acceptable Use Policy
In order to avoid overloading the MedlinePlus servers, NLM requires that users of MedlinePlus Connect send no more than 100 requests per minute per IP address. Requests that exceed this limit will not be serviced, and service will not be restored for 300 seconds or until the request rate falls beneath the limit, whichever comes later. To limit the number of requests that you send to Connect, NLM recommends caching results for a 12-24 hour period.
This policy is in place to ensure that the service remains available and accessible to all users. If you have a specific use case that requires you to send a large number of requests to MedlinePlus Connect, and thus exceed the request rate limit outlined in this policy, please contact us. NLM staff will evaluate your request and determine if an exception may be granted. Please also review the MedlinePlus XML files documentation. These XML files contain complete health topic records and can serve as an alternate method of accessing MedlinePlus data.
More Information
- How MedlinePlus Connect Works
- Demonstrations — Web application and Web service
- Technical information for developers
- Frequently Asked Questions (FAQs)
- MedlinePlus Connect email list
- Contact MedlinePlus Connect