Easily access from Java

The SupWSD API is a binding to an HTTP RESTful service that gives you programmatic access to SupWSD, a framework for supervised Word Sense Disambiguation (WSD). Before using the services, you must first register on SupWSD. At the end of the registration process, you will receive an email with the API key. The SupWSD service is available for English, French, German, Italian and Spanish and enforces a default limit of 5.000 free requests per 1 hour period.

The list of models and the related statistics are available here.

All the data of the external resources are released under the terms of the respective licenses.

The SupWSD Java API requires JRE 1.8 or above. The jar file is available from the download page whereas the javadoc is available here.

Installation

To work with the Java API, unpack the zip file with:

Copied to clipboard
unzip supwsd-java-api-client.zip

Create your Eclipse project (File > New > Maven or Grandle project, give the project a name and click Finish). This creates a new folder with the project name under the Eclipse workspace folder

Now, include the supwsd-java-api-client.jar file in the project build classpath:

  1. Select the project from Package Explorer view (Windows > Show View > Package Explorer)

  2. From the menu bar click on Project and then Properties. Select Java Build Path from the contents column on the left and open the Libraries tab

  3. Click on the Add External JARs button, browse to the downloaded SupWSD-API-1.1.0 folder, and select the supwsd-java-api-client.jar file

Classes

The main classes of SupWSD are:

SupWSD the entry point library.
Result a result of the disambiguation process for a single word.
Token the syntactic information of the processed word.
Sense a sense associated with a specific word.
Gloss a description of the first sense associated with the word.

SupWSD

The SupWSD class is used as the entry point to access all the functionalities. After creating an instance with the api key, you can call the method disambiguate to retrieve the sense of words:

Result

A Result contains all the informations of the disambiguation process for a single specific word. The main components of this class are the following objects:

If you want to retrieve all the Sense objects corresponding to a given word, you can use the getSenses method that returns a sorted set of Sense ordered by their probabilities. For words that do not have associated training data, SupWSD will output "U" (Unknow) as the answer. You can check the validity of a result using the isMissing method.

Sense

A Sense is a result of the disambiguation procedure for a specific word. Each sense contains the id of the source and its probability. Moreover, the first sense of each word also contains the Gloss with the relative description and license.

Examples

Here are some code samples to demonstrate using the SupWSD API.

Disambiguate all the words in a given sentence

Copied to clipboard
import it.si3p.supwsd.*;
import it.si3p.supwsd.analysis.*;
import it.si3p.supwsd.config.*;

public class Main {
	public static void main(String[] args) throws SupException {
		final String text = "Il cervello umano è abbastanza abile nella disambiguazione del senso delle parole.";
		SupWSD supwsd = SupWSD.getInstance("ApiKey");
		List<Result> results = supwsd.disambiguate(text, Language.IT, Model.TRAIN_O_MATIC);
		for (Result result : results) {
			Sense sense = result.getSense();
			System.out.println(result.getToken() + " : " + sense + " (" + sense.getGloss() + ")");
		}
	}
}

Disambiguate specific words in a given sentence

Copied to clipboard
import it.si3p.supwsd.*;
import it.si3p.supwsd.analysis.*;
import it.si3p.supwsd.config.*;

public class Main {
	public static void main(String[] args) throws SupException {
		final String text = "The human " + SupWSD.SENSE_TAG + "brain" + SupWSD.SENSE_TAG + " is quite " + SupWSD.SENSE_TAG + "proficient" + SupWSD.SENSE_TAG + " at word-sense disambiguation.";
		SupWSD supwsd = SupWSD.getInstance("ApiKey");
		List<Result> results = supwsd.disambiguate(text, Language.EN, Model.SEMCOR_OMSTI);
		for (Result result : results) {
			if (!result.isMissing()){
				System.out.println(result.getToken() + " : " + result.getSense());
			}
		}
	}
}

Get a probability distribution over senses for all the words in a given sentence

Copied to clipboard
import it.si3p.supwsd.*;
import it.si3p.supwsd.analysis.*;
import it.si3p.supwsd.config.*;

public class Main {
	public static void main(String[] args) throws SupException {
		final String text = "Das menschliche Gehirn beherrscht die Disambiguierung von Wörtern sehr gut.";
		SupWSD supwsd = SupWSD.getInstance("ApiKey");
		List<Result> results = supwsd.disambiguate(text, Language.DE, Model.TRAIN_O_MATIC, true);
		for (Result result : results) {
			Token token = result.getToken();
			System.out.println("Word: " + token.getWord() + "\tLemma: " + token.getLemma() + "\tPos: " + token.getPos());
			if(!result.isMissing()) {
				for (Sense sense : result.getSenses()) {
					System.out.print("Id: " + sense.getId() + "\tProbability: " + sense.getProbability());
					Gloss gloss = sense.getGloss();
					if(gloss!=null) {
						System.out.print("\tDescription: " + sense.getGloss() + "\tLicense: " + sense.getGloss().getLicense());
					}
					System.out.println();
				}
			}
			System.out.println();
		}
	}
}

Models and sources licenses

Copied to clipboard
import it.si3p.supwsd.config.License;
import it.si3p.supwsd.config.Model;
import it.si3p.supwsd.config.Source;

public class Main {
	public static void main(String[] args) {
		License modelLicense = Model.getLicense(Model.TRAIN_O_MATIC);
		License sourceLicense = Source.getLicense(Source.WORDNET);
		System.out.println(modelLicense.name() + " : " + modelLicense.getDescription());
		System.out.println(sourceLicense.name() + " : " + sourceLicense.getDescription());
	}
}