FDA Notices of Judgment Web Service
Help | Web Service
The FDA Notices of Judgment digital archive offers a search-based Web service that provides access to the metadata and full-text OCR from the repository in XML format. Developers can use the Web service to build applications that query and link to these resources.
The service accepts keyword and fielded searches as requests. Results are returned in order of relevancy. Keyword searches may also be limited to specific metadata fields. The returned results represent the subset of Notices of Judgment resources that are relevant to the query in the request.
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 the FDA Notices of Judgment digital archive. If you have questions about the Web service, or if you would like to share an application that you have built using the service, please contact us.
Acceptable Use Policy
In order to avoid overloading our servers, NLM requires that users of the FDA Notices of Judgment 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 FDA Notices of Judgment Web service is a static data set; updates may be made on an infrequent, ad hoc basis. 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 ensures that the service remains available and accessible to all users. NLM encourages all users of the FDA Notices of Judgment 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 which exceeds 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.
Base URL
https://wsearch.nlm.nih.gov/ws/query
Parameters
Parameters for Initial Search Request
There are two parameters the must be included in the initial search request to define the database being searched and the search query.
Parameter Name | Required | Description |
---|---|---|
db |
Yes |
Database to search. Value must be "fdanj". |
term |
Yes |
Term submitted to the Web service as a text query. All special characters must be URL encoded. Spaces may be replaced by '+' signs, which represents 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=fdanj&term=cola
https://wsearch.nlm.nih.gov/ws/query?db=fdanj&term=%22lash+lure%22
https://wsearch.nlm.nih.gov/ws/query?db=fdanj&term=%22amphetamine%22+OR+%22secobarbital%22
Field Searching
The text for the query term can include limiters to restrict the search to a specific metadata field. Field values that can be searched include:
- title
- caseNumber
- collection
- evidenceNumbers
- dateIssued
- seizureDates
- productKeywords
- defendantNames
- courtJurisdiction
- seizureLocation
- shippedFrom
- shippedTo
- full-text
See the Output Format section below for a description of each of these fields.
Examples:
https://wsearch.nlm.nih.gov/ws/query?db=fdanj&term=title:cola
https://wsearch.nlm.nih.gov/ws/query?db=fdanj&term=caseNumber:101
https://wsearch.nlm.nih.gov/ws/query?db=fdanj&term=courtJurisdiction:%22Southern District of Texas%22
Parameters for Subsequent Requests
The parameters listed below are used to retrieve subsequent results related to the initial search query request.
Parameter Name | Required | Description |
---|---|---|
file |
Yes |
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 |
Yes |
Name of the server with the file referenced by the file parameter. This is required when the file parameter is being used. |
retstart |
Yes |
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 (retstart):
https://wsearch.nlm.nih.gov/ws/query?file=viv_briwYO&server=pvlbsrch05&retstart=10
Optional Parameters
These parameters may be used in initial or subsequent search requests.
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. |
tool |
A string with no internal spaces that identifies the resource which is using the Web service (e.g., tool=your_tool_name). 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. |
Example (retmax):
https://wsearch.nlm.nih.gov/ws/query?file=viv_briwYO&server=pvlbsrch05&retstart=20&retmax=30
Output Format
Output Type
The Web Service returns XML using the markup defined in this document.
XML Response Format
The following is the basic structure of the XML returned by the Web service. This XML file does not have any style information associated with it. The document tree is shown below:
<nlmSearchResult><term>...</term>
<file>...</file>
<server>...</server>
<count>...</count>
<retstart>...</retstart>
<retmax>...</retmax>
<list>
<document>
<content name="title">...</content>
<content name="caseNumber">...</content>
<content name="collection">...</content>
<content name="evidenceNumbers"> ...</content>
<content name="dateIssued">...</content>
<content name="seizureDates">...</content>
<content name="productKeywords">...</content>
<content name="defendantNames">...</content>
<content name="courtJurisdiction">...</content>
<content name="seizureLocation">...</content>
<content name="shippedFrom">...</content>
<content name="shippedTo">...</content>
<content name="full-text">...</content>
<content name="snippet"/>
</document>
</list>
</nlmSearchResult>
Descriptions of Elements
The element names for the Web Service are described below:
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. |
count |
The number of documents in the current result set (non-negative integer). |
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. |
list |
The element containing all of the retrieved <document>s. |
document |
An individual resource from the Notices of Judgment repository. |
content |
The element containing details of the metadata which are defined by the name attribute. |
List Element Description
The list element includes three attributes; num, start, and per.
Attribute | Type | Description |
---|---|---|
num |
Non-negative Integer |
Total number of results retrieved for the search query term. |
start |
Non-negative Integer |
Sequential index of the first document in the retrieved set shown in the XML output (see retstart). |
per |
Non-negative Integer |
Total number of documents from the retrieved set shown in the XML output (see retmax). |
Document Element Description
The document element includes two attributes; url and rank.
Attribute | Type | Description |
---|---|---|
url |
Text |
The URL for the resource. |
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 resource's title, 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 Element Description
The content element includes one attribute; name.
Attribute | Type | Description |
---|---|---|
name |
Text |
The name of the content node. Allowed values are: title, caseNumber, collection, evidenceNumbers, dateIssued, seizureDates, productKeywords, defendantNames, courtJurisdiction, seizureLocation, shippedFrom, shippedTo, full-text. See description of content node values listed below. |
The content nodes for the name attribute include the following values:
Content Name Attribute Value |
Occurrences | Description |
---|---|---|
title |
One |
Title of the court case. |
caseNumber |
One |
Court case number. |
collection |
One |
Acronym of the sub-collection to which the case belongs. Values are fdnj=Combined Foods and Drugs; ddnj=Drugs and Devices; ffnj=Foods; csnj=Cosmetics. |
evidenceNumbers |
One or more |
Internal evidence control numbers including F&D (Food and Drug), S (Sample), IS (Interstate Sample) numbers. Evidence files in the archival collection are filed according to the S and IS numbers. |
dateIssued |
Zero or more |
Date the judgment summary was published. |
seizureDates |
One or more |
Dates the products were seized by FDA agents. |
productKeywords |
One or more |
Topical subjects of the resource; values do not come from a controlled vocabulary. |
defendantNames |
Zero or more |
Personal and corporate names of the defendants in the case. |
courtJurisdiction |
One or more |
Name of federal court jurisdiction where the case was tried. |
seizureLocation |
Zero or more |
Geographc location where the products were seized. |
shippedFrom |
Zero or more |
Geographc location from where the products were originally shipped. |
shippedTo |
Zero or more |
Geographc location to where the products were shipped or intended to be shipped. |
full-text |
One |
Full-text extracted, uncorrected OCR of the case summary. |
Example:
<document rank="0" url="https://fdanj.nlm.nih.gov/catalog/fdnj00309">
<content name="size">27452823</content>
<content name="title">NOTICE OF JUDGMENT NO. 309, FOOD AND DRUGS ACT. MISBRANDING OF " <span class="qt0">COKE</span> EXTRACT." (SOFT DRINK CONTAINING COCAIN.)</content>
<content name="caseNumber">309</content>
<content name="collection">fdnj</content>
<content name="evidenceNumbers">I. S. No. 22162-a. F. & D. No. 698</content>
<content name="dateIssued">May 26, 1910</content>
<content name="seizureDates">January 6, 1909</content>
<content name="productKeywords"><span class="qt0">COKE</span> EXTRACT (SOFT DRINK CONTAINING COCAIN.)</content>
<content name="defendantNames">J. A. Scott</content>
<content name="courtJurisdiction">Northern District of Georgia</content>
<content name="seizureLocation">Georgia</content>
<content name="shippedFrom">Georgia</content>
<content name="shippedTo">Tennessee</content>
<content name="full-text">Issued May 26, 1910.? I. S. No. 22162-a.? F. & D. No. 698. United States Department of Agriculture,
OFFICE OF THE SECRETARY. NOTICE OF JUDGMENT NO. 309, FOOD AND DRUGS ACT. MISBRANDING OF " <span class="qt0">COKE</span> EXTRACT."
(SOFT DRINK CONTAINING COCAIN.) On or about January 6, 1909, J. A. Scott, of Atlanta, Ga., doing?
business under the name and style of the Kumfort Company, shipped? from the State of Georgia into the State of Tennessee a consignment?
of a product known as " <span class="qt0">Coke</span> Extract," and labeled " <span class="qt0">Coke</span>. Bottled?
by Kumfort Company, Atlanta, Ga. Guaranteed under State and?
National food laws." A sample from this shipment was procured?
and analyzed by the Bureau of Chemistry, United States Depart??
ment of Agriculture, and as the findings of the analyst and report?
thereon indicated that the product was misbranded within the mean??
ing of the Food and Drugs Act of June 30, 1906, the Secretary of?
Agriculture afforded the Kumfort Company, and the dealer from?
whom the sample was purchased, opportunities for hearings. As it?
appeared after hearings held that the shipment was made in viola??
tion of the act, the Secretary of Agriculture reported the facts to?
the Attorney General with a statement of the evidence on which to?
base a prosecution.
In due course a criminal information was filed against the said?
J. A. Scott in the District Court of the United States for the North??
ern District of Georgia charging the above shipment and alleging?
that the product was misbranded, in that it contained cocain, and did?
not bear a statement on the label showing the quantity or proportion?
of cocain contained therein.
On October 15, 1909, said defendant entered a plea of guilty and?
the court imposed upon him a fine of </content>
<content name="snippet"/>
</document>
Search Term Highlighting (Keyword-in-Context)
The query term is identified in the content nodes using span tags. Each instance of the query term includes a class attribute equal to qt0, qt1, qt2, etc. Use these tags to apply highlighting the search terms in your user interface.
Example:
<document rank="0" url="https://fdanj.nlm.nih.gov/catalog/ddnj01341">
<content name="size">27452823</content>
<content name="title">1341. Misbranding of Mor-<span class="qt0">Milk</span> for Pigs and Hogs, Mor-<span class="qt0">Milk</span> for Calves, and Mor-<span class="qt0">Milk</span> for Poultry. U. S. v. Utley Noble ...</content>
<content name="caseNumber">1341</content>
<content name="collection">ddnj</content>
<content name="evidenceNumbers">F. D. C. No. 11335. Sample Nos. 32090-F, 32091-F, 37312-F, 37967-F.</content>
<content name="dateIssued">November 1945</content>
<content name="seizureDates">February 2 and April 30, 1943</content>
<content name="productKeywords">Mor-<span class="qt0">Milk</span> for Pigs and Hogs, Mor-<span class="qt0">Milk</span> for Calves, and Mor-<span class="qt0">Milk</span> for Poultry</content>
<content name="defendantNames">Utley Noble, trading as the Mor-<span class="qt0">Milk</span> Co., Dixon, Ill.</content>
<content name="courtJurisdiction">Northern District of Illinois</content>
<content name="seizureLocation">Illinois</content>
<content name="shippedFrom">Illinois</content>
<content name="shippedTo">Indiana, Pennsylvania</content>
<content name="full-text">1341. Misbranding of Mor-<span class="qt0">Milk</span> for Pigs and Hogs, Mor-<span class="qt0">Milk</span> for Calves, and Mor-<span class="qt0">Milk</span> for
Poultry. U. S. v. Utley Noble (Mor-<span class="qt0">Milk</span> Co.). Plea of guilty. Fine, </content>
<content name="snippet"/>
</document>
Help | Web Service