HTTP API

Note: The Babelfy API v0.9 is not supported anymore, please use the new HTTP API 1.0.

This page describes how you can query Babelfy through an HTTP interface that returns JSON. Before you can use the HTTP API you must obtain an API KEY by signing up here (note that keys are shared across BabelNet and Babelfy, so if you already registered to the BabelNet website, you can just retrieve your Babelfy key by logging in). You can then append the key parameter to the HTTP requests as shown in the examples below. All requests must be executed using the GET method and they should include the Accept-Encoding: gzip header in order to obtain compressed content.

Disambiguate a text

Parameters

Name Type Description
text String Required. The text you want to disambiguate
lang Language Required. The language of the text (AGNOSTIC for language agnostic disambiguation).
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a dizionario enciclopedico multiling├╝e und a reseau semantique&lang=AGNOSTIC&key=KEY
annType SemanticAnnotationType It allows to restrict the disambiguated entries to only named entities, word senses or both.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&annType=NAMED_ENTITIES&key=KEY
annRes SemanticAnnotationResource It allows to restrict the disambiguated entries to only WordNet, Wikipedia or BabelNet.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&annRes=WIKI&key=KEY
th double With this parameter you can select the cutting threshold.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&th=.0&key=KEY
match MatchingType This parameter can be used to select the candidate extraction strategy, i.e., either only exact matching or both exact and partial matching.
Example: https://babelfy.io/v1/disambiguate?text=Alan is a well-known computer scientist.&lang=EN&th=.0&match=PARTIAL_MATCHING&key=KEY
MCS MCS Use this to enable or disable the most common sense backoff strategy.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&MCS=OFF&key=KEY
dens boolean Enable or disable the densest subgraph heuristic during the disambiguation pipeline.
Example: https://babelfy.io/v1/disambiguate?text=Apples appear in many religious traditions, often as a mystical or forbidden fruit.&lang=EN&dens=false&key=KEY
cands ScoredCandidates Use thi parameter to obtain as a result of the disambiguation procedure a scored list of candidates or only the top ranked one (if ALL is selected then MCS and th parameters will not be taken into account).
Example: https://babelfy.io/v1/disambiguate?text=Apples appear in many religious traditions, often as a mystical or forbidden fruit.&lang=EN&cands=ALL&key=KEY
posTag PosTaggingOptions Use this parameter to change the tokenization and pos-tagging pipeline for your input text.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&posTag=NOMINALIZE_ADJECTIVES&key=KEY
extAIDA boolean Extend the candidates sets with the aida_means relations from YAGO.
Example: https://babelfy.io/v1/disambiguate?text=BabelNet is both a multilingual encyclopedic dictionary and a semantic network&lang=EN&extAIDA=true&key=KEY
key String Required. API KEY obtained after signing up to BabelNet (see key & limits)

Response Example

