Skip Navigation Bar
National Library of Medicine Technical BulletinNational Library of Medicine Technical Bulletin

Table of Contents: 2012 JULY–AUGUST No. 387

Previous Next

MedlinePlus XML Files and Web Service Enhancements

Burgess S. MedlinePlus XML Files and Web Service Enhancements. NLM Tech Bull. 2012 Jul-Aug;(387):e1.

2012 July 03 [posted]

In June 2012, the National Library of Medicine (NLM) added new content and several new features to the MedlinePlus XML files and Web service. These enhancements make MedlinePlus XML data more robust, accessible, and flexible for users.

MedlinePlus XML Files

In June, NLM began publishing the MedlinePlus XML files in a new format with a new DTD. These files provide additional content that was not available in the earlier version of the files. The new XML files contain all MedlinePlus English and Spanish health topics and associated data, which includes:

  • basic metadata (health topic title, URL, language, date created, and ID),
  • vocabulary (MeSH, "Also called" terms, see references),
  • full summary,
  • group membership,
  • related health topics,
  • equivalent English or Spanish topics,
  • related content in other languages,
  • primary NIH institute, and
  • all site records (links) assigned to a health topic page, including their names, URLs, organizations, category assignments, and standard descriptions.

With this release, most text and links available on MedlinePlus health topic pages become accessible in XML format. For complete details on all elements and attributes in the MedlinePlus health topic XML, see the MedlinePlus XML file description.

NLM also publishes a health topic group XML file. The health topic group XML contains information on MedlinePlus topic groups and now uses a new format and DTD.

NLM updates and posts the new MedlinePlus health topic XML files daily (Tuesday-Saturday) in compressed (.zip) and uncompressed formats. All of the new MedlinePlus XML files are published daily to correspond to the update schedule of the Web site. Links to the six most recent XML data sets and the new DTDs are available from the MedlinePlus XML files page. NLM does not publish delta files for the new XML data sets.

To continue receiving the most up-to-date MedlinePlus information, users of the earlier version of the MedlinePlus XML files need to transition over to the new files. NLM will continue to post updated files using the earlier format and DTD through the end of July 2012. After July 2012, NLM will only publish updated XML content via the new version of the files, and earlier versions of the MedlinePlus XML files will no longer be available.

MedlinePlus Web Service

In June, NLM also added several new features, parameters, content, and policies to the MedlinePlus Web service. The MedlinePlus Web service allows systems to send keyword-based queries to retrieve matching health topics in XML format. Existing users can continue to send requests and receive responses in the same format as they were using prior to June. The enhancements to the MedlinePlus Web service are detailed below, and publicly available documentation reflects the changes.

NLM now offers a Spanish version of the MedlinePlus Web service that accepts Spanish-language queries and responds with Spanish health topics. Users can send requests to the MedlinePlus Spanish Web service by sending the healthTopicsSpanish value for the db parameter in their queries.

The MedlinePlus Web service also now allows for optional field searching in queries. Users can accomplish field searching by including limiters in the term parameter to restrict the search to a specific health topic field. Fields that can be searched this way are title, alt-title, mesh, full-summary, and group.

Users of the MedlinePlus Web service can use the new optional rettype parameter to select from three possible result formats: brief, topic, and all. By default, results are returned in brief format if no rettype is specified in the request. The brief format was the only format available prior to June. The topic format returns the health topic results as full XML records with all associated data and links. The XML format of the topic result type matches the format and DTD of health topics in the MedlinePlus XML files (as described in the first section of this article). The most significant feature of the topic format is the inclusion of all site records from MedlinePlus health topic pages, including encyclopedia links, multiple language links, organization links, and much more. The all format returns health topics in both brief and topic format.

Two new optional parameters, email and tool, allow Web service users to specify a contact email address and the resource using the Web service, respectively. Including these parameters in requests can assist NLM in providing better service and allows NLM to contact users if there are problems with their queries.

With the release of these new features, parameters, and content, NLM published a new acceptable use policy for the MedlinePlus Web service in June. To ensure that the Web service is continually available for all users, the new policy states:

"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. 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."

Users who are currently sending more than 85 requests per minute per IP address to the MedlinePlus Web service will need to adjust the number and/or frequency of requests in order to avoid request throttling, which will result in requests not being serviced until the request rate falls beneath the limit. Although NLM published this policy in June, enforcement will not begin until July 16 to give users time to come into compliance.

NLM encourages users of MedlinePlus data to subscribe to the MedlinePlus Web Service and XML Files email list to stay current on the latest changes and enhancements to these services. Send the MedlinePlus team any questions or feedback via the Contact Us link that appears on any page.

By Sarena Burgess
Public Services Division

NLM Technical Bulletin National Library of Medicine National Institutes of Health