GEMET webservice API

Essentially the API is based on the SKOS Thesaurus, but made multi-language aware and usable over a ReST Interface,
XML-RPC and potentially SOAP. Another source of inspiration was the AGROVOC Web Services.
This webservice API has then inspired the SISSVoc WebService API.

The database is able to hold an unlimited number of thesauri, and it distinguishes between the thesauri by a thesaurus namespace URI. Therefore, if you want to import your thesaurus into the database you invent a namespace URI first. The URI can be any legal URI. GEMET has three thesaurus URIs because the groups and the themes categorisations are seen as two additional (very small) thesauri:
1 ! Concepts
2 ! Super groups
3 ! Groups
4 ! Themes
5 ! Inspire themes

What is a Concept?

GEMET is language neutral. The problem is that one language might use a single word to describe a concept. But in another language people use two or more terms to split the concept into several concepts. As they say; Eskimos have 40 different words for "snow". In GEMET this extreme example would be 40 concepts, but the English terms would all be "snow". Icelandic would have perhaps 15 words for snow, and therefore also some overlap. Since no language is so rich it has unique terms for all concepts, GEMET uses a number to distinguish the concepts from each other.

A concept URI is simply the thesaurus URI plus the concept number. E.g. Currently it is just a string, but we want to make GEMET part of the Semantic Web and browsable as Linked Data. What this means is that is you visit a concept URI with a webbrowser, you'll see a webpage. If you use a linked data browser, with an Accept-header of application/rdf+xml, then an RDF document should be returned.

Using the API as a ReST service

The methods below are described as method calls in simplified Java with the public keyword implied. If you want to use it as a ReST api. You first need the URL where the API is implemented. In GEMET it is Then you encode the parameters as a GET operation:

ReST has the constraint on the API that the arguments can only be text strings. I.e. you can't send structures over to the server. Likewise no polymorphism is possible. It is not yet known how to tell the ReST interface what format the result should be returned in. Possibly with an optional argument called format=json.

All JSON responses can also be wrapped as JSONP if you provide a jsonp argument. I.e. !­­&language=es&jsonp=callback will wrap the JSON response in callback method call.

When designing the API we have been careful not to mix up the URL of the method with the URL of the thesaurus. It is possible to install the application and GEMET database somewhere else (e.g. intranet) and then use it without being dependent on GEMET at I.e. !­­&language=es must be possible.

Class ThesaurusService

Method getTopmostConcepts

Get the top concepts of a thesaurus.

Concept[] getTopmostConcepts(URI thesaurus_uri, String language)

The result from the method will be a list of concept structs that are determined to be top concepts of the thesaurus.
The purpose is to make the thesaurus browsable. In principle all concepts that don't have a broader definition would qualify.
This method replaces fetchTopConcepts, fetchThemes and fetchGroups
To get the themes, you would call getTopmostConcepts('', 'en')
A URI is a subclass of string, potentially with some methods to manipulate the URI.

  • ! thesaurus_uri= *
    Try link
  • ! thesaurus_uri= *
    Try link

Method getAllConceptRelatives

Get a list of all concept relatives.

Mapping[] getAllConceptRelatives(URI concept_uri,
           URI target_thesaurus_uri,
           URI relation_uri)