[
	{
		"tokenFragment":{"start":0,"end":0},
		"charFragment":{"start":0, "end":7},
		"babelSynsetID":"bn:03083790n",
		"DBpediaURL":"http://dbpedia.org/resource/BabelNet",
		"BabelNetURL":"http://babelnet.org/rdf/s03083790n",
		"score":1.0,
		"coherenceScore":0.6666666666666666,
		"globalScore":0.11428571428571428,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":4,	"end":4},
		"charFragment":{"start":19,	"end":30},
		"babelSynsetID":"bn:00010388n",
		"DBpediaURL":"http://dbpedia.org/resource/Multilingualism",
		"BabelNetURL":"http://babelnet.org/rdf/s00010388n",
		"score":0.9,
		"coherenceScore":0.5,
		"globalScore":0.06428571428571428,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":5,	"end":5},
		"charFragment":{"start":32,	"end":43},
		"babelSynsetID":"bn:00102202a",
		"DBpediaURL":"",
		"BabelNetURL":"http://babelnet.org/rdf/s00102202a",
		"score":0.0,
		"coherenceScore":0.0,
		"globalScore":0.0,
		"source":"MCS"
	},{
		"tokenFragment":{"start":5,	"end":6},
		"charFragment":{"start":32,	"end":54},
		"babelSynsetID":"bn:02290297n",
		"DBpediaURL":"http://dbpedia.org/resource/Encyclopedic_dictionary",
		"BabelNetURL":"http://babelnet.org/rdf/s02290297n",
		"score":1.0,
		"coherenceScore":0.3333333333333333,
		"globalScore":0.02857142857142857,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":6,	"end":6},
		"charFragment":{"start":45,	"end":54},
		"babelSynsetID":"bn:00026967n",
		"DBpediaURL":"http://dbpedia.org/resource/Dictionary",
		"BabelNetURL":"http://babelnet.org/rdf/s00026967n",
		"score":0.9130434782608695,
		"coherenceScore":1.0,
		"globalScore":0.3,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":9,	"end":9},
		"charFragment":{"start":62,	"end":69},
		"babelSynsetID":"bn:00110347a",
		"DBpediaURL":"",
		"BabelNetURL":"http://babelnet.org/rdf/s00110347a",
		"score":1.0,
		"coherenceScore":0.16666666666666666,
		"globalScore":0.007142857142857143,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":9,	"end":10},
		"charFragment":{"start":62,	"end":77},
		"babelSynsetID":"bn:02275757n",
		"DBpediaURL":"http://dbpedia.org/resource/Semantic_network",
		"BabelNetURL":"http://babelnet.org/rdf/s02275757n",
		"score":1.0,
		"coherenceScore":0.5,
		"globalScore":0.08571428571428572,
		"source":"BABELFY"
	},{
		"tokenFragment":{"start":10, "end":10},
		"charFragment":{"start":71,	"end":77},
		"babelSynsetID":"bn:00057379n",
		"DBpediaURL":"",
		"BabelNetURL":"http://babelnet.org/rdf/s00057379n",
		"score":0.0,
		"coherenceScore":0.0,
		"globalScore":0.0,
		"source":"MCS"
	}
]

Code samples

import urllib2
import urllib
import json
import gzip

from StringIO import StringIO

service_url = 'https://babelfy.io/v1/disambiguate'

text = 'BabelNet is both a multilingual encyclopedic dictionary and a semantic network'
lang = 'EN'
key  = 'KEY'

params = {
	'text' : text,
	'lang' : lang,
	'key'  : key
}

url = service_url + '?' + urllib.urlencode(params)
request = urllib2.Request(url)
request.add_header('Accept-encoding', 'gzip')
response = urllib2.urlopen(request)

if response.info().get('Content-Encoding') == 'gzip':
	buf = StringIO( response.read())
	f = gzip.GzipFile(fileobj=buf)
	data = json.loads(f.read())

	# retrieving data
	for result in data:
                # retrieving token fragment
                tokenFragment = result.get('tokenFragment')
                tfStart = tokenFragment.get('start')
                tfEnd = tokenFragment.get('end')
                print str(tfStart) + "\t" + str(tfEnd)

		# retrieving char fragment
                charFragment = result.get('charFragment')
                cfStart = charFragment.get('start')
                cfEnd = charFragment.get('end')
                print str(cfStart) + "\t" + str(cfEnd)

                # retrieving BabelSynset ID
                synsetId = result.get('babelSynsetID')
                print synsetId

require "net/http"
require 'json'

uri = URI("https://babelfy.io/v1/disambiguate?")

params = {
  :text => 'BabelNet is both a multilingual encyclopedic dictionary and a semantic network',
  :lang  => 'EN',
  :key  => 'KEY'
}

uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

response = http.request(Net::HTTP::Get.new(uri.request_uri))

