Vocabulary Server Version 1.1 methods

Select from the following for more information on each method

  1. getList — retrieves a specific term and/or all terms on a given list.
  2. getMap — retrieves all terms from one or more lists, including their mappings to either one or more specified vocabularies or all vocabularies in the server.
  3. getRelatedRecordByCriteria — retrieves subject terms matching the given criteria and object terms matching the given predicate.
  4. getRelatedRecordByTerm — retrieves the subject term(s) referred to by the subjectTerm parameter and the object terms matching the given predicate.
  5. searchVocab — retrieves records containing a specified string (may include a wildcard) in the term, abbreviated term or definition.
  6. verifyTerm — verifies that a term, an abbreviated term or a term definition exists in a given list.
  7. whatLists — retrieves information (URL, name, abbreviation, definition, version number and version date) on all visible lists or all visible lists in a particular category.
  8. whatListsCat — retrieves the terms which describe the vocabulary server subject categories.

1. getList

Retrieves a specific term and/or all terms on a given list.

Parameters

Name Cardinality Type Description
recordKey mandatory (>=1) xsd:string URI identifying a term or list of terms to retrieve information on. If a list is specified then all member terms will be returned.
earliestRecord optional (1) xsd:dateTime If specified, no terms before this date will be returned. ISO date/time syntax is used, e.g. '2003-08-14T23:00:00.000Z'.

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
getList?recordKey=http://vocab.ndg.nerc.ac.uk/list/P021/current
&earliestRecord=2007-09-01T00:00:00Z

This returns all the records from the specified list (P021) that have been modified on or after September 1st 2007. Note that the string specifying the date and time must be both complete to the level of seconds and syntactically correct or an HTTP error (Error 500) will result.

2. getMap

Retrieves all terms from one or more lists, including their mappings to either one or more specified vocabularies or all vocabularies in the server.

Parameters

Name Cardinality Type Description
subjectList mandatory (>=1) xsd:string URI of the subject list.
predicate mandatory (1) xsd:int Specification of desired predicate. Please see predicate bit mask for more information.
objectList optional (>=0) xsd:string If specified, only terms which are members of the specified lists will be returned.
inference mandatory (1) xsd:string

Specifies whether to include inferred relationships. Allowed values are

  • true — include all inferred relationships, e.g. if a=b and b=c are reported as observed then a=c is also included.
  • false — only include directly observed relationships and their simple inversions, e.g. if a=b is reported as observed then b=a is also included.

Please also see the caveats for the V1.1 Vocabulary Server release.

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
getMap?subjectList=http://vocab.ndg.nerc.ac.uk/list/P031/current
&predicate=2
&objectList=http://vocab.ndg.nerc.ac.uk/list/P021/current
&inference=false

This returns a document containing each term in the SeaDataNet Agreed Parameter Group vocabulary (P031) and its corresponding narrower terms in the BODC Parameter Discovery Vocabulary.

3. getRelatedRecordByCriteria

Retrieves subject terms matching the given criteria and any object terms matching the given predicate.

Notes:

  • This method is primarily designed to interface to the Vocabulary Server thesaurus. To use it in this manner set both subjectList and objectList to http://vocab.ndg.nerc.ac.uk/list/P211/current. Using it against other lists may not produce the expected result unless there are hierarchical relationships between terms.
  • Terms satisfying the search criteria but having no mappings to other records in the Vocabulary Server are not included in the output.

Parameters

Name Cardinality Type Description
subjectList optional (>=0) xsd:string If specified, only subject terms on the given list will be included in the results.
subjectField optional (>=0) xsd:string

If specified, selects the field used to locate the subjectText in. Available options are

  • short — search for subjectText in the abrieviated term field.
  • long — search for subjectText in the term name (default).
  • definition — search for subjectText in the term definition.
subjectText mandatory (1) xsd:string Text to select matching subject terms by.
caseSensitivity optional (1) xsd:boolean Perform a case sensitive comparison between subjectText and the selected field.
Default=true
partialMatch optional (1) xsd:boolean Perform a partial match between subjectText and the selected field. Equivalent to prepending and appending "*" to subjectText.
Default=false
predicate mandatory (1) xsd:int Specification of desired predicate. Please see predicate bit mask for more information.
objectList optional (>=0) xsd:string If specified, only terms which are members of the specified lists will be returned.
inferences mandatory (1) xsd:string

Specifies whether to include inferred relationships. Allowed values are

  • true — include all inferred relationships, e.g. if a=b and b=c are reported as observed then a=c is also included.
  • false — only include directly observed relationships and their simple inversions, e.g. if a=b is reported as observed then b=a is also included.

Please also see the caveats for the V1.1 Vocabulary Server release.

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
getRelatedRecordByCriteria?subjectText=air%20temperature
&caseSensitivity=false
&partialMatch=true
&predicate=255
&inferences=false
&subjectList=http://vocab.ndg.nerc.ac.uk/list/P211/current
&objectList=http://vocab.ndg.nerc.ac.uk/list/P211/current

