Skip Navigation

TOXNET Web Service API Overview  Next Topic

TOXNET Web Service API - Search TOXNET Chemical Databases

TOXNET chemical databases include HSDB, CCRIS, GENETOX, IRIS, ITER, and LactMed. The TOXNET Web Service API allows users to search for keywords in one of these databases.

Search using HTTP GET requests

Base URL

http://toxgate.nlm.nih.gov/cgi-bin/sis/search/x?dbs+<db>:<keyword>

Required Parameters for Initial Search Requests

Parameter Name Description
db Database to search.
Valid database names are hsdb, ccris, genetox, iris, iter, and lact. Please note that the database name must be in lowercase.
keyword The keyword submitted to the web service.
Spaces should be replaced by '+' signs. Special characters should be replaced with a "%" followed by their ASCII code in hexadecimal. For very long queries (more than several hundred characters long), consider using the HTTP POST method.

Example

Search for benzene leukemia in the HSDB database.

URL for initial search: http://toxgate.nlm.nih.gov/cgi-bin/sis/search/x?dbs+hsdb:benzene+leukemia

Search Result:   Click here  (Please allow your browser to show blocked content by right clicking on the information bar.)

Search using HTTP POST requests

The TOXNET Web Service API provides query expansion through chemical synonyms, CAS registry numbers, and keyword stemming. These functions can only be called by using the POST method. Please refer to programming language-specific documents on how to issue HTTP POST requests.

Base URL

http://toxgate.nlm.nih.gov/cgi-bin/sis/search

Required Parameters

Parameter Name Description
queryxxx Keyword.
chemsyn Must be 1 to turn on query expansion with chemical synonyms and CAS Registry Number.
database Database to search.
Valid database names are hsdb, ccris, genetox, iris, iter, and lact. Please note that the database name must be in lowercase.
Stemming Must be 1 to turn on stemming.
and Must be 1.
second_search Must be 1.
gateway Must be 1.

Example

Search for benzene in HSDB database

URL for Initial Search:
http://toxgate.nlm.nih.gov/cgi-bin/sis/search

Required Parameters

Parameter Name Description
queryxxx benzene
chemsyn 1
database hsdb
Stemming 1
and 1
second_search 1
gateway 1

Sample Search

queryxxx
database
Stemming
and
chemsyn
second_search
gateway


1. Sample Java Source Code for HTTP POST Requests

//Adapted from http://www.javaworld.com/javaworld/javatips/javatip34/Happy.java
import java.net.*;
import java.io.*;
import java.util.*;

public class postview {

  public static void main (String args[]) {
    try
      {
        URL              url;
        URLConnection    urlConn;
        DataOutputStream printout;
        BufferedReader   input;

        // URL of CGI-Bin script.
        url = new URL ("http://toxgate.nlm.nih.gov/cgi-bin/sis/search/");
        // URL connection channel.
        urlConn = url.openConnection();
        // Let the run-time system (RTS) know that we want input.
        urlConn.setDoInput (true);
        // Let the RTS know that we want to do output.
        urlConn.setDoOutput (true);
        // No caching, we want the real thing.
        urlConn.setUseCaches (false);
        // Specify the content type.
        urlConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        // Send POST output.
        printout = new DataOutputStream (urlConn.getOutputStream ());
        String content = "queryxxx=benzene&database=hsdb&Stemming=1&" + "and=1&second_search=1&gateway=1&chemsyn=1";
        printout.writeBytes (content);
        printout.flush ();
        printout.close ();
        // Get response data.
        input =new BufferedReader(new InputStreamReader (urlConn.getInputStream()));
        String str;
        while (null != ((str = input.readLine())))
          {
            System.out.println (str);
          }
        input.close ();
      }

    catch (MalformedURLException me)
      {
        System.err.println("MalformedURLException: " + me);
      }
    catch (IOException ioe)
      {
        System.err.println("IOException: " + ioe.getMessage());
      }
  }
}

2. Sample wget Command for HTTP POST Requests

wget --post-data="queryxxx=benzene&database=hsdb&Stemming=1&and=1&second_search=1&gateway=1&chemsyn=1" "http://toxgate.nlm.nih.gov/cgi-bin/sis/search"

Search results

Search Result Example:   Click here  (Please allow your browser to show blocked content by right clicking on the information bar)

TOXNET API Response Format  
<QueryResult>
<Count>
</Count>
<DispMax>
</DispMax>
<Id>
</Id>
<TemporaryFile>
</TemporaryFile>
<Translation>
</Translation>
</QueryResult>

Description of Tags

Tag Name Description
QueryResult Basic node that contains the response.
Count Total number of records returned in the current search.
DispMax Maximum records displayed for each subsequent search. Default value = 20.
Id List of DOCNOs.
TemporaryFile A unique identifier used to specify the current search. Used in the subsequent search. Session will expire after 30 minutes of inactivity.
Translation A description of this search.

 

Subsequent Requests

URL: http://toxgate.nlm.nih.gov/cgi-bin/sis/search/g?<TemporaryFile>:<n>

Required Parameters for Subsequent Requests
Parameter Name Description
TemporaryFile The unique identifier returned in the initial search tag <TemporaryFile> which refers to the current search.
n n indicates to start at the (n+1)th record and display the following 20 records. Note: n starts at 0.

Example for Subsequent Requests

Get the next 20 short records starting from the 21st record.

URL:  http://toxgate.nlm.nih.gov/cgi-bin/sis/search/g?./temp/~zatH9T:20

Search Result:   Click here  (Please allow your browser to show blocked content by right clicking on the information bar.)

TOXNET API Response Format

<DocSumSet>
<Id>
</Id>
<DocSum>
<DOCNO>
</DOCNO>
<na>
</na>
<rn>
</rn>
</DocSum>
</DocSumSet>

Description of Tags  

Tag Name Description
DocSumSet Basic node that contains the response.
Id List of DOCNOs.
DocSum Document Summary.
DOCNO Document Number.
na Chemical Name.
rn CAS Registry Numbers.


Request a full record in chemical databases

This Web Service API provides full chemical records only in HTML format.

URL for requesting a full record in HTML format

http://toxgate.nlm.nih.gov/cgi-bin/sis/search/r?dbs+<db>:@term+@DOCNO+<DOCNO>

Required Parameters for Full Record Request

Parameter Name Description
db Database to search.
Valid database names are hsdb, ccris, genetox, iris, iter, and lact. Please note that the database name must be in lowercase.
DOCNO The record DOCNO.

Example

Retrieve a full benzene record DOCNO:35 from HSDB database in HTML format:

URL:  http://toxgate.nlm.nih.gov/cgi-bin/sis/search/r?dbs+hsdb:@term+@DOCNO+35

Complex search queries

Please consult the PISCES Query Language to formulate complex search queries using features such as Boolean operations, field-specific search, and wildcard characters.


Top