if response.is_a?(Net::HTTPSuccess)
  json = JSON.parse(response.body)

  json.each do |entry|
      # retrieving token fragment
      tokenFragment = entry['tokenFragment']
      tfStart = tokenFragment['start']
      tfEnd = tokenFragment['end']
      puts tfStart.to_s + "\t" + tfEnd.to_s

      # retrieving char fragment
      charFragment = entry['charFragment']
      cfStart = charFragment['start']
      cfEnd = charFragment['end']
      puts cfStart.to_s + "\t" + cfEnd.to_s

      # retrieving BabelSynset ID
      synsetId = entry['babelSynsetID']
      puts synsetId

  end
end
<!DOCTYPE html>
<html>
<head>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
</head>
<body>
<script>
    var service_url = 'https://babelfy.io/v1/disambiguate';
    var text = 'BabelNet is both a multilingual encyclopedic dictionary and a semantic network'
    var lang = 'EN'
    var key = 'KEY'

    var params = {
        'text'   : text,
        'lang' : lang,
	'key'  : key
    };

    $.getJSON(service_url + "?", params, function(response) {

        $.each(response, function(key, val) {

            // retrieving token fragment
            var tokenFragment = val['tokenFragment'];
            var tfStart = tokenFragment['start'];
            var tfEnd = tokenFragment['end'];

            var tfragment = "Start token fragment: " + tfStart
                + "<br/>" + "End token fragment: " + tfEnd;
            $('<div>', {html:tfragment}).appendTo(document.body);

            // retrieving char fragment
            var charFragment = val['charFragment'];
            var cfStart = charFragment['start'];
            var cfEnd = charFragment['end'];

            var cfragment = "Start char fragment: " + cfStart
                + "<br/>" + "End char fragment: " + cfEnd;
            $('<div>', {html:cfragment}).appendTo(document.body);

            // retrieving BabelSynset ID
            var synsetId = val['babelSynsetID'];
            var id = "BabelNet Synset id: " + synsetId;
            $('<div>', {html:id}).appendTo(document.body);

        });

    });
</script>
</body>
</html>
<!DOCTYPE html>
<html>
<body>
<?php

  $service_url = 'https://babelfy.io/v1/disambiguate';

  $text = 'BabelNet is both a multilingual encyclopedic dictionary and a semantic network';
  $lang = 'EN';
  $key  = 'KEY';

  $params = array(
    'text' => $text,
    'lang' => $lang,
    'key'   => $key
  );

  $url = $service_url . '?' . http_build_query($params);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_ENCODING, 'gzip');
  $response = json_decode(curl_exec($ch), true);
  curl_close($ch);

  # retrieving edges data
  foreach($response as $result) {

    // retrieving token fragment
    $tokenFragment = $result['tokenFragment'];
    $tfStart = $tokenFragment['start'];
    $tfEnd = $tokenFragment['end'];

    echo "Start token fragment: " . $tfStart
                . "<br/>" . "End token fragment: " . $tfEnd;

    // retrieving char fragment
    $charFragment = $result['charFragment'];
    $cfStart = $charFragment['start'];
    $cfEnd = $charFragment['end'];

    echo "<br/>Start char fragment: " . $cfStart
        . "<br/>" . "End char fragment: " . $cfEnd;

    // retrieving BabelSynset ID
    $synsetId = $result['babelSynsetID'];
    echo "<br/>BabelNet Synset id: " . $synsetId;
  }

?>
</body>
</html>

Java access

Note: The Babelfy API v0.9 is not supported anymore, please upgrade now to Babelfy API v1.0.

The Babelfy Java API requires JRE 1.7 or above. Here you can access the javadoc for the API. Unpack the zip file with:

unzip BabelfyAPI-1.0.zip

The file is available the download section.

Configuration

The first important step is the configuration of the properties file located inside the Babelfy API folder.

For instance, assuming you received by email the following key: abcdefghilmnopqrstuvz

  1. Edit the babelfy.var.properties files inside Babelfy-online-API-1.0/config/

as shown in the following line:

babelfy.key=abcdefghilmnopqrstuvz

