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	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:

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 " COKE 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">COKE 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 " COKE 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 " Coke Extract," and labeled " Coke. 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-Milk for Pigs and Hogs, Mor-Milk for Calves, and Mor-Milk 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-Milk for Pigs and Hogs, Mor-Milk for Calves, and Mor-Milk for Poultry</content>
<content name="defendantNames">Utley Noble, trading as the Mor-Milk 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-Milk for Pigs and Hogs, Mor-Milk for Calves, and Mor-Milk for Poultry. U. S. v. Utley Noble (Mor-Milk Co.). Plea of guilty. Fine, </content>
<content name="snippet"/>
</document>

Help | Web Service