This method will return a listing of relations for the given concept.
The relation can be any relationship, but only direct relationships.
The thesaurus_uri argument is optional. If it isn't provided the relations can be to concepts in all thesauri in the database.
The relation_uri argument is optional. It makes it possible to get only one type of relationship.
The relation argument takes a URI, e.g.
See [#knownrelations below] for a list of known relations.
Only thesauri that are stored in the database are included.

The properties theme and hasConcept are inverse of each
other. Meaning <Concept A> theme <Theme B> is the same as <Theme B> hasConcept <Concept A>.
Therefore hasConcept is not actually listed in
the database. Similarly are the properties group and hasConcept
inverse. As are subGroupOf and subGroup.

  • ! ?concept_uri= !
    Try link
  • ! ?concept_uri= !
    Try link
  • ! ?concept_uri= !
    Try link

Method getRelatedConcepts

Get a list of all concept with a given relation to the object.

Concept[] getRelatedConcepts(URI concept_uri,
           URI relation_uri, String language)

This method will return related concepts for the given concept.
The relation_uri is mandatory, and must be one of the known relations listed in getAllConceptRelatives.
See [#knownrelations below] for a list of known relations.

  • ! ?concept_uri= !
    &relation_uri= !
    Try link

Method getConcept

Get a concept by a known URI.

Concept getConcept(URI concept_uri, String language)

Returns a Concept struct filled out with information from the requested language.



LanguageString[] getAllTranslationsForConcept(URI concept_uri, String property_uri)

Returns all translations for a property of a given concept.
The property is either a SKOS property URI, or an attribute name from
the Concept class. Currently these are: definition, prefLabel, scopeNote,
acronymLabel, and example. It is possible for a compliant server to have
more information about a concept. These will show up as extra attributes
in Concept objects, and it is legal for a client to ask about translations
for any attribute of type LanguageString.
Property URI Concept attribute
! definition
! preferredLabel
! scopeNote
! nonPreferredLabels
! example
! acronymLabel

Why this business with property URIs? It is to provide an opportunity for
someone who thinks in RDF terms to use the API in a for him natural way.

  • ! concept_uri=! property_uri=!
    Try link

Note: when constructing a GET request of this type, the property URI must
be URI-encoded, when it contains the "#" character (which has special
meaning in a URI).


Get a list of concepts matching a keyword for a particular thesaurus.

Concept[] getConceptsMatchingKeyword(String keyword,
        int search_mode, URI thesaurus_uri, String language)

search_mode - integer in the range 0 – 4 inclusive:
  • 0 – no wildcarding of any type ('accident' becomes '!^accident$'). SQL syntax: term = 'accident'
  • 1 – suffix regex ('accident' becomes '!^accident.+$'). SQL syntax: term LIKE 'accident%'
  • 2 – prefix regex ('accident' becomes '!^.+accident$'). SQL syntax: term LIKE '%accident'
  • 3 – prefix/suffix combined ('accident' becomes '!^.+accident.+$'). SQL syntax: term LIKE '%accident%'
  • 4 – auto search: each of the previous four expansions is tried in ascending order until a match is found.

The thesaurus_uri argument indicates which thesaurus to search in. If
the argument is empty, all thesauri in the database are searched.
The language argument is used both for specifying what language the
keyword is and for returning the concept in the correct language.

  • ! &thesaurus_uri=!
    Try link


Concept[] getConceptsMatchingRegexByThesaurus(String regex,
          URI thesaurus_uri, String language)

Get a list of concepts matching a regex for a particular thesaurus.
The language argument is used both for specifying what language to search in and for returning the concept in the correct language. Example:
  • ! ?­regex=^air$&­thesaurus_uri=!
    Try link

Method getAvailableLangs

Return the languages a concept's preferred label is available in.

String[] getAvailableLanguages(URI concept_uri)

A concept must have a preferred label before it can have any other property in that language.

  • ! ?­concept_uri=!
    Try link

Method getAvailableThesauri

Return all the thesauri uris, the service knows of
Thesaurus[] getAvailableThesauri()

  • !
    Try link

Method fetchThemes

Convenience method that calls getTopmostConcepts('', language)

Concept[] fetchThemes(String lang)

Method fetchGroups

Convenience method that calls getTopmostConcepts('', language)

Concept[] fetchGroups(String language)

There is a major difference between the old fetchGroups() and this
new one. The current one returns 36 hits, whereas the new one will
return only the 4 toplevel groups. You can then for each of them call
to get the children.

Known relations

! Narrower concept
! Broader concept
! Related, but not a synonym
! Theme relationship of a concept. Implemented in RDF, but it is unclear whether it is relevant. Equivalent to broader, but a theme is not a broader concept of a concept
! Source is a theme or group, target is a concept, equivalent to narrower
! Source is a concept, target is a group. Equivalent to broader
! Source is a group, target is one of the four super groups. Equivalent to broader
! Source is one of the four super groups, target is a group. Equivalent to narrower

Note: when using the RESTful API you have to encode the '#' as %23 in
URLs, otherwise the webbrowser assumes you're referring to a fragment
inside the result document.


Class URI

URI parameters are simply String instances that are valid URIs.

Class Concept

URI uri The URI of the concept. Mandatory
URI thesaurus The URI of the thesaurus the concept belongs to. Mandatory
String language The language the definition and terms are delivered in
!LanguageString definition The definition of the concept
!LanguageString preferredLabel Preferred label of the concept (optional, 0 or 1) (skos:prefLabel)
!LanguageString scopeNote Scope note text for describing the intended meaning (skos:scopeNote)
!LanguageString[] nonPreferredLabels Non-preferred labels of the concept (0 or more) (skos:altLabel)
!LanguageString example Example of use of the concept (skos:example)

For all methods that return Concept objects, the following apply:
The language field is populated with the language parameter the client
requested. If wildcarding is possible, then the wildcard. The language
of definition, preferredLabel, scopeNote, nonPreferredLabels and example
are to be popuplated with the language of the text returned. If a text
is not available in the given language, the server can choose to fallback
to another language or not provide anything.

Class LanguageString

The purpose of the LanguageString is to associate a language identifier with a text phrase.
String language
String string

Class Mapping

URI source The URI of the concept that is the parent of the relation
URI relation The URI of the relationship
URI target The URI of the child

A broader relation is defined from SKOS as the predicate.
By using URIs instead of BT, NT, RT etc. it is possible to create your own types of relationships.

Class Thesaurus

URI uri The URI of the thesaurus. Mandatory
String name The name of the thesaurus. Mandatory
String version A text string providing the version. Can be date or number (or both) Mandatory
String description A description of the thesaurus

Tools using the GEMET Web service API