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. 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.
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. If you are looking for data from MedlinePlus Genetics, please see MedlinePlus Genetics Data Files & API.
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
https://wsearch.nlm.nih.gov/ws/query
Please use https instead of http. If you are already using the MedlinePlus web service with http, please update your code to https.
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. |
Examples:
https://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma
https://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=%22diabetes+medicines%22+OR+%22diabetes+drugs%22
https://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:
https://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. |
Example:
https://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=myservicename). 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 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. |
Examples (retmax):
https://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=diabetes&retmax=50
https://wsearch.nlm.nih.gov/ws/query?file=viv_0Uu9LP&server=qvlbsrch04&retstart=30&retmax=20
Examples (rettype):
https://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma&rettype=brief
https://wsearch.nlm.nih.gov/ws/query?db=healthTopics&term=asthma&rettype=topic
https://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) |
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. |
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.) |
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. |
Example:
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.