USGS - science for a changing world

Science Topics

Thesaurus term web services

Several web services provide information from the USGS Thesaurus and related controlled vocabularies in JSONP format. These services enable web pages to obtain detailed information about thesaurus terms for use in dynamic web interfaces. An example web page making use of these services is at http://www.usgs.gov/science/tab-term.html

A term search service supports the jQuery autocomplete function, returning an array of objects describing thesaurus terms that begin with the given text. The match is not case sensitive.
Service URL http://www.usgs.gov/science/term-search.php
Parameters
thcode Thesaurus identifier; if not specified, the USGS Thesaurus will be used
term Fragment of text to match candidate terms
callback Name of a function in which to wrap the results, to support JSONP
uf Set to zero to exclude non-preferred terms from the results
Output An array of objects, each containing the following members:
thcode Unique identifier for the thesaurus (same as input thcode value)
code Unique identifier for a term within the thesaurus
label Text matching the input string, may be the non-preferred term
value Descriptor text of the matched thesaurus term

Special cases

  1. If no term is given, the service returns an empty array: http://www.usgs.gov/science/term-search.php
  2. If a percent sign is specified as the term, the service returns all of the terms in the given thesaurus alphabetically: http://www.usgs.gov/science/term-search.php?thcode=2&term=%

Example

(line breaks and extra spaces added here for clarity)

http://www.usgs.gov/science/term-search.php?term=con

Provides detailed information about a given thesaurus term, which may be specified by its unique identifier or by the text of its descriptor. If a text is given as input and the text matches a USE-WITH term, the result will be an array describing the two descriptors to which the USE-WITH term applies.
Service URL http://www.usgs.gov/science/term.php
Parameters
thcode Thesaurus identifier; if not specified, the USGS Thesaurus will be used
code Unique identifier of the descriptor
text Text of the descriptor, if descriptors are distinct in the specified thesaurus
callback Name of a function in which to wrap the results, to support JSONP
Output A single object or an array of two objects containing the following members:
thcode Thesaurus identifier
term Single term object specifying the term, as follows:
code Unique identifier for this term
name Descriptor text for this term
parent Unique identifier of the parent of this term
scope Scope note for the term
uf Array of objects specifying USE-FOR and USE-WITH relationships:
name Text of the non-preferred term
usewith false for a simple non-preferred term, or a term object if the text is to be used for both the given descriptor and another descriptor together
bt Array of term objects specifying the broader terms, each the parent of the previous entry
nt Array of term objects specifying the narrower terms
rt Array of term objects specifying the related terms

Special cases

  1. If no parameters are given, the service returns an array of objects describing the thesauri that are available in the current database instance: http://www.usgs.gov/science/term.php
  2. If a valid thesaurus code is given but neither a term code nor a descriptor is given, the root node of the thesaurus will be returned: http://www.usgs.gov/science/term.php?thcode=2
  3. If a text given as input matches a USE-WITH term, an array of descriptors will be returned, each as described for a single term, above. http://www.usgs.gov/science/term.php?thcode=2&text=oil%20spills
  4. If a pair of terms is given as input with " AND " between them, the two terms are matched separately and an array of descriptors will be returned, each as described for a single term, above. http://www.usgs.gov/science/term.php?thcode=2&text=industrial%20pollution%20AND%20petroleum

Example

http://www.usgs.gov/science/term.php?code=769

Provides information about specific named things (for example events, geographic features, products) that would not be included in the thesaurus because they are not a type of thing. Each named thing is associated with one or more descriptors from any of the thesauri that we use, and a qualifying term is used to categorize the relationship.
Service URL http://www.usgs.gov/science/inst.php
Parameters
name Name of the thing for which related terms are requested; this will be matched without regard for letter case to the named instances or their non-preferred variants
callback Name of a function in which to wrap the results, to support JSONP
Output A single object containing the following members:
name The name of the thing requested, as it appears in the database
scope A short descriptive text intended to indicate sufficient detail that the named thing can be understood properly
relatedTerm Array of objects indicating thesaurus descriptors that might help to provide additional information about the named thing:
relation A short category term indicating the relationship the term has to the named thing
descriptor A complete term descriptor, indicating the thcode identifier of the thesaurus in which the descriptor is found, with all of its related terms, using the data structure returned by the term details service (above)