Running the Babelfy demo

Now, you can test that everything works simply issuing the run-babelfydemo command within the main Babelfy-online-API-1.0 folder. Otherwise, you can start the demo with the command line:

java -classpath lib/*:babelfy-online-1.0.jar:config it.uniroma1.lcl.babelfy.demo.BabelfyDemo

Working with Eclipse and Netbeans

In order to use the Babelfy API within an Eclipse or Netbeans project, you need to carry out the following steps (select either Eclipse or Netbeans):

For Scala users: install the Scala plugin for Eclipse or download the Scala IDE for Eclipse - http://scala-ide.org/

  1. Create your Eclipse project (File -> New -> Java (or Scala) project, give the project a name and press Finish). This creates a new folder with the project name under your Eclipse workspace folder
  2. Copy the config/ folder from the Babelfy-online-API-1.0 folder into your workspace/projectFolder/
  3. Now we need to include all the lib/*.jar and babelfy-online-1.0.jar files in the project build classpath:
    1. Select the project from Package Explorer tree view
    2. From the top bar click on Project and then Properties
    3. Once inside the Properties section click on Java build path and select the Libraries tab
    4. From the right menu click on the Add External JARs button
    5. Browse to the downloaded Babelfy-online-API-1.0 folder, and select all the lib/*.jar and babelfy-online-1.0.jar files
  4. Next we need to Include the config/ folder in the project build classpath:
    1. Select the project from Package Explorer tree view
    2. From the top bar click on File and then Refresh
    3. From the Java build path (see point 3 above) select the Source tab
    4. Once in the Source tab, click on Add Folder from the right sidebar and select the downloaded config/ folder
  5. Happy coding!! ;-)

For Scala users: install the Scala plugin for Netbeans - http://wiki.netbeans.org/Scala

  1. Create your Netbeans project (File -> New Project -> Java (or Scala), give the project a name and press Finish). This creates a new folder with the project name under your NetBeans workspace folder
  2. Copy the config/ and resources/ folders from the Babelfy-online-API-1.0 folder into your projectFolder/
  3. Now we need to include all the lib/*.jar and babelfy-online-1.0.jar files, along with the config/ folder in the project build classpath:
    1. Right click on the name of the project in the left tree view, click on Properties and then click on Categories
    2. Once in the Categories section select Libraries and click on the compiles button where you can add JARs and folders through the Add JAR/Folder button
    3. Browse to the downloaded Babelfy-online-API-1.0 folder, and select all the lib/*.jar and babelfy-online-1.0.jar files
    4. Next select the config/ folder and add that as well
  4. Happy coding!! ;-)

Code

Let's now look at the main classes in the Babelfy API. For more details, see the API javadoc.

Main classes

The main classes of Babelfy are:

  • Babelfy (the entry point to Babelfy)
  • SemanticAnnotation (Babelfy's response object: represents a token-based disambiguation result)
  • Fragment (represents portion of POS-tagged text indicating its start and end indexes into the document)
  • BabelfyToken (the token unit which can be used to build sentences in input to Babelfy)
  • BabelfyParameters (the disambiguations parameters for Babelfy calls)
  • BabelfyConstraints (the disambiguations constraints for Babelfy calls)

Babelfy

The Babelfy class is used as the entry point to access all the disambiguation functions available in Babelfy. The use of an instance of this class is intended for a single Babelfy call. You can issue a query with default parameters. For example:

val bfy = new Babelfy()
val inputText = "BabelNet is both a multilingual encyclopedic dictionary and a semantic network"
val bfyAnnotations = bfy.babelfy(inputText, Language.EN)Babelfy bfy = new Babelfy();
String inputText = "BabelNet is both a multilingual encyclopedic dictionary and a semantic network";
List<SemanticAnnotation> bfyAnnotations = bfy.babelfy(inputText, Language.EN);

Now you are ready to use the Babelfy object to work with the Babelfy API.

SemanticAnnotation

A SemanticAnnotation represents a disambiguated fragment of text. It contains all the information about the disambiguated Fragment which can be accessed by using the following methods:

  1. getBabelNetURL() (the URL to the selected BabelSynset)
  2. getBabelSynsetID() (the BabelNet synset ID of the selected BabelSynset, read the BabelNet Java API guide for how to access the BabelSynset information)
  3. getCharOffsetFragment() (the char-based offsets of the annotation if the input text was given as a String)
  4. getCoherenceScore() (a score to measure the level of connectedness of the disambiguated BabelSynset in context)
  5. getDBpediaURL() (the URL to the DBpedia resource associated with the selected BabelSynset)
  6. getScore() (the disambiguation score)
  7. getGlobalScore() (the relevance score of this node within the nput document)
  8. getSource() (the method used to select this BabelSynset: Babelfy, MCS (Most Common Sense) or OTHER)
  9. getTokenOffsetFragment() (the token-based offsets of the annotation if the input text was given as a List<BabelfyToken>)

The Babelfy#babelfy method returns a list of SemanticAnnotation object, each containing all the relevant information for a disambiguated fragment of the input text. . The following code extracts some information from the result:

for (annotation <- bfyAnnotations) {
    //splitting the input text using the CharOffsetFragment start and end anchors
    val frag = inputText.substring(annotation.getCharOffsetFragment.getStart,
        annotation.getCharOffsetFragment.getEnd + 1)
    println(frag + "\t" + annotation.getBabelSynsetID)
    println("\t" + annotation.getBabelNetURL)
    println("\t" + annotation.getDBpediaURL)
    println("\t" + annotation.getSource)
}
//bfyAnnotations is the result of Babelfy.babelfy() call
for (SemanticAnnotation annotation : bfyAnnotations)
{
	//splitting the input text using the CharOffsetFragment start and end anchors
	String frag = inputText.substring(annotation.getCharOffsetFragment().getStart(),
		annotation.getCharOffsetFragment().getEnd() + 1);
	System.out.println(frag + "\t" + annotation.getBabelSynsetID());
	System.out.println("\t" + annotation.getBabelNetURL());
	System.out.println("\t" + annotation.getDBpediaURL());
	System.out.println("\t" + annotation.getSource());
}

The output for the sentence "BabelNet is both a multilingual encyclopedic dictionary and a semantic network" is the following:

BabelNet	bn:03083790n
	http://babelnet.org/rdf/s03083790n
	http://dbpedia.org/resource/BabelNet
	BABELFY
multilingual	bn:00010386n
	http://babelnet.org/rdf/s00010386n
	http://dbpedia.org/resource/Multilingualism
	BABELFY
multilingual	bn:00010388n
	http://babelnet.org/rdf/s00010388n
	http://dbpedia.org/resource/Multilingualism
	BABELFY
encyclopedic	bn:00102202a
	http://babelnet.org/rdf/s00102202a
	null
	MCS
encyclopedic dictionary	bn:02290297n
	http://babelnet.org/rdf/s02290297n
	http://dbpedia.org/resource/Encyclopedic_dictionary
	BABELFY
dictionary	bn:00026967n
	http://babelnet.org/rdf/s00026967n
	http://dbpedia.org/resource/Dictionary
	BABELFY
semantic	bn:00110347a
	http://babelnet.org/rdf/s00110347a
	null
	BABELFY
semantic network	bn:02275757n
	http://babelnet.org/rdf/s02275757n
	http://dbpedia.org/resource/Semantic_network
	BABELFY
network	bn:00021488n
	http://babelnet.org/rdf/s00021488n
	http://dbpedia.org/resource/Computer_network
	BABELFY

The list of SemanticAnnotation.Source values is:

public enum Source
{
	/**
	 * The annotation comes from Babelfy algorithm.
	 */
	BABELFY,
	/**
	 * The annotation comes from the MFS heuristic.
	 */
	MCS,
	/**
	 * An unspecified annotation.
	 */
	OTHER
}

