Software » EEA website systems

= [wiki:GEMET GEMET] webservice API =
Essentially the API is based on the [http://www.w3.org/2001/sw/Europe/reports/thes/api/docs/ SKOS Thesaurus],
but made multi-language aware and usable over a [wiki:ReSTInterface ReST Interface],
[http://www.xmlrpc.com/ XML-RPC] and potentially SOAP.
Another source of inspiration was the [http://www.fao.org/aims/ag_webservices.jsp AGROVOC Web Services].
This webservice API has then inspired the [https://www.seegrid.csiro.au/wiki/bin/view/Siss/SISSVocWebService SISSVoc WebService API].

The [wiki:GEMET 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		!http://www.eionet.europa.eu/gemet/concept/		Concepts
	2		!http://www.eionet.europa.eu/gemet/supergroup/		Super groups
	3		!http://www.eionet.europa.eu/gemet/group/		Groups
	4		!http://www.eionet.europa.eu/gemet/theme/		Themes
	5		!http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/		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. http://www.eionet.europa.eu/gemet/concept/7769.
Currently it is just a string, but we want to
make GEMET part of the Semantic Web and browsable as
[http://www4.wiwiss.fu-berlin.de/bizer/pub/LinkedDataTutorial/ 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 http://www.eionet.europa.eu/gemet/ Then you encode the parameters as a GET operation:
http://www.eionet.europa.eu/gemet/theme/&language=es
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 [http://en.wikipedia.org/wiki/Type_polymorphism 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''.

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 http://www.eionet.europa.eu.
I.e. http://www.eionet.europa.eu/gemet/theme/­&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('http://www.eionet.europa.eu/gemet/theme/', 'en')`
A URI is a subclass of string, potentially with some methods to manipulate the URI.

Examples: * !http://www.eionet.europa.eu/gemet/getTopmostConcepts? thesaurus_uri=!http://www.eionet.europa.eu/gemet/group/&language=en
[http://www.eionet.europa.eu/gemet/getTopmostConcepts?thesaurus_uri=http://www.eionet.europa.eu/gemet/group/&language=en Try link] * !http://www.eionet.europa.eu/gemet/getTopmostConcepts? thesaurus_uri=!http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/&language=en
[http://www.eionet.europa.eu/gemet/getTopmostConcepts?thesaurus_uri=http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/&language=en 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. http://www.w3.org/2004/02/skos/core#narrower.
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''.

Examples: * !http://www.eionet.europa.eu/gemet/getAllConceptRelatives ?concept_uri=!http://www.eionet.europa.eu/gemet/group/234
[http://www.eionet.europa.eu/gemet/getAllConceptRelatives?concept_uri=http://www.eionet.europa.eu/gemet/group/234 Try link] * !http://www.eionet.europa.eu/gemet/getAllConceptRelatives ?concept_uri=!http://www.eionet.europa.eu/gemet/concept/6740
[http://www.eionet.europa.eu/gemet/getAllConceptRelatives?concept_uri=http://www.eionet.europa.eu/gemet/concept/6740 Try link] * !http://www.eionet.europa.eu/gemet/getAllConceptRelatives ?concept_uri=!http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9
[http://www.eionet.europa.eu/gemet/getAllConceptRelatives?concept_uri=http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9 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.

Example: * !http://www.eionet.europa.eu/gemet/getRelatedConcepts ?concept_uri=!http://www.eionet.europa.eu/gemet/concept/913
&relation_uri=!http://www.w3.org/2004/02/skos/core%23broader&language=fr
[http://www.eionet.europa.eu/gemet/getRelatedConcepts?concept_uri=http://www.eionet.europa.eu/gemet/concept/913&relation_uri=http://www.w3.org/2004/02/skos/core%23broader&language=fr 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.

Examples: * http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9&language=de
[http://www.eionet.europa.eu/gemet/getConcept?concept_uri=http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9&language=de Try link] * ­http://www.eionet.europa.eu/gemet/concept/95&language=en
[http://www.eionet.europa.eu/gemet/getConcept?concept_uri=http://www.eionet.europa.eu/gemet/concept/95&language=en Try link]

=== getAllTranslationsForConcept === {{{
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'''
	!http://www.w3.org/2004/02/skos/core#definition		definition
	!http://www.w3.org/2004/02/skos/core#prefLabel		preferredLabel
	!http://www.w3.org/2004/02/skos/core#scopeNote		scopeNote
	!http://www.w3.org/2004/02/skos/core#altLabel		nonPreferredLabels
	!http://www.w3.org/2004/02/skos/core#example		example
	!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#acronymLabel		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.

Example: * !http://www.eionet.europa.eu/gemet/getAllTranslationsForConcept? concept_uri=!http://www.eionet.europa.eu/gemet/concept/10126& property_uri=!http://www.w3.org/2004/02/skos/core%23prefLabel
[http://www.eionet.europa.eu/gemet/getAllTranslationsForConcept?concept_uri=http://www.eionet.europa.eu/gemet/concept/10126&property_uri=http://www.w3.org/2004/02/skos/core%23prefLabel 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).

=== getConceptsMatchingKeyword ===
Get a list of concepts matching a keyword for a particular thesaurus. {{{
Concept[] getConceptsMatchingKeyword(String keyword,
int search_mode, URI thesaurus_uri, String language)
}}}

'''Arguments''':
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.

Example: * !http://www.eionet.europa.eu/gemet/getConceptsMatchingKeyword?keyword=air&search_mode=0 &thesaurus_uri=!http://www.eionet.europa.eu/gemet/concept/&language=en
[http://www.eionet.europa.eu/gemet/getConceptsMatchingKeyword?keyword=air&search_mode=0&thesaurus_uri=http://www.eionet.europa.eu/gemet/concept/&language=en Try link]

=== getConceptsMatchingRegexByThesaurus === {{{
Concept[] getConceptsMatchingRegexByThesaurus(String regex,
URI thesaurus_uri, String language)
}}}
Get a list of concepts matching a [http://en.wikipedia.org/wiki/Regular_expression 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: * !http://www.eionet.europa.eu/gemet/getConceptsMatchingRegexByThesaurus ?­regex=^air$&­thesaurus_uri=!http://www.eionet.europa.eu/gemet/concept/&language=en
[http://www.eionet.europa.eu/gemet/getConceptsMatchingRegexByThesaurus?regex=^air$&thesaurus_uri=http://www.eionet.europa.eu/gemet/concept/&language=en 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.

Example: * !http://www.eionet.europa.eu/gemet/getAvailableLanguages ?­concept_uri=!http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9
[http://www.eionet.europa.eu/gemet/getAvailableLanguages?concept_uri=http://inspire-registry.jrc.ec.europa.eu/registers/FCD/items/9 Try link]

=== Method getAvailableThesauri ===
Return all the thesauri uris, the service knows of {{{
Thesaurus[] getAvailableThesauri()
}}}
Example: * !http://www.eionet.europa.eu/gemet/getAvailableThesauri
[http://www.eionet.europa.eu/gemet/getAvailableThesauri Try link]

=== Method fetchThemes ===
Convenience method that calls `getTopmostConcepts('http://www.eionet.europa.eu/gemet/theme/', language)` {{{
Concept[] fetchThemes(String lang)
}}}

=== Method fetchGroups ===
Convenience method that calls `getTopmostConcepts('http://www.eionet.europa.eu/gemet/group/', 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
getAllConceptRelatives(thesaurus='http://www.eionet.europa.eu/gemet/group/')
to get the children.

Known relations #knownrelations ||!http://www.w3.org/2004/02/skos/core#narrower||Narrower concept|| ||!http://www.w3.org/2004/02/skos/core#broader||Broader concept|| ||!http://www.w3.org/2004/02/skos/core#related||Related, but not a synonym|| ||!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#theme||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|| ||!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#hasConcept||Source is a theme or group, target is a concept, equivalent to ''narrower''|| ||!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#group||Source is a concept, target is a group. Equivalent to ''broader''|| ||!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#subGroupOf||Source is a group, target is one of the four super groups. Equivalent to ''broader''|| ||!http://www.eionet.europa.eu/gemet/2004/06/gemet-schema.rdf#subGroup||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. Classes

=== Class URI ===
URI parameters are simply String instances that are valid URIs.

=== Class Concept ===

	'''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.

	'''!LanguageString'''
	String language
	String string

=== Class Mapping ===

	'''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 http://www.w3.org/2004/02/skos/core#broader predicate.
By using URIs instead of BT, NT, RT etc. it is possible to create your own types of relationships.

=== Class Thesaurus ===

	'''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 * http://dev.bnhelp.cz/trac/gemetclient -- !JavaScript implementation of a GEMET client.