Use Case 25: History for structured product labels

From Demand-Driven Open Data for HHS
Jump to: navigation, search

Use Case

Use case summary


  • Access to historical product labels via API
  • To access historical label revisions, rxData currently relies on Structured Product Labeling (SPL) public use files.
  • Additional issue (OpenFDA API response is missing HTML formatting markers, such as line breaks) has been broken out into a separate use case.
[Go to Use Case #45 Formatting on Structed Product Labels page] ➡


  • Value to customer: Looking at pharmaceutical market access in context of changing labeling information
  • Value to industry/public: Understand labeling changes, applicable across pharmaceutical industry


  • rxData for Prescription Drug labels
  • Fred Trotter for Prescription + OTC
  • Iodine

Current data and limitation

Drug labels

  • Data sources: DailyMed, OpenFDA, FDA Online Label Repository
  • Data sources with version history: DailyMed (API and download)

Fields relevant to version history in drug labels

DailyMed, FDA Online Label Repository (XML)

  • Per
    • <setId> is a GUID and is a unique identifier for the document that remains constant through all versions/revisions of the document.
    • <id root> is a Globally Unique Identifier (GUID) and is unique for each version of the document. Letters used in a GUID are lower case.
    • <versionNumber> is an integer greater than zero that provides a sequence to the versions of the document.
    • <effectiveTime> provides a date reference to the SPL version including the year, month and day as yyyymmdd.


  • Per the fields of the JSON schema relevant to versioning are:
    • set_id: The Set ID, A globally unique identifier (GUID) for the labeling, stable across all versions or revisions.
    • id: The document ID, A globally unique identifier (GUID) for the particular revision of a labeling document.
    • version: A sequentially increasing number identifying the particular version of a document, starting with 1.
    • effective_time: Date reference to the particular version of the labeling document.
"The openFDA drug product labeling API returns data from the FDA Structured Product Labeling (SPL) dataset. This dataset contains structured documentation about regulated products, submitted by manufacturers to FDA. OpenFDA uses the latest available bulk downloads, which have the latest version of every structured product labeling document for products that are actively marketed"


  • Fields:
    • SPL Set ID
    • PDF link
    • BLA number and supplement number
  • Update frequency:
  • Joins between datasets: SPL XMLs, AccessFDA database, OpenFDA Label API


Accessing previous versions of labels via API


SPL files are also available for download through DailyMed at National Library of Medicine (NLM) website: Choose from:

  • Human prescription or OTC full archive files
  • Daily, weekly or monthly periodic update files

Return the version history for a given setID in either json or xml.{SetID}/history.json{SetID}/history.xml example:

Return the specific version of a label. This will return a .zip file containing the label xml and all images and supporting files associated with that label. This is a new function and isn't yet documented on DailyMed.{SetID}&version={versionNumber} example:

Return all previous versions of the label in a .zip file. Each previous version is in a separate enclosed .zip file.{SetID}/ example:

Interpreting version history from downloaded XML files:

  • <setId>: GUID (globally unique ID) for the document that remains constant through all revisions
  • <id root>: GUID (globally unique ID) that's different and unique for each version of the document
  • <versionNumber>: Indicates revision count
  • <effectiveTime>: Date of this SPL version
    • Sections with <id> and <title> (such INDICATIONS AND USAGE, CLINICAL STUDIES, etc.) have <effectiveTime> that changes with each version.

Example for document-level version control:

 <id root="50606941-3e5d-465c-b4e0-0f5a19eb41d4"/>
 <code code="51725-0" codeSystem="2.16.840.1.113883.6.1"
 displayName="Establishment registration"/>
 <title>Establishment Registration</title>
 <effectiveTime value="20070424"/>
 <setId root="a30accef-f437-4136-808c-9ed4ada5fcf8"/>
 <versionNumber value="1"/>

Example for section-level version control:

<id root="62abedf9-6bde-4787-beb0-abd214307427"/>
<code code="34067-9"
displayName="Indications and Usage"/>
<title>Indications and Usage</title>
<text>labeling text</text>
<effectiveTime value="20070822"/>


View previous versions of labels

  • As of 6/25/2015: The OpenFDA staff have access to the full SPL files, but have not yet published revisions to their API. The SPL subject matter expert said he'll point out this use case and request that label revisions be added.
    • Currently the JSON response for a SPL on OpenFDA
      • Includes Document-level version control fields
      • But excludes section-level version control fields
    • Proposed solution:
      • By default, the JSON response should continue to include only the last version of SPL
      • Add an explicit query parameter, such as "showVersions", that would display all historical versions
    • There's no estimated commitment date yet.

obtaining a setID via RxNorm by providing an RXCUI

Another source: RxNorm

  • RxNorm data sources includes MTHSPL, which refers to "FDA Structured Product Labels"
  • It also has a RESTful Web API