IBabelfy methods

The Babelfy class implements the IBabelfy interface. The IBabelfy interface exposes various overloads of the babelfy method in order to cover a large set of disambiguation settings.

  1. babelfy(String text, Language lang) - Given a text and a language, returns a list of semantic annotations
  2. babelfy(String text, Language lang, BabelfyConstraints constraints) - Given a text and a language, returns a list of semantic annotations on the given constraints
  3. babelfy(List<? extends BabelfyToken> tokenizedText, Language lang) - Given a tokenized text and a language, returns a list of semantic annotations
  4. babelfy(List<? extends BabelfyToken> tokenizedText, Language lang, BabelfyConstraints constraints) - Given a tokenized text and a language, returns a list of semantic annotations on the given constraints

Let's take a look at how to build a List of BabelfyTokens as sentence input of Babelfy:

A BabelfyToken represents the way you can provide to Babelfy a custom-tokenized text. Each token has its own word, lemma, POS tag and language, so that you can provide arbitrary text in multiple languages. There is also a special BabelfyToken.EOS (end of sentence token) which can be used as separator token between texts in different sentences or languages. In the following example we are building a list of BabelfyToken from two texts in different languages:

val myEnText = Arrays.asList("java", "bytecode")
val myFrText = Arrays.asList("programme", "informatique")
val tokenizedInput = new ArrayList[BabelfyToken]()