This is an example using the thesaurus. The string 'air temperature' hits one record in the thesaurus that is related to the narrower terms 'wet bulb temperature', 'dry bulb temperature' and 'dewpoint temperature' and the broader term 'meteorology'.

4. getRelatedRecordByTerm

Retrieves the subject term referenced by the passed in URI and all object terms matching the predicate.

Parameters

Name Cardinality Type Description
subjectTerm mandatory (1) xsd:string URI of term to be used as the subject.
predicate mandatory (1) xsd:int Specification of desired predicate. Please see predicate bit mask for more information.
objectList optional (>=0) xsd:string If specified, only terms which are members of the specified lists will be returned.
inferences mandatory (1) xsd:string

Specifies whether to include inferred relationships. Allowed values are

  • true — include all inferred relationships, e.g. if a=b and b=c are reported as observed then a=c is also included.
  • false — only include directly observed relationships and their simple inversions, e.g. if a=b is reported as observed then b=a is also included.

Please also see the caveats for the V1.1 Vocabulary Server release.

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
getRelatedRecordByTerm?subjectTerm=http://vocab.ndg.nerc.ac.uk/term/P021/current/TEMP
&predicate=255
&inferences=true

This returns a single term from the BODC Parameter Discovery Vocabulary (Temperature of the water column), together with every record mapped to it in the Vocabulary Server by any kind of relationship.

5. searchVocab

Retrieves records containing a specified string (may include wildcards) in the term, abbreviated term or definition.

Parameters

Name Cardinality Type Description
listKey optional (1) xsd:string If specified, only the given list will be searched.
searchTerm mandatory (1) xsd:string Text to search the field identified by termType for. The character "*" is interpreted as zero or more instances of any character.
termType optional (1) xsd:string

If specified, selects the field used to locate searchTerm in. Available options are

  • short — search for subjectText in the abrieviated term field.
  • long — search for subjectText in the term name (default).
  • definition — search for subjectText in the term definition.

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
searchVocab?listKey=http://vocab.ndg.nerc.ac.uk/list/P021/current
&searchTerm=*emperature*

This returns all records from the specified vocabulary containing the string 'emperature' in the full term name, such as 'Temperature of the water column' and 'Air temperature'.

6. verifyTerm

Verifies that a term, abbreviated term or term definition exists in a given list.

Parameters

Name Cardinality Type Description
listKey mandatory (1) xsd:string URI of the list containing the term to be verified.
entryTerm mandatory (1) xsd:string The text to verify against the list members.
termType optional (1) xsd:string

Selects the field used to locate entryTerm in. Available options are

  • short — search for entryTerm in the abrieviated term field.
  • long — search for entryTerm in the term name (default).
  • definition — search for entryTerm in the term definition.

Output

Name Cardinality Type Description
verifiedTerm optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
verifyTerm?listKey=http://vocab.ndg.nerc.ac.uk/list/P021/current/
&entryTerm=WC_Temp
&termType=short

This returns both a codeTableRecord element and an error element indicating that the entry term supplied (WC_Temp) is a valid abbreviation in the specified list (P021). Invalid terms just return the error element.

7. whatLists

Retrieves information (URL, name, abbreviation, definition, version number and version date) on all visible lists or all visible lists in a particular category (obtained from whatListsCat).

Parameters

Name Cardinality Type Description
categoryKey optional (1) xsd:string If specified, only lists belonging to the subject category identified by this term URI will be returned. The available subject categories and their term URIs may be obtained using a call to the whatListsCat method.

Output

Name Cardinality Type Description
codeTableType optional (>=0) types:codeTableTypeType Matching terms (if any) will be returned as instances of codeTableTypeType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableTypeType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/
whatLists?categoryKey=http://vocab.ndg.nerc.ac.uk/term/C980/current/CL12

This returns a codeTableTypeType instance for each list in the subject category known by the URI http://vocab.ndg.nerc.ac.uk/term/C980/current/CL12 (SeaDataNet Controlled Vocabularies).

8. whatListsCat

Retrieves the terms which describe the Vocabulary Server subject categories.

Parameters

None

Output

Name Cardinality Type Description
codeTableRecord optional (>=0) types:codeTableRecordType Matching terms (if any) will be returned as instances of codeTableRecordType. Please see XML data types for more information.
error mandatory (1) xsd:boolean Indicates whether an error has ocurred during processing. If so, the value of this element will be true and all instances of codeTableRecordType returned with the response MUST be considered invalid and discarded.

Example HTTP-POX call

http://vocab.ndg.nerc.ac.uk/axis2/services/vocab/whatListsCat

 


Related BODC pages

BODC Web Services        NERC Vocabulary Server version 2.0
NERC DataGrid (NDG)    

 

Related external links

Open Geospatial Consortium, Inc (OGC)

 

NERC DataGrid NERC DataGrid NERC DataGrid