Special cases

  1. If no parameters are given, the service returns an array of named things for which we have related terms. http://www.usgs.gov/science/inst.php

Example

http://www.usgs.gov/science/inst.php?name=Mount%20St.%20Helens

Service providing descriptors that are associated with the group headings shown on the Science Topics home page or the Newsroom category page. These group headings are not themselves terms in any thesaurus, but exist to help people navigate to some thesaurus term relevant to their concerns, from which they can select broader, narrower, or related thesaurus terms.
Service URL http://www.usgs.gov/science/newsroom.php
http://www.usgs.gov/science/top.php
Parameters
heading Group heading for which related terms are requested; this will be matched without regard for letter case
callback Name of a function in which to wrap the results, to support JSONP
Output A single object containing the following members:
heading The group heading requested, as it appears in the database
list Array of items appearing under that heading, each of which contains:
thcode Thesaurus identifier
name Text to be displayed in the group
term Array of one or two term objects specifying the terms forming the concept identified, each as follows:
code Unique identifier for this term
name Descriptor text for this term
parent Unique identifier of the parent of this term
scope Scope note for the term

Special cases

  1. If no parameters are given, the service returns an array of group headings. http://www.usgs.gov/science/top.php

Example

http://www.usgs.gov/science/newsroom.php?heading=Energy

A service providing Science Topics catalog records that have been assigned a given thesaurus term or one of its narrower terms.
Service URL http://www.usgs.gov/science/records-matching.php
Parameters
thcode Thesaurus identifier (numeric)
code Unique identifier of the descriptor within the given thesaurus
Output An array of citation records, with these properties:
cite Unique identifier (numeric) of the catalog record in the Science Topics database
title Title of the resource
onlink Web link to the resource
description Short text describing the resource, intended to help people decide whether or not to click the web link
format If the resource is a PDF document, this will contain "PDF"
record_url Web link to a catalog record page for this resource within the Science Topics interface
categories Array of descriptors assigned to this record. Each element contains
thcode Unique identifier (numeric) for the thesaurus containing this term
code Unique identifier for this term within the given thesaurus
name Descriptor text for this term
parent Unique identifier of the parent of this term
scope Scope note for the term

Example

(line breaks and extra spaces added here for clarity)

http://www.usgs.gov/science/records-matching.php?thcode=2&code=916

A service providing a text search pattern for a given thesaurus term
Service URL http://www.usgs.gov/science/search-pattern.php
Parameters
text Descriptor text, if code is not given. Thesauri will be searched using this text, and the information returned will reflect that associated with the descriptor matched, if the given text matches a non-preferred term.
thcode Thesaurus identifier (numeric)
code Unique identifier of the descriptor within the given thesaurus
thalso Thesaurus identifier (numeric) for the term identified using also
also Unique identifier of a second descriptor within the thesaurus identified using thalso, if that is specified, or thcode if thalso is not specified
Output An object containing information about the descriptor and texts that may be used as the pattern for searching.
thcode Thesaurus identifier
term Array of term objects specifying the term or terms, each element containing:
code Unique identifier for this term
name Descriptor text for this term
parent Unique identifier of the parent of this term
scope Scope note for the term
customized A customized search pattern developed by the USGS Web Re-Engineering Team staff, if a custom search pattern has been developed for this term.
default A search pattern composed from the descriptor text, the non-preferred terms, all of the narrower terms, and their non-preferred terms.

Example

(line breaks and extra spaces added here for clarity)

http://www.usgs.gov/science/search-pattern.php?thcode=2&code=769

Accessibility FOIA Privacy Policies and Notices

Take Pride in America logo USA.gov logo U.S. Department of the Interior | U.S. Geological Survey
URL: http://www.usgs.gov/science/tab-term.html
Page Contact Information: Ask USGS
Page Last Modified: Friday, 12-Sep-2014 10:39:26 EDT