//building tokens for the English text
for (word <- myEnText)
  tokenizedInput.add(new BabelfyToken(word, Language.EN));

//add an EOS token to separate the different texts
tokenizedInput.add(BabelfyToken.EOS);

//building tokens for the French text
for (word <- myFrText)
  tokenizedInput.add(new BabelfyToken(word, Language.FR));List<String> myEnText = Arrays.asList("java", "bytecode");
List<String> myFrText = Arrays.asList("programme", "informatique");
List<BabelfyToken> tokenizedInput = new ArrayList<>();

//building tokens for the English text
for (String word : myEnText)
	tokenizedInput.add(new BabelfyToken(word, Language.EN));

//add an EOS token to separate the different texts
tokenizedInput.add(BabelfyToken.EOS);

//building tokens for the French text
for (String word : myFrText)
	tokenizedInput.add(new BabelfyToken(word, Language.FR));

BabelfyConstraints

We now have a look at the BabelfyContraints class. This class defines various constraints on the input text/tokens, BabelfyConstraints exposes the following methods:

  1. addAnnotatedFragments (the user can provide pre-annotated fragments as help to the disambiguaton phase)
  2. addFragmentToDisambiguate (the user can specify which fragments have to be considered by Babelfy)

Some code using the above methods follows:

val constraints = new BabelfyConstraints()
val a = new SemanticAnnotation(new TokenOffsetFragment(0, 7), "bn:03083790n",
	"http://dbpedia.org/resource/BabelNet", Source.OTHER)
	constraints.addAnnotatedFragments(a)
val bfy = new Babelfy()
val bfyAnnotations = bfy.babelfy(inputText, Language.EN, constraints)
BabelfyConstraints constraints = new BabelfyConstraints();
SemanticAnnotation a = new SemanticAnnotation(new TokenOffsetFragment(0, 0), "bn:03083790n",
    "http://dbpedia.org/resource/BabelNet", Source.OTHER);
constraints.addAnnotatedFragments(a);
Babelfy bfy = new Babelfy();
List<SemanticAnnotation> bfyAnnotations = bfy.babelfy(inputText, Language.EN, constraints);

BabelfyParameters

We now have a look at the BabelfyParameters class. This class defines various settings that define the Babelfy behaviour depending on the input text/tokens and constraints, BabelfyParameters exposes the following methods:

  1. setAnnotationResource (allows the user to restrict the disambiguated entries to only WordNet, Wikipedia or BabelNet)
  2. setAnnotationType (allows the user to restrict the disambiguated entries to only named entities, word senses or both)
  3. setDensestSubgraph (enables or disables the densest subgraph heuristic during the disambiguation pipeline)
  4. setDisambiguationConstraint (defines how to use the disambiguation constraints defined above)
  5. setExtendCandidatesWithAIDAmeans (extends the candidates sets with the aida_means relations from YAGO)
  6. setMatchingType (selects the candidates extraction strategy, i.e., either only exact matching or both exact and partial matching)
  7. setMCS (enables or disables the most common sense backoff strategy)
  8. setMultiTokenExpression (sets whether to use multi-token expressions or not)
  9. setPosTaggingOptions (sets options for the POS-tagging phase)
  10. setScoredCandidates (defines whether to return just the top ranked or all candidate for a fragment)
  11. setThreshold (sets the disambiguation threshold)

The full list of BabelfyParameters.DisambiguationConstraint values is:

public enum DisambiguationConstraint
{
	/**
	 * Disambiguate only the input fragments and return the corresponding annotations
	 */
	DISAMBIGUATE_INPUT_FRAGMENTS_ONLY,

	/**
	 * Disambiguate all the possible fragments in the input text but return annotations only for
	 * the input fragments
	 */
	DISAMBIGUATE_ALL_RETURN_INPUT_FRAGMENTS,

	/**
	 * Disambiguate the entire text and return the corresponding annotations
	 */
	DISAMBIGUATE_ALL;
}

The full list of BabelfyParameters.MatchingType values is:

public enum MatchingType
{
	/**
	 * Only exact matches are considered for disambiguation
	 */
	EXACT_MATCHING,

	/**
	 * Both exact and partial matches (e.g. Thomas for Thomas Muller) are considered for
	 * disambiguation
	 */
	PARTIAL_MATCHING
}

The full list of BabelfyParameters.MCS values is:

public enum MCS
{
	/**
	 * Use Most Common Sense
	 */
	ON,

	/**
	 * Use Most Common Sense even on Stopwords
	 */
	ON_WITH_STOPWORDS,

	/**
	 * Do not use Most Common Sense
	 */
	OFF;
	}

The full list of BabelfyParameters.PosTaggingOptions values is:

public enum PosTaggingOptions
{
	/**
	 * Standard POS tagging process.
	 */
	STANDARD,

	/**
	 * Interprets all adjectives as nouns.
	 */
	NOMINALIZE_ADJECTIVES,

	/**
	 * Interprets input fragment words as nouns.
	 */
	INPUT_FRAGMENTS_AS_NOUNS,

	/**
	 * Tokenize the input string by splitting all characters as single tokens (all tagged as
	 * nouns, so that we can disambiguate nouns). This should be used for languages and texts in
	 * which there is no standard word separator such as spaces and punctuation marks.
	 */
	CHAR_BASED_TOKENIZATION_ALL_NOUN,
}

The full list of BabelfyParameters.ScoredCandidates values is:

public enum ScoredCandidates
{
	/**
	 * Return only the top ranked candidate for a fragment.
	 */
	TOP,

	/**
	 * Return all candidates for a fragment.
	 */
	ALL;
}

The full list of BabelfyParameters.SemanticAnnotationResource values is:

public enum SemanticAnnotationResource
{
	/**
	 * Annotate with Wikipedia page titles
	 */
	WIKI,

	/**
	 * Annotate with WordNet synsets
	 */
	WN,

	/**
	 * Annotate with BabelNet synsets
	 */
	BN
}

The full list of BabelfyParameters.SemanticAnnotationType values is:

public enum SemanticAnnotationType
{
	/**
	 * Disambiguates all
	 */
	ALL,

	/**
	 * Disambiguates named entities only
	 */
	NAMED_ENTITIES,

	/**
	 * Disambiguates concepts only
	 */
	CONCEPTS
}

Full example

Some code using the above methods follows:

val inputText = "BabelNet is both a multilingual encyclopedic dictionary and a semantic network"
val constraints = new BabelfyConstraints()
val a = new SemanticAnnotation(new TokenOffsetFragment(0, 7), "bn:03083790n",
  "http://dbpedia.org/resource/BabelNet", Source.OTHER)
constraints.addAnnotatedFragments(a)
val bfy = new Babelfy()
val bfyAnnotations = bfy.babelfy(inputText, Language.EN, constraints)

for (annotation <- bfyAnnotations) {
  //splitting the input text using the CharOffsetFragment start and end anchors
  val frag = inputText.substring(annotation.getCharOffsetFragment.getStart,
    annotation.getCharOffsetFragment.getEnd + 1)
  println(frag + "\t" + annotation.getBabelSynsetID)
  println("\t" + annotation.getBabelNetURL)
  println("\t" + annotation.getDBpediaURL)
  println("\t" + annotation.getSource)
}
String inputText = "BabelNet is both a multilingual encyclopedic dictionary and a semantic network";
BabelfyConstraints constraints = new BabelfyConstraints();
SemanticAnnotation a = new SemanticAnnotation(new TokenOffsetFragment(0, 0), "bn:03083790n",
    "http://dbpedia.org/resource/BabelNet", Source.OTHER);
constraints.addAnnotatedFragments(a);
BabelfyParameters bp = new BabelfyParameters();
bp.setAnnotationResource(SemanticAnnotationResource.BN);
bp.setMCS(MCS.ON_WITH_STOPWORDS);
bp.setScoredCandidates(ScoredCandidates.ALL);
Babelfy bfy = new Babelfy(bp);
List<SemanticAnnotation> bfyAnnotations = bfy.babelfy(inputText, Language.EN, constraints);
//bfyAnnotations is the result of Babelfy.babelfy() call
for (SemanticAnnotation annotation : bfyAnnotations)
{
    //splitting the input text using the CharOffsetFragment start and end anchors
    String frag = inputText.substring(annotation.getCharOffsetFragment().getStart(),
        annotation.getCharOffsetFragment().getEnd() + 1);
    System.out.println(frag + "\t" + annotation.getBabelSynsetID());
    System.out.println("\t" + annotation.getBabelNetURL());
    System.out.println("\t" + annotation.getDBpediaURL());
    System.out.println("\t" + annotation.getSource());
}

How do I obtain a Babelfy API key?

To obtain an API key you must register an account on BabelNet: http://babelnet.org/register. At the end of the registration process, you will receive an email with your API key. Information about how to use the API key is available on the HTTP API and Java API pages.

What is a Babelcoin?

Babelcoins are used as an internal credit system to keep track of the requests made against our APIs. 1 Babelcoin represents the ability to make 1 query against either the BabelNet or Babelfy API. For instance, if you have 187 Babelcoins left in your account, it means you can only perform 187 query requests. Note that your Babelcoins will be reset daily back to 1000 credits.

How many Babelcoins are given with a base account?

When you first register on BabelNet, you will be given 1000 Babelcoins per day.

How can I increase the Babelcoins daily limit?

We provide the possibility of increasing the Babelcoins daily limit, normally set to 1000, to people wanting to use Babelfy for research purposes. Please send an email to navigli[at]di.uniroma1.it with the subject Request of Babelfy key limit increase for research purposes, providing in detail (i) the reason for needing to increase the daily limit, (ii) your affiliation, (iii) a description of your research project, (iv) your BabelNet account username, (v) the amount of Babelcoins per day you would like to obtain, (vi) the time length of the requested extension and (vii) whether you are using BabelNet or Babelfy, (viii) what human languages you plan to use. Make sure you use an institutional email so we can verify the institute that is making the request.

How can I use Babelfy commercially?

If you want to use Babelfy for commercial purposes, please contact info[at]babelmind.com.