API for Wordnet server

This API is used for DEB dictionaries that have the class WordNet selected in the administration interface. Nearly the same API is also used for specific classes CdbID, CdbLU and CdbSynset in the Cornetto server.

Replace servername with actual address of the server.

For more info about JSON, see ​http://www.json.org/

API usage example in PHP.

The ​DEBVisDic format XML schema is described in more details in WordNetFormat.

Web interface

Open servername/dictionary?action=listPreview in browser. Accepts the same queries as DEBVisDic.

JSONP support

Every function accepts argument callback. If specified, response is modified to support JSONP.

Getting the list of available dictionaries for the user

Request: servername/doc?action=connect

Response: JSON encoded hash with following structure

{
  "dicts" => {
    ''client_package_id'' => {
      "id"    => ''client package id'',
      "code"  => ''dictionary code'',
      "name"  => ''dictionary name'',
      "access" => ''access rights r/w'',
      "dicslookup" => ''array of package names to allow lookups to'',
      "eqtags" => ''array of eqtags+dictionaries'',
      "dicsreload" => ''array of dictionaries to refresh'',
      "key" => ''dictionary key tag'',
      "indexes" => ''indexed elements''
    }
  }
}

Older version used init action, now obsolete.

Dictionary Search

Request: servername/dictionary_code?action=queryList&word=search_query[&add_def=true/false][&maxres=number][&show_toomany=true/false]

search_query

search query, must be URL encoded UTF-8

add_def

optional parameter, if set to true, synset definition is part of response

maxres

optional parameter, number of maximum results returned (default 100)

show_toomany

optional parameter, if set to true and the number of results is higher then maxres, the answer contains one more result with value: "..." and label: "..."

Response: JSON encoded array of hashes with following structure

 {
   "value" => ''entry ID'',
   "label" => ''information about an entry, depends on dictionary, usually contains PoS, literals'',
   "definition" => ''synset definition, only included if add_def=true''
 }

Query types:

• word - search for entries containing whole word in literals
• word: - search for all different senses of literal exactly matching word
• word:number - search for exact literals with sense number (possibly more POS)
• [.*]word[.*] - search for word substring - .* can be put at the beginning/end of the word or at both of them (N.B. that full regular expressions are not supported at the moment)
• xml_element=value - search for value of xml_element, for example SYNSET.POS=n
• xml_element=dictionary_code2:entry_id2:xml_element2 - search for xml_element with value from xml_element2 of entry_id2 in dictionary_code2

Query entry information

Request: servername/dictionary_code?action=runQuery&query=entry_id&outtype=output_type[&arg=argument][&nojson=1][&default=1][&expand_rels=1][&reldics=wordnet_list]

entry_id

ID of displayed entry

output_type

output type of entry, possible values:

• plain - plain form of XML entry from database
• xml - coloured, foldable XML representation for display in browser
• lmf - synset in LMF format
• html - HTML representation of entry, use default XSLT template, it's possible to specify other template with optional arg argument
• tree - array representation of tree, arg specifies tree direction - ILR for normal tree, RILR for reversed tree
• editor - hash representation of XML for editor tab
• rels - searches in wordnet_list for all synsets that have ELR link to entry_id and link type 'EQ_Synonym', 'EQ_Near_Synonym', 'EQ_Has_Hyperonym', 'EQ_Has_Hyponym'. Returns array of hash representation.

arg

depends on output_type. For html optionally specifies other than default template. For tree specifies tree direction.

nojson

by default response is JSON encoded, by setting nojson=1 response is not encoded

default

optional argument for html output type - with default=1 HTML is displayed with default styles, otherwise style set in client is used

expand_rels

optional argument for editor output type - with expand_rels=1 more details about ILR are included (definition, literals)

wordnet_list

mandatory argument for rels output type - comma separated list of wordnet codes, define in which wordnets to search for synsets

Response: by default JSON encoded, depends on output type

Display tree of an entry

Request: servername/dictionary_code?action=runQuery&outtype=tree&query=entry_id&arg=argument

entry_id

ID of displayed entry

arg

specifies tree direction - ILR for normal tree, RILR for reversed tree

Response: JSON encoded array with tree structure (same as for basic tree in display) - selected entry and its parents

Display subtree of an entry

Request: servername/dictionary_code?action=subtree&query=entry_id&arg=argument[&rel_type=relation_type][&details=details]

entry_id

ID of displayed entry

arg

specifies tree direction - ILR for normal tree, RILR for reversed tree

rel_type

optional parameter, used to limit response only to relations of specified type

details

optional parameter, for details=1 add g_syn, definition, for details=2 add g_syn, definition, literal array

Response: JSON encoded array with tree structure (same as for basic tree in display) - only direct descendants of entry are returned

Display full subtree of an entry

Request: servername/dictionary_code?action=fullsubtree&query=entry_id&arg=argument[&rel_type=relation_type][&details=details]

entry_id

ID of displayed entry

arg

specifies tree direction - ILR for normal tree, RILR for reversed tree

rel_type

optional parameter, used to limit response only to relations of specified type

details

optional parameter, for details=1 add g_syn, definition, for details=2 add g_syn, definition, literal array

Response: JSON encoded array with tree structure (same as for basic tree in display) - display all descendants of entry

Save entry

Request: servername/dictionary_code?action=save&id=entry_id&data=encoded data

entry_id

ID of saved entry

encoded data

JSON and URL UTF-8 encoded hash representation of an entry (same as returned for editor)

Delete entry

Request: servername/dictionary_code?action=delete&id=entry_id

entry_id

ID of entry

Next sense number

Request: servername/dictionary_code?action=nextSense&literal=literal

literal

literal that you want to check

Response: (JSON encoded) recommended_sense = number of the next free sense number for given literal

"Translate" synsets

Request: servername/dictionary_code?action=translate&query=search_query&target=targetWN

dictionary_code

source language

search_query

search query, must be URL encoded UTF-8, same as for "Querying dictionary"

target

target language, wordnet dictionary code

Response: (JSON encoded) arrays "original" and "translated" with the list of synsets in source and target language (same structure as for "Querying dictionary")

Information & statistics

Relations

Request: servername/dictionary_code?action=info&type=relations[&relation=name][&maxres=10][&ascending=true]

relation

limit response only to relations with type name

maxres

maximum number of results, default 10

ascending

if set to true, ascending order, otherwise descending

Response: array of hashes {synset_id, synset_pos, relation_type, relation_count}

Last modifications

Request: servername/dictionary_code?action=info&type=lastmodifications[&user=username][&synset=synset_id][&maxres=10]

user

show only modifications by user

synset_id

show only modifications for synset_id

maxres

maximum number of results, default 10

Response: array of hashes {action, synset_id, time, user, version}

Editation statistics

Request: servername/dictionary_code?action=info&type=edit[&user=username][&synset=synset_id][&month=month]

user

show only modifications by user

synset_id

show only modifications for synset_id

month

statistics for given month, default previous month, format YYYY-MM

Response: array of hashes {user, synset_id, month, action_count}

Journal info

Request: servername/dictionary_code?action=info&type=journal[&user=username][&synset=synset_id][&datefrom=date_from][&date_to=date_to][&maxres=10]

user

show only modifications by user

synset_id

show only modifications for synset_id

maxres

maximum number of results, default 10

date_from, date_to

limit information from/to given date, format YYYY-MM-DD

Response: array of hashes {action, synset_id, time, username, version}