Skip navigation

MedlinePlus Web Service

MedlinePlus offers a search-based Web service that provides access to MedlinePlus health topic data in XML format. Using the Web service, software developers can build applications that utilize MedlinePlus health topic information. The service accepts keyword searches as requests and returns relevant health topics in ranked order. Keyword searches may be limited to specific fields. The service also returns health topic summaries, search result snippets, external links, and other associated data.

To ensure that the latest information is readily available, the data in the Web service is updated daily, Tuesday - Saturday. The Web service is available for English and Spanish health topics. The Web service is free of charge and does not require registration or licensing. If you use data from the Web service or build an interface using the 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. If you have questions about the MedlinePlus Web service, or if you would like to share an application that you have built using the service, please contact us.

To receive notification when MedlinePlus releases enhancements to the service or updates the documentation, sign up for our Web service email updates:


Please note that the Web service only returns the subset of MedlinePlus health topic records that are relevant to the query in the request. If you need the full set of MedlinePlus health topics in XML format, see our XML files page. If you want to link patients or healthcare providers from electronic health record (EHR) systems to relevant MedlinePlus information, use MedlinePlus Connect. For a complete list of MedlinePlus resources available in XML format, see our XML data sources handout.

Description

Returns MedlinePlus health topic search results in English or Spanish for an input query string.

Acceptable Use Policy

In order to avoid overloading the MedlinePlus servers, NLM requires that users of the MedlinePlus Web service send no more than 85 requests per minute per IP address. Requests that exceed this limit will not be serviced, and service will not be restored until the request rate falls beneath the limit. The MedlinePlus Web service is updated once per day, Tuesday-Saturday. To limit the number of requests that you send to the Web service, 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. NLM encourages all users of the MedlinePlus Web service to use the email and tool parameters (as described below). NLM may use this information to contact you if there are problems with your requests.

If you have a specific use case that requires you to send a large number of requests to the Web service, 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.

Base URL

http://wsearch.nlm.nih.gov/ws/query

Parameters

Required Parameters for Initial Search Request

Parameter Name Description
db Database to search. Value must be a valid MedlinePlus Web service database name. Possible values are:
healthTopics - English health topics. Submit English-language queries when using this parameter.
healthTopicsSpanish - Spanish health topics. Submit Spanish-language queries when using this parameter.
term Text query submitted to the Web service. All special characters must be URL encoded. Spaces may be replaced by '+' signs, which represent the AND operator. Represent the OR operator as +OR+. To send a query as a phrase, enclose the phrase in quotes using %22 to represent quotation marks.
Required Parameters for Initial Search Request

Examples:
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=%22diabetes+medicines%22+OR+%22diabetes+drugs%22
http://wsearch.nlm.nih.gov/ws/query?db=healthTopicsSpanish&term=asma

Field Searching

The text for term can include limiters to restrict the search to a specific health topic field. The syntax is <fieldName>:<fieldValue>. Fields that can be searched in this way are:

title
alt-title
mesh (only available for English-language searches)
full-summary
group

See the Output Format section below for a description of each of these fields. Use field searching carefully, as it can have a significant impact on the order in which results are returned. Please note that when group field searching is used by itself and with no other parameters, all documents will be returned with the same relevancy ranking (rank="0").

Example:
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=title:asthma

Required Parameters for Subsequent Requests

Parameter Name Description
file Name of the file containing the document references for the current search. This parameter is required when retstart is being used. The value is obtained from the XML returned from the initial search. The file will expire after a certain period of inactivity, after which a new request must be initiated. If the file is expired, the XML output will contain an error message.
server Name of the server with the file referenced by the file parameter. This is required when the file parameter is being used.
retstart Sequential index of the first document in the retrieved set to be shown in the XML output (default=0, corresponding to the first record of the entire set). This parameter can be used in conjunction with retmax to download an arbitrary subset of documents retrieved from a search.
Required Parameters for Subsequent Requests

Example:
http://wsearch.nlm.nih.gov/ws/query?file=viv_0Uu9LP&server=qvlbsrch04&retstart=20

Optional Parameters

Parameter Name Description
retmax Total number of documents from the retrieved set to be shown in the XML output (default=10). By default, the web service only includes the first 10 documents retrieved in the XML output. Increasing retmax allows more of the retrieved documents to be included in the XML output.
rettype Retrieval type. This parameter specifies the format of the results. By default, results will be returned in brief format if no rettype is specified in the request. To specify a retrieval type, use one of the following possible values:
brief - Returns the health topics as search results with abbreviated health topic records, keyword-in-context highlighting, and snippets (default).
topic - Returns the health topics as full XML records with all associated vocabulary and links.
all - Returns health topics in both brief and topic format.
tool A string with no internal spaces that identifies the resource which is using the Web service (e.g., tool=nihseniorhealth). This argument is used to help NLM provide better service to third parties using the Web service from programs. As with any query system, it is sometimes possible to ask the same question different ways, with different effects on performance. NLM requests that developers sending a large volume of requests include a constant 'tool' argument for all requests using the Web service.
email Email address. If you choose to provide an email address, NLM may use it to contact you if there are problems with your queries. In addition to using the email address parameter, we encourage all Web service users to sign up for the email list referenced at the top of this page to receive general announcements and notifications of changes to the service.
Optional Parameters

Examples (retmax):
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=diabetes&retmax=50
http://wsearch.nlm.nih.gov/ws/query?file=viv_0Uu9LP&server=qvlbsrch04&retstart=30&retmax=20

Examples (rettype):
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma&rettype=brief
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma&rettype=topic
http://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma&rettype=all

Output

Output Type

