Documentation for Using the REMOTE


	Home


	News


	Compliance Assistance Tools


	Environmental Security


	Topic Directory


	Industry & Gov't Sectors


	Environmental Topics


	Geographic Locations


	Expert Directory


	Planned and Ongoing Activities


	Measures


	Regulations


	Current EPA Priorities


	ECCAT - Compliance Tools Compendium

Clearinghouse Home red arrow

Partner Sites red arrow

Clearinghouse Web Services red arrow

Search the Clearinghouse from Your Site!

Using the REMOTE_SEARCH Web Service

This web service provides access to most of the search functionality available on our Advanced Search Page. It allows you to export data from the Clearinghouse in a variety of formats, including comma separated variables (CSV - used by most popular database and spreadsheet programs) and WDDX (used by many Cold Fusion web sites). Use this service to download your own copy of the Clearinghouse database, or to provide a "Search the Clearinghouse" feature to your web site. You may search by keywords or Clearinghouse topics.

Syntax

The REMOTE_SEARCH function recognizes the following parameters. These may be sent in the URL using a HTTP "GET" request, or in the body of the request using the HTTP "POST" method. "Mixed" requests are not recognized. For most applications, a "GET" request should work fine, though for long search terms, remember that there are limits on how long the URL parameters can be. The order of the parameters is not important.

Please note that parameters indicated as "required" MUST be present for the REMOTE_SEARCH function to work. Failure to include these parameters will generally return an error.

Table 1. Parameters Recognized by REMOTE_SEARCH
METHOD
required Tells REMOTE_SEARCH which of it's methods to employ. Currently, the only allowed value is GETLINKS
SEARCH_TERMS
Search terms which will be used to search the Clearinghouse. Default is to return results matching one or more terms. See note below regarding Advanced Search Features. This parameter is required unless the TOPIC_ID is specified.
TOPIC_ID
One or more TOPIC_IDS from the Clearinghouse's topic directory. If a value is provided for this parameter, the search will be limited to this topic.
SEARCHMODE
Used with TOPIC_ID. Allows user to restrict search to single topic, or all subtopics. Must be one or more of the following Values: [THISTOPIC\|INCLUDESUBTOPICS]. Default is THISTOPIC, which limits search to only the topic specified.
RESOURCE_TYPE
Restricts the search to resources of a specific type. One or more of the following Values: [TOOLS\|CONTACT\|FAQ\|OVERVIEW\|WEBSITE\|OTHER]
DISPLAY_MODE
Determines which format the results will be presented in. Allowed values are [CSV\|RSS\|WDDX]. Default is RSS.
SORT_ORDER
Determines which field used to sort the results. Must be one of the following values: [RELEVANCE\|TITLE\|URL]. The default is "RELEVANCE"

Using the Results from REMOTE_SEARCH

The REMOTE_SEARCH function returns the results of the search, formatted in the requested data format (CSV, RSS or WDDX formats). Field names are provided as the first row on CSV results; they are used as tag (element) names on the XML formats (WDDX, RSS). The function returns the following fields:

Table 2. Fields Returned by REMOTE_SEARCH
RESOURCE_ID
This is the unique record identifier for the Clearinghouse. It is a long integer value.
URL
This is the full URL of the web link, which may be up to 255 characters in length.
TITLE
This is the title of the resource, which may be up to 255 characters in length.
DESCRIPTION
This is the full description of the resource, which may be up to 4000 characters in length.
RESOURCE_TYPE
This is a flag used to indicate which of the Clearinghouse's primary resource types best describes the resource. Allowed values are TOOLS, CONTACT, FAQ, WEBSITE, NEWS, OVERVIEW, OTHER and UNKNOWN.

If no results are found, or if the request for data is not understood, the REMOTE_SEARCH function cannot return the expected data set. Instead, the REMOTE_SEARCH function returns one of the following error messages:

Table 3. Error Messages Returned by REMOTE_SEARCH
`<CLEARINGHOUSE_ERROR>No records were found matching your query</CLEARINGHOUSE_ERROR>`
This is the error returned when no records are returned (for example, if a search is too narrow or contains misspelled terms).
`<CLEARINGHOUSE_ERROR>The method you requested was not recognized (UNKNOWN_METHOD)</CLEARINGHOUSE_ERROR>`
This error is returned when an incorrect argument is provided for the METHOD parameter. Currently, only the "METHOD=GetLinks" value is recognized.

The brackets (> and <) are included in all formats, including CSV. Web developers planning on using the REMOTE_SEARCH web service should be sure to check for these messages prior to processing the data retrieved from the web service.

Notes on Advance Search Features

The Clearinghouse Search function supports a range of features which allow advanced users to focus their searches by restricting which fields are searched. Simple Boolean searches are also supported, allowing you to search for specific combinations of words (for example, "Pollution" AND "Prevention").

Table 4. Advanced Search Options Supported by REMOTE_SEARCH
+[search string]
The "+" sign ensures that only results containing [search string] are included in the search results. Equivalent to a logical "AND."
-[search string]
The "-" sign ensures that only results NOT containing [search string] are included in the search results. Equivalent to a logical "NOT."
"[search string]"
Enclosing the search term in quotes treats the term as a complete phrase. Only resources matching the exact phrase will be returned (case insensitive).
url:[search string]
Searches for [search string] only in the URL field. This is useful for searching for sites in a specific domain -- e.g., including the phrase "url:www.epa.gov/region02/" will return only those sites hosted on EPA's Region 2 web site.
title:[search string]
Searches for [search string] only in the Title field.
description:[search string]
Searches for [search string] only in the Description field.

Example

A simple example is provided below. Use this URL to obtain a Comma Separated Variable export of all resources in the "Chemical Industry" topic (C:10:900:325:) which contain the word "Audit" in the title. By customizing the search terms used, you can search for other information on the Clearinghouse just as easily. You could then use this file to create your own database of web resources by importing the file into your favorite database or spreadsheet program.

http://cfpub2.epa.gov/clearinghouse/webservices/remote_search.cfm?METHOD=GETLINKS&TOPIC_ID=C:10:900:325:&SEARCH_TERMS=title:audit&DISPLAY_MODE=CSV

For More Information

If you would like more information about how to implement Clearinghouse web services, please contact Scott Butner at 509-372-4946 (scott.butner@pnl.gov).

URL: http://cfpub1.epa.gov/clearinghouse/webservices/about_remote_search.cfm
Last Updated: Tuesday, May 13, 2008