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 https://apps.usgs.gov/thesaurus/tab-term.html

Thesaurus info

Provides a list of thesauri available through these services, with detailed information about each thesaurus.

Service URL

https://apps.usgs.gov/thesaurus/thesaurus.php

Parameters

thcode	Thesaurus identifier (numeric). Optional; if neither this nor a thesaurus name is specified, information about all thesauri are reported.
thname	Thesaurus name. The name is matched, without case sensitivity, with the preferred or alternative names of thesauri known to the service database. Optional; if neither this nor a thesaurus identifier code is specified, information about all thesauri are reported.

Output

An object containing information about the thesaurus, if thcode was specified, otherwise an array of such objects, one per thesaurus.

thcode

Thesaurus identifier

name

Name of the thesaurus

scope

A short statement indicating the type of information the thesaurus is intended to express, or expected uses of the thesaurus

creator

Organization or person responsible for creating the thesaurus

rights

edition

Thesaurus edition or version number

date

Date thesaurus was last modified

codetype

Type of term identifiers (alpha indicates characters, number indicates numbers)

prefix

Short identifier for this thesaurus for use in RDF

uri

Complete identifier for this thesaurus to be used in RDF

tblname

Database table containing preferred terms and scope notes

nonpref

Database table containing non-preferred terms

relterm

Database table containing non-hierarchical term relationships

root_code

Unique identifier of the root node of the thesaurus

Example

(line breaks and extra spaces added here for clarity)

https://apps.usgs.gov/thesaurus/thesaurus.php?thcode=2

Term search

Supports the jQuery autocomplete function, returning an array of objects describing thesaurus terms that begin with, end with, or contain the given text. The match is not case sensitive.

Service URL

https://apps.usgs.gov/thesaurus/term-search.php

Parameters

thcode

Thesaurus identifier; if not specified, the USGS Thesaurus will be used. If specified as "any", the search will be carried out on all available thesauri.

term

Fragment of text to match candidate terms

callback

Name of a function in which to wrap the results, to support JSONP

rel

Relationship used to match the given term fragment to the thesaurus terms. All comparisons ignore letter case.

word	(default) Text matches the beginning of any word in the thesaurus term
begins	Text matches the beginning of a thesaurus term
contains	Text occurs anywhere in a thesaurus term
ends	Text matches the end of a thesaurus term
exact	Text matches the thesaurus term exactly

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

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

Example

(line breaks and extra spaces added here for clarity)

https://apps.usgs.gov/thesaurus/term-search.php?term=con

Term details

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

https://apps.usgs.gov/thesaurus/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

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

Array of term objects specifying the broader terms, each the parent of the previous entry

Array of term objects specifying the narrower terms

Array of term objects specifying the related terms

Special cases

If no parameters are given, the service returns an array of objects describing the thesauri that are available in the current database instance: https://apps.usgs.gov/thesaurus/term.php
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: https://apps.usgs.gov/thesaurus/term.php?thcode=2
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. https://apps.usgs.gov/thesaurus/term.php?thcode=2&text=oil%20spills
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. https://apps.usgs.gov/thesaurus/term.php?thcode=2&text=industrial%20pollution%20AND%20petroleum

Example

https://apps.usgs.gov/thesaurus/term.php?code=769

Term Like

Search a thesaurus to find terms that begin with, end with, or contain a text that you supply. Returns JSON or JSONP.

Service URL

https://apps.usgs.gov/thesaurus/term-like.php

Parameters

thcode	Thesaurus identifier; if not specified, the USGS Thesaurus will be used. If specified as "any", the search will be carried out on all available thesauri.
text	Fragment of text to match thesaurus terms
callback	Name of a function in which to wrap the results, to support JSONP

Output

A single object containing the following members:

word	The text given to search for.
exact	Preferred term that matches the text.
similar	Preferred terms that contain the text.
usefor	Non-preferred term relationships involving the text, including USE-WITH relationships.

Example

https://apps.usgs.gov/thesaurus/term-like.php?thcode=2&text=oil

Named instances

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

https://apps.usgs.gov/thesaurus/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

If no parameters are given, the service returns an array of named things for which we have related terms. https://apps.usgs.gov/thesaurus/inst.php

Example

https://apps.usgs.gov/thesaurus/inst.php?name=Mount%20St.%20Helens

Search pattern

Provides a text search pattern for a given thesaurus term.

Service URL

https://apps.usgs.gov/thesaurus/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)

https://apps.usgs.gov/thesaurus/search-pattern.php?thcode=2&code=769