XML

XML Response Format

The following is the basic structure of the XML returned:

<nlmSearchResult>

</term>

</file>

</server>

</count>

</retstart>

</retmax>

</spellingCorrection>

<list>

<document>

<content />

</document>
</list>

</nlmSearchResult>

The rettype parameter in the URL request determines the format and type of information contained within the <content> element. See below for more information on the content element.


Descriptions of Elements

Element Name Description
nlmSearchResult Basic XML node that contains the response (has no attributes)
term Text query submitted to the Web service
file Name of the file containing the document references for the current search
server Name of the server with the file referenced by the file parameter
retstart Sequential index of the first document in the retrieved set shown in the XML output
retmax Total number of documents from the retrieved set shown in the XML output
count The number of documents in the current result set (non-negative integer)
spellingCorrection Suggested alternative search with a different spelling of the word(s) in the query term(s). This element is not always present.
list The containing element for all of the retrieved documents
document An individual document (MedlinePlus health topic record)
Descriptions of Elements

 

Document Element Description

Attribute Type Description
url Text MedlinePlus health topic page URL
rank Non-negative integer Rank of the document in the results. The rank is based on the relevance score as determined by the search engine. Generally, the first document in the first results set will have a rank of zero, and the next document will have a rank of 1, 2, 3, etc. However, if the query string matches a health topic's title or altTitle, that topic will be boosted to the top, regardless of the rank. In these cases the first document in the first results set may have a rank greater than zero.
content Text  Specifies some text associated with its parent document, the MedlinePlus health topic record. The content nodes will vary depending on the value of the rettype URL parameter.
Document Element Description

 

Content Element Description for brief Retrieval Type

For rettype=brief, the value of content nodes will contain query term identification in the form of tags. The query term will be identified in the tag as qt0, qt1, qt2, etc.

Attribute Type Description
name Text The name of the content node. Allowed values are: title, organizationName, altTitle, fullSummary, mesh, groupName, snippet. (See below for a description of content node values.)
Content Element Description for brief Retrieval Type

 

The content nodes are as follows:

Content Name Attribute Value Description
title Name of the MedlinePlus health topic page
organizationName Organization that produced the MedlinePlus topic page. Value will always be "National Library of Medicine" for English and "Biblioteca Nacional de Medicina" for Spanish.
altTitle See reference(s) and synonym(s) for the topic. See references and synonyms are undifferentiated in the XML.
FullSummary Text summary of the topic. HTML formatting will be present.
mesh Medical Subject Heading(s) assigned to the topic.
groupName Group(s) to which the topic belongs. A complete list of groups can be found on the MedlinePlus health topics landing page in English and Spanish.
snippet Brief result summary generated by the search engine that provides a preview of the relevant content on the topic page.
Content Name Attribute Value description

Example:

- <document rank="0" url="http://www.nlm.nih.gov/medlineplus/diabetesmedicines.html">
  <content name="title"><span class="qt0">Diabetes</span> <span class="qt1">Medicines</span></content>
  <content name="organizationName">National Library of Medicine</content>
  <content name="altTitle">Insulin</content>
  <content name="altTitle">Hypoglycemic <span class="qt1">Medicines</span></content>
  <content name="FullSummary"><p><span class="qt0">Diabetes</span> means your blood glucose, or blood sugar, is too high. If you can't control your <span class="qt0">diabetes</span> with wise food choices and physical activity, you may need <span class="qt0">diabetes</span> <span class="qt1">medicines. The kind of medicine</span> you take depends on your type of <span class="qt0">diabetes</span>, your schedule, and your other health conditions. </p><p>With Type 1 <span class="qt0">diabetes</span>, your pancreas does not make insulin. Insulin is a hormone that helps glucose get into your cells to give them energy. Without insulin, too much glucose stays in your blood. If you have type 1 <span class="qt0">diabetes</span>, you will need to take insulin. </p><p>Type 2 <span class="qt0">diabetes</span>, the most common type, can start when the body doesn't use insulin as it should. If your body can't keep up with the need for insulin, you may need to take pills. Some people need both insulin and pills. Along with meal planning and physical activity, <span class="qt0">diabetes</span> pills help people with type 2 <span class="qt0">diabetes</span> or gestational <span class="qt0">diabetes</span> keep their blood glucose levels on target. Several kinds of pills are available. Each works in a different way. Many people take two or three kinds of pills. Some people take combination pills. Combination pills contain two kinds of <span class="qt0">diabetes</span> <span class="qt1">medicine</span> in one tablet. Some people take pills and insulin.</p><p>NIH: National Institute of <span class="qt0">Diabetes</span> and Digestive and Kidney Diseases</p></content>
  <content name="mesh">Hypoglycemic Agents</content>
  <content name="mesh">Insulin</content>
  <content name="groupName">Endocrine System</content>
  <content name="groupName">Drug Therapy</content>
  <content name="groupName"><span class="qt0">Diabetes Mellitus</span></content>
  <content name="snippet">... food choices and physical activity, you may need <span class="qt0">diabetes</span> <span class="qt1">medicines. The kind of medicine</span> you take depends on ... combination pills. Combination pills contain two kinds of <span class="qt0">diabetes</span> <span class="qt1">medicine</span> in one tablet. Some people take pills and ...</content>
  </document>

Content Element Description for topic and all Retrieval Types

For rettype=topic there will be one content node content@name=healthTopic. This content node will be followed by the health topic data in XML. For complete documentation on the MedlinePlus health topic XML format, see the MedlinePlus XML files page, DTD, and description.

For rettype=all, all the above content nodes may be present, since this rettype returns both the brief and topic formats.