Introduction
The Bitext API Platform offers 9 different services that can be divided into 3 groups:
- 3 Bot & Assistant Middleware services: Query Simplification, Query Simplification + Negation Detection and Variant Generation
- 4 Core NLP services: Lemmatization, POS Tagging, Segmentation, and Language Identification
- 3 Text Analysis services: Phrase Extraction, Entity Extraction and Sentiment Analysis
The platform is currently available in 50+ languages, depending on the service, including Afrikaans, Arabic (MSA), Catalan, Croatian, Czech, Danish, Dutch, English, French, German, Hungarian, Italian, Korean, Norwegian Bokmål, Norwegian Nynorsk, Polish, Portuguese, Romanian, Russian, Persian (Farsi), Serbian, Slovak, Slovenian, Spanish, Swedish, Turkish and Ukrainian. Upcoming versions of the platform will include additional languages and services.
The Bitext API Platform is extremely intuitive and easy to use. This documentation provides a general overview of the platform, including how to call the API endpoints from your code.
API Reference
If your personal token is tokenprovidedbybitext then, using curl, you can call the Bitext Platform API like this:
curl -X POST \
--url https://svc02.api.bitext.com/publicapi/sentiment/ \
-H "Authorization: bearer tokenprovidedbybitext"
You must also specify in the headers that you are sending a JSON request body, by passing a Content-Type header with the application/json value.
curl -X POST \
--url https://svc02.api.bitext.com/publicapi/sentiment/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json"
In curl, a first request for the analysis of I have a beautiful house in Madrid would appear as follows:
curl -X POST \
--url https://svc02.api.bitext.com/publicapi/sentiment/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data \
'{"language":"eng", "text":"I have a beautiful house in Madrid"}'
This first request would return a JSON that looks like this:
{
"success": true,
"resultid": "5ee6b4e1-02e6-4b4a-8a70-ec25ef224281",
"message": "Request accepted"
}
The resultid field in this response is crucial. It will be used to build the subsequent requests. These new requests are GET and include the resultid in the URL. To check whether the Bitext Platform API has finished analyzing one of the texts previously sent, you would write the following request with curl:
curl -X GET \
--url https://svc02.api.bitext.com/publicapi/sentiment/5ee6b4e1-02e6-4b4a-8a70-ec25ef224281/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json"
If the analysis is already available, the response to that request would be the following:
{
"resultid": "5ee6b4e1-02e6-4b4a-8a70-ec25ef224281",
"sentimentanalysis": [
{
"sentence": "I have a beautiful house in Madrid",
"topic": "house",
"topic_norm": "house",
"text": "beautiful",
"text_norm": "beautiful",
"score": "3.000000"
}
]
}
If the analysis is not yet available, the endpoint will return HTTP status code 202, letting you know you need to try the same request again, along with a JSON response indicating the status of the analysis.
{
"resultid": "5ee6b4e1-02e6-4b4a-8a70-ec25ef224281",
"status": "incomplete",
"percentage": "75.00"
}
The Bitext APIs can be accessed by using the following 10 endpoints:
- https://svc02.api.bitext.com/publicapi/simplification/
- https://svc02.api.bitext.com/publicapi/simplificationnegation/
- https://svc02.api.bitext.com/publicapi/variants/
- https://svc02.api.bitext.com/publicapi/segmentation/
- https://svc02.api.bitext.com/publicapi/lemmatization/
- https://svc02.api.bitext.com/publicapi/postagging/
- https://svc02.api.bitext.com/publicapi/langid/
- https://svc02.api.bitext.com/publicapi/entities/
- https://svc02.api.bitext.com/publicapi/phrases/
- https://svc02.api.bitext.com/publicapi/sentiment/
The endpoints correspond to the services that are currently publicly available. For example, if you want to perform a sentiment analysis in English, you would then use the endpoint https://api.bitext.com/sentiment/ and specify English as the language parameter for requests.
In order to successfully call the API endpoints, you must include your API credentials in each request, by adding your personal authentication token to all requests. Your authentication token can be found in the Profile section of the platform dashboard. Click API Credentials, copy the token and use it in your code. The token must be sent as the value of the Authorization header, with "bearer" as a prefix to indicate it is a bearer token.
The Bitext APIs work asynchronously. You must first request that the API starts analyzing a text, after which you can perform additional requests, until the API returns the correct analysis of the text
The first request is a POST request that sends a JSON with two parameters: language and text. The value of the text parameter corresponds to the text to be analyzed, and the value of the language parameter corresponds to the language of that text. The limit of characters per API request is 50,000.
The example request is calling the Sentiment Analysis endpoint in English (the language parameter). The action will only be successfully executed if the user has an active trial or paid subscription to the Bitext API Platform.
The codes for the currently available Bitext languages are as follows:
- "arb": Standard Arabic (MSA)
- "cat": Catalan
- "hrv": Croatian
- "ces": Czech
- "dan": Danish
- "nld": Dutch
- "eng": English
- "fra": French
- "deu": German
- "hun": Hungarian
- "ita": Italian
- "kor": Korean
- "nno": Norwegian Nynorsk
- "nob": Norwegian Bokmål
- "fas": Persian (Farsi)
- "pol": Polish
- "por": Portuguese
- "rum": Romanian
- "rus": Russian
- "srp": Serbian
- "slk": Slovak
- "slv": Slovenian
- "spa": Spanish
- "swe": Swedish
- "tur": Turkish
- "ukr": Ukrainian
- Query Simplification
Bitext Query Simplification service takes a command to a chatbot as input and outputs a simplified version of the command reduced to its essential components, splitting it into smaller sentences when needed. This simplified version reduces the training needs of the chatbot, improving its understanding of a command that would otherwise be too complex.
POST Request
Query Simplification - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Query Simplification - POST request data parameters.
{
"language": "...",
"mode": "...",
"text": "..."
}
Query Simplification - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
Request
- Endpoint: /simplification/
- URL: https://svc02.api.bitext.com/publicapi/simplification/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (found under Profile > API Credentials in the Bitext API dashboard)
- language: the language of the text you want to analyze (see available languages below)
- mode: the specific analysis environment (see available modes below)
- text: the text you want to analyze
Available languages:
- "eng": English
- "spa": Spanish
- "ita": Italian
- "fra": French
- "por": Portuguese
- "deu": German
- "nld": Dutch
- "swe": Swedish
- "dan": Danish
Available modes:
- "home": Smart Home
- "ecommerce": E-commerce
- "news": News
Successful responses
(see code)
GET Request
Query Simplification - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Query Simplification - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Query Simplification - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"simplificationanalysis": [
{
"simplification": "..."
},
{
"simplification": "..."
}
]
}
Request
- Endpoint: /simplification/
- URL: https://svc02.api.bitext.com/publicapi/simplification/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (found under My Account > Profile > API Credentials in the Bitext API dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
- status: HTTP status code of the response
- 202: The analysis with ID 'resultid' is not complete and must be requested again.
- 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- form: each of the words in the text
- pos: the Part of Speech of the word in that sentence. POSes can be noun, adjective, verb, adverb, determiner, pronoun, preposition or conjunction, among others.
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $api_mode = "ecommerce";
my $user_text = "show flat shoes and boots";
print "\nBITEXT API. Rewriting endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to query simplification analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/simplification/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text", "mode" => "$api_mode"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
api_mode = "ecommerce"
user_text = "show flat shoes and boots"
print ("\nBITEXT API. Rewriting endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to query simplification analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/simplification/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text, "mode" : api_mode }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
api_mode = "ecommerce"
user_text = "show flat shoes and boots"
puts ''
puts 'BITEXT API. Rewriting endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to query simplification analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/simplification/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + "", "mode" => "" + api_mode + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Query Simplification - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/simplification/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "show flat shoes and boots", "mode": "ecommerce"}'
Query Simplification - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Query Simplification - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/simplification/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Query Simplification - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"simplificationanalysis": [
{
"simplification": "show flat shoe"
},
{
"simplification": "show boot"
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
Integration guides for NLU engines
- Query Simplification + Negation
Bitext Query Simplification + Negation Detection service takes a command to a chatbot as input and outputs a simplified version of the command reduced to its essential components, splitting it into smaller sentences when needed and including information about whether each output sentence is positive or negative. This simplified version reduces the training needs of the chatbot, improving its understanding of a command that would otherwise be too complex.
POST Request
Request
Query Simplification + Negation Detection - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Query Simplification + Negation Detection - POST request data parameters.
{
"language": "...",
"mode": "...",
"text": "..."
}
Query Simplification + Negation Detection - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
- Endpoint: /simplificationnegation/
- URL: https://svc02.api.bitext.com/publicapi/simplificationnegation/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (found under Profile > API Credentials in the Bitext API dashboard)
- language: the language of the text you want to analyze (see available languages below)
- mode: the specific analysis environment (see available modes below)
- text: the text you want to analyze
Available languages:
- "eng": English
- "spa": Spanish
- "ita": Italian
- "fra": French
- "por": Portuguese
- "deu": German
- "nld": Dutch
- "swe": Swedish
- "dan": Danish
Available modes:
- "home": Smart Home
- "ecommerce": E-commerce
- "news": News
Successful responses
(see code)
GET Request
Query Simplification + Negation Detection - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Query Simplification + Negation Detection - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Query Simplification + Negation Detection - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"simplificationnegationanalysis": [
{
"simplification": "...",
"negation-flag": true|false
},
{
"simplification": "...",
"negation-flag": true|false
}
]
}
Request
- Endpoint: /simplificationnegation/
- URL: https://svc02.api.bitext.com/publicapi/simplificationnegation/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (found under Profile > API Credentials in the Bitext API dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
- status: HTTP status code of the response
- 202: The analysis with ID 'resultid' is not complete and must be requested again.
- 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- form: each of the words in the text
- pos: the Part of Speech of the word in that sentence. POSes can be noun, adjective, verb, adverb, determiner, pronoun, preposition or conjunction, among others.
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $api_mode = "ecommerce";
my $user_text = "show flat shoes and not boots";
print "\nBITEXT API. Rewriting + Negation Detection endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to query simplification + negation detection analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/simplificationnegation/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text","mode" => "$api_mode"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
api_mode = "ecommerce"
user_text = "show flat shoes and not boots"
print ("\nBITEXT API. Query Simplification + Negation Detection endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to query simplification + negation detection analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/simplificationnegation/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text, "mode" : api_mode }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
api_mode = "ecommerce"
user_text = "show flat shoes and not boots"
puts ''
puts 'BITEXT API. Query Simplification + Negation Detection endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to query simplification + negation detection analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/simplificationnegation/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + "", "mode" => "" + api_mode + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Query Simplification + Negation Detection - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/simplificationnegation/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "show flat shoes and not boots", "mode": "ecommerce"}'
Query Simplification + Negation Detection - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Query Simplification + Negation Detection - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/simplificationnegation/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Query Simplification + Negation Detection - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"simplificationnegationanalysis": [
{
"simplification": "show flat shoe",
"negation-flag": false
},
{
"simplification": "not show boot",
"negation-flag": true
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
Integration guides for NLU engines
- Variant Generation
Bitext Variant Generation service creates dozens of relevant variations from a single query and tag their entities and intent, making it extremely easy to produce quality training data for your chatbot.
POST Request
Variant Generation - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Variant Generation - POST request data parameters.
{
"language": "...",
"mode": "...",
"text": "...",
"intent": "...",
"politeness": "...",
"negation": "...",
"all_numbers": "...",
"output": "..."
}
Variant Generation - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
Request
- Endpoint: /variants/
- URL: https://svc02.api.bitext.com/publicapi/variants/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (found under Profile > API Credentials in the Bitext API dashboard).
- language: the language of the text you want to analyze (see available languages below).
- mode: the specific analysis environment (see available modes below).
- text: the text you want to analyze.
- intent: then name of the intent that will be populated in the output JSON file.
- politeness: optional boolean value that defines the generation of variants with elements of politeness. Set to true by default.
- negation: optional boolean value that defines the generation of variants with elements of negation. Set to true by default.
- all_numbers: optional boolean value that defines the generation of variants with all possible grammatical numbers. Set to true by default.
- output: output data format (see available modes below).
Available languages:
- "eng": English
- "spa": Spanish
- "ita": Italian
- "fra": French
- "por": Portuguese
- "deu": German
- "nld": Dutch
- "swe": Swedish
- "dan": Danish
Available modes:
- "home": Smart Home
- "ecommerce": E-commerce (Beta)
- "news": News (Beta)
Available output modes:
- "rasa": Rasa JSON format
- "luis": LUIS JSON format
- "witai": Wit.ai JSON format
- "watson": Watson JSON format
- "lex": Lex JSON format
- "dialogflow": Dialogflow JSON format
Successful responses
(see code)
GET Request
Variant Generation - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Variant Generation - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Variant Generation - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"utterances": [
]
}
Request
- Endpoint: /variants/
- URL: https://svc02.api.bitext.com/publicapi/variants/
- Method: GET
- Headers: (see code)
- token: your API token (found under My Account > Profile > API Credentials in the Bitext API dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
- status: HTTP status code of the response
- 202: The analysis with ID 'resultid' is not complete and must be requested again.
- 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
Example code
import requests
import json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
api_mode = "home"
output_mode = "rasa"
user_text = "turn on the lights in the kitchen"
intent = "turn on light"
print("\nBITEXT API. Variant Generation endpoint. Python sample code\n")
print("--------------------------------------------------\n\n")
# Building the POST request to Variant Generation endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/variants/"
headers = {"Authorization": "bearer " + oauth_token, "Content-Type": "application/json"}
header = {"Authorization": "bearer " + oauth_token}
params = {"language": user_language, "mode": api_mode, "text": user_text, "intent": intent, "politeness": True, "negation": True, "all_numbers": True, "output": output_mode}
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200:
analysis = json.loads(res.text)
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Results:\n\n")
print(json.dumps(analysis, sort_keys=False, indent=2))
Output (partial)
{
"rasa_nlu_data": {
"common_examples": [
{
"text": "turn on the light in the kitchen",
"entities": [
{
"entity": "Action",
"start": 0,
"end": 7,
"value": "turn on"
},
{
"entity": "Object",
"start": 12,
"end": 17,
"value": "light"
},
{
"entity": "Place",
"start": 25,
"end": 32,
"value": "kitchen"
}
],
"intent": "turn on light"
},
{
"text": "turn on the light of the kitchen",
"entities": [
{
"entity": "Action",
"start": 0,
"end": 7,
"value": "turn on"
},
{
"entity": "Object",
"start": 12,
"end": 17,
"value": "light"
},
{
"entity": "Place",
"start": 25,
"end": 32,
"value": "kitchen"
}
],
"intent": "turn on light"
},
...
}
Variant Generation - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/variants/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "turn on the lights in the kitchen and the bedroom", "mode": "home"}'
Variant Generation - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Variant Generation - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/variants/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Variant Generation - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"utterances": [
]
}
Depending on the analysis environment selected, the number of variants generated will vary and the entities will be treated and tagged differently. Restricting the domain allows for are more controlled generation of variants and a more efficient tagging of entities.
On the right you can find an example using Python.
Integration guides for NLU engines
- Segmentation
Bitext Segmentation service takes as input a whole text and returns the text splited into an array of sentences.
POST Request
Request
Segmentation - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Segmentation - POST request data parameters.
{
"language": "...",
"text": "..."
}
Segmentation - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
- Endpoint: /segmentation/
- URL: https://svc02.api.bitext.com/publicapi/segmentation/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: language of the text you want to analyze (see available languages below)
- text: text you want to analyze
Available languages:
- "eng": English
- "spa": Spanish
- "cat": Catalan
- "ces": Czech
- "dan": Danish
- "deu": German
- "fra": French
- "hrv": Croatian
- "hun": Hungarian
- "ita": Italian
- "nld": Dutch
- "pol": Polish
- "por": Portuguese
- "rum": Romanian
- "rus": Russian
- "slk": Slovak
- "slv": Slovenian
- "spa": Spanish
- "srp": Servian
- "tur": Turkish
- "ukr": Ukrainian
Successful responses
(see code)
GET Request
Segmentation- GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Segmentation - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Segmentation - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"segmentationresults": [
"...",
"..."
]
}
Request
- Endpoint: /segmentation/
- URL: https://svc02.api.bitext.com/publicapi/segmentation/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- segmentationresults: list of sentences
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = "This is one sentence. This is another sentence";
print "\nBITEXT API. Segmentation endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to segmentation endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/segmentation/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = "This is one sentence. This is another sentence"
print ("\nBITEXT API. Segmentation endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to segmentation analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/segmentation/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = "This is one sentence. This is another sentence"
puts ''
puts 'BITEXT API. Segmentation endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to segmentation analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/segmentation/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Segmentation - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/segmentation/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "This is the first sentence. This is the second sentence."}'
Segmentation - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Segmentation - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/segmentation/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Segmentation - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"segmentationresults": [
"This is the first sentence.",
"This is the second sentence."
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- Lemmatization
Bitext Lemmatization service provides all potential roots (also known as lemmas) for a given word, using morphological analysis and carefully curated lexicons. For example, for the word "spoke", the lemmatization service will return the lemmas "speak" and "spoke". For the sentence "We spoke yesterday about fixing the bike.", the Lemmatization service will output a set of lemmas for every word in the sentence.
The Lemmatization service API endpoint expects a list of words. For every word in that input list, the service returns a list of lemmas. If no lemmas have been found for a word, it will return the input form as lemma.
POST Request
Request
Lemmatization - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Lemmatization - POST request data parameters.
{
"language": "...",
"text": ["...", "..."]
}
Lemmatization - POST request successful responses (HTTP status code 201)
{
"message": "Request accepted",
"success": true,
"resultid": "..."
}
- Endpoint: /lemmatization/
- URL: https://svc02.api.bitext.com/publicapi/lemmatization/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: language of the text you want to analyze (see available languages below)
- text: list of words you want to analyze
Available languages:
- "arb": Standard Arabic (MSA)
- "cat": Catalan
- "nld": Dutch
- "eng": English
- "fra": French
- "deu": German
- "ita": Italian
- "kor": Korean
- "nno": Norwegian Nynorsk
- "nob": Norwegian Bokmål
- "fas": Persian (Farsi)
- "por": Portuguese
- "rus": Russian
- "spa": Spanish
Successful responses
(see code)
GET Request
Lemmatization - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Lemmatization - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Lemmatization - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"lemmatizationanalysis": [
{
"form": "...",
"lemmas": ["...", "..."]
},
{
"form": "...",
"lemmas": ["...", "..."]
},
{
"form": "...",
"lemmas": ["...", "..."]
}
]
}
Request
- Endpoint: /lemmatization/
- URL: https://svc02.api.bitext.com/publicapi/lemmatization/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- form: analyzed word
- lemmas: list of lemmas found for the analyzed word
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = ["I", "have", "a", "beautiful", "house", "in", "Madrid"];
print "\nBITEXT API. Lemmatization endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to lemmatization analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/lemmatization/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = ["I", "have", "a", "beautiful", "house", "in", "Madrid"]
print ("\nBITEXT API. Lemmatization endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to lemmatization analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/lemmatization/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = ["I", "have", "a", "beautiful", "house", "in", "Madrid"]
puts ''
puts 'BITEXT API. Lemmatization endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to lemmatization analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/lemmatization/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Lemmatization - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/lemmatization/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": ["lost", "can'\''t"]}'
Lemmatization - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Lemmatization - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/lemmatization/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Lemmatization - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"lemmatizationanalysis": [
{
"form": "lost",
"lemmas": ["lose", "lost"]
},
{
"form": "can't",
"lemmas": ["can not"]
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- POS Tagging
Bitext POS Tagging service provides the Part of Speech (POS) for each one of the words in a sentence. When a word can have several POSes, the relevant POS will be decided using syntactic and morphological analysis. For example, for the sentence "I want to run", the POS Tagging service will return the "pronoun" for "I", "verb" for "want" and "run", and "preposition" for "to". But in "It was a good run", "run" will be assigned the POS "noun".
POST Request
Request
POS Tagging - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
POS Tagging - POST request data parameters.
{
"language": "...",
"text": "..."
}
POS Tagging - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
- Endpoint: /postagging/
- URL: https://svc02.api.bitext.com/publicapi/postagging/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: language of the text you want to analyze (see available languages below)
- text: text you want to analyze
Available languages:
- "arb": Standard Arabic (MSA)
- "cat": Catalan
- "hrv": Croatian
- "ces": Czech
- "dan": Danish
- "nld": Dutch
- "eng": English
- "fra": French
- "deu": German
- "hun": Hungarian
- "ita": Italian
- "pol": Polish
- "por": Portuguese
- "ron": Romanian
- "rus": Russian
- "srp": Serbian
- "slk": Slovak
- "slv": Slovenian
- "spa": Spanish
- "swe": Swedish
- "tur": Turkish
- "ukr": Ukrainian
Successful responses
(see code)
GET Request
POS Tagging - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
POS Tagging - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
POS Tagging - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"postagginganalysis": [
[
{
"form": "...",
"pos": "..."
},
{
"form": "...",
"pos": "..."
},
{
"form": "...",
"pos": "..."
}
]
]
}
Request
- Endpoint: /postagging/
- URL: https://svc02.api.bitext.com/publicapi/postagging/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- form: each of the words in the text
- pos: the Part of Speech of the word in that sentence. POSes can be noun, adjective, verb, adverb, determiner, pronoun, preposition or conjunction, among others.
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = "Your house is great";
print "\nBITEXT API. POS Tagging endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to POS Tagging analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/postagging/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = "Your house is great"
print ("\nBITEXT API. POS Tagging endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to POS tagging analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/postagging/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = "Your house is great"
puts ''
puts 'BITEXT API. POS Tagging endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to POS tagging analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/postagging/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
POS Tagging - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/postagging/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "Your house is great"}'
POS Tagging - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
POS Tagging - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/postagging/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
POS Tagging - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"postagginganalysis": [
[
{
"form": "Your",
"pos": "determiner"
},
{
"form": "house",
"pos": "noun"
},
{
"form": "is",
"pos": "verb"
},
{
"form": "great",
"pos": "adjective"
}
]
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- Language Identification
Bitext Language Identification service detects the language of the input text and returns a list of sentences with their respective language.
POST Request
Request
Language Identification - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Language Identification - POST request data parameters.
{
"text": "..."
}
Language Identification - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
- Endpoint: /langid/
- URL: https://svc02.api.bitext.com/publicapi/langid/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- text: text you want to analyze
Successful responses
Available languages for identification:
- "af": Afrikaans
- "ar": Arabic
- "az": Azerbaijani
- "be": Belarusian
- "bg": Bulgarian
- "ca": Catalan
- "cs": Czech
- "da": Danish
- "de": German
- "el": Greek
- "en": English
- "eo": Esperanto
- "es": Spanish
- "et": Estonian
- "eu": Basque
- "fa": Persian (Farsi)
- "fi": Finnish
- "fr": French
- "ga": Irish Gaelic
- "gl": Galician
- "gu": Gujarati
- "he": Hebrew
- "hi": Hindi
- "hu": Hungarian
- "hy": Armenian
- "id": Indonesian
- "is": Icelandic
- "it": Italian
- "ja": Japanese
- "ka": Georgian
- "kk": Kazakh
- "kn": Kannada
- "ko": Korean
- "ky": Kyrgyz
- "mk": Macedonian
- "ml": Malayalam
- "mn": Mongolian
- "ms": Malay
- "nb": Norwegian Bokmål
- "ne": Nepali
- "nl": Dutch
- "nn": Norwegian Nynorsk
- "pa": Punjabi
- "pt": Portuguese
- "ru": Russian
- "sk": Slovak
- "sr": Serbian
- "sv": Swedish
- "sw": Swahili
- "te": Telugu
- "tl": Tagalog
- "tr": Turkish
- "uk": Ukrainian
- "ur": Urdu
- "uz": Uzbek
- "vi": Vietnamese
- "zh": Chinese
- "zu": Zulu
GET Request
Language Identification- GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Language Identification - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Language Identification - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"langidanalysis": [
{
"sentence": "...",
"iso": "...",
"language": "...",
"name": "..."
}
,
{
"sentence": "...",
"iso": "...",
"language": "...",
"name": "..."
}
]
}
Request
- Endpoint: /langid/
- URL: https://svc02.api.bitext.com/publicapi/langid/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- sentence: original sentence
- iso: detected language in iso format
- language: detected language in alpha 3 format
- name: detected language name
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Text to be analyzed
my $user_text = "Это фраза. This is another sentence";
print "\nBITEXT API. Language identification endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to language identification endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/langid/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Text to be analyzed
user_text = "Это фраза. This is another sentence"
print ("\nBITEXT API. Language Identification. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to language identification analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/langid/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = {"text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Text to be analyzed
user_text = "Это фраза. This is another sentence"
puts ''
puts 'BITEXT API. Language Identification endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to language identification analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/langid/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Language Identification - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/langid/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"text": "Это фраза. This is the second sentence."}'
Language Identification - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Language Identification - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/langid/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Language Identification - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"langidanalysis":
[
{
"sentence": "\u042d\u0442\u043e \u0444\u0440\u0430\u0437\u0430.",
"language": "rus",
"name": "Russian",
"iso": "RU-RU"
},
{
"sentence": "This is another sentence",
"language": "eng",
"name": "English",
"iso": "EN-US"
}
]
}
}
[{"sentence": "\u042d\u0442\u043e \u0444\u0440\u0430\u0437\u0430.", "language": "rus", "name": "Russian", "iso": "RU-RU"}, {"sentence": "This is the second sentence.", "language": "eng", "name": "English", "iso": "EN-US"}]}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- Entity Extraction
Bitext entity extraction service finds entities within texts, such as people’s names, country names and company names. When a text is sent to the entities endpoint, a single bag of entities is retrieved. Each entity found in the text appears both exactly as it does in the text and also as a normalized version. The type of entity is specified with a numeric code.
POST Request
Entities - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Entities - POST request data parameters.
{
"language": "...",
"text": "..."
}
Entities - GET request successful responses (HTTP status code 201)
{
"success": true,
"message": "Request accepted",
"resultid": "..."
}
Entities - GET request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Entities - GET request successful responses (HTTP status code 202)
{
"resultid": "..."
}
Entities - GET request successful responses (HTTP status code 200)
{
"entitiesanalysis": [
{
"type": "...",
"concept": "...",
"concept_norm": "..."
}
],
"resultid": "..."
}
Request
- Endpoint: /entities/
- URL: https://svc02.api.bitext.com/publicapi/entities/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: Language of the text you want to analyze (see available languages below)
- text: Text you want to analyze
Available languages:
- "eng": English
- "deu": German
- "fra": French
- "ita": Italian
- "nld": Dutch
- "por": Portuguese
- "spa": Spanish
Successful responses
(see code)
GET Request
Request
- Endpoint: /entities/
- URL: https://svc02.api.bitext.com/publicapi/entities/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses:
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- type: Type of entity identified (see available entity types below)
- entity: Entity found (person, country, company, etc.)
- entity_norm: Normalized version of the entity
Available entities types:
- 0: Unknown
- 1: Name of person
- 3: Place
- 4: Phone number
- 5: Email address
- 6: Company
- 7: Organization
- 8: URL
- 9: IP address
- 10: Date
- 11: Hour
- 15: Money
- 17: Twitter hashtag
- 18: Twitter user
- 19: Other alphanumeric
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = "Barack Obama is due to visit Scotland from April 20th";
print "\nBITEXT API. Entity Extraction endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to Entity Extraction analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/entities/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = "Barack Obama is due to visit Scotland from April 20th"
print ("\nBITEXT API. Entity Extraction endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to entity extraction analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/entities/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = "Barack Obama is due to visit Scotland from April 20th"
puts ''
puts 'BITEXT API. Entity Extraction endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to entity extraction analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/entities/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Entities - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/entities/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "Barack Obama is due to visit Scotland from April 20th"}'
Entities - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Entities - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/entities/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Entities - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"entitiesanalysis": [
{
"entity": "Barack Obama",
"type": "1",
"entity_norm": "Barack Obama"
},
{
"entity": "Scotland",
"type": "3",
"entity_norm": "Scotland"
},
{
"entity": "April 20th",
"type": "10",
"entity_norm": "20/04/"
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- Phrase Extraction
Bitext Phrase Extraction service provides the relevant phrases and the type of phrase (nominal, verbal, adjectival or adverbial) for a sentence, using syntactic and morphological analysis. For example, for the sentence "The front wheel has a broken spoke", the Phrase Extraction service will return the phrases "the front wheel" (nominal phrase), "has" (verbal phrase) and "a broken spoke" (nominal phrase).
POST Request
Request
Phrases - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Phrases - POST request data parameters.
{
"language": "...",
"text": "..."
}
Phrases - POST request successful responses (HTTP status code 201)
{
"success": true,
"resultid": "...",
"message": "Request accepted"
}
- Endpoint: /phrases/
- URL: https://svc02.api.bitext.com/publicapi/phrases/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: language of the text you want to analyze (see available languages below)
- text: text you want to analyze
Available languages:
- "cat": Catalan
- "nld": Dutch
- "eng": English
- "fra": French
- "deu": German
- "ita": Italian
- "por": Portuguese
- "spa": Spanish
Successful responses
(see code)
GET Request
Phrases - GET request headers
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Phrases - GET request successful responses (HTTP status code 202)
{
"resultid": "...",
"status": "...",
"percentage": "..."
}
Phrases - GET request successful responses (HTTP status code 200)
{
"resultid": "...",
"phrasesanalysis": [
{
"phrase": "...",
"type": "..."
},
{
"phrase": "...",
"type": "..."
},
{
"phrase": "...",
"type": "..."
}
]
}
Request
- Endpoint: /phrases/
- URL: https://svc02.api.bitext.com/publicapi/phrases/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete.
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- phrase: phrase found
- type: type of phrase identified
Available phrase types:
- NP: Noun Phrase
- VP: Verb Phrase
- JP: Adjectival Phrase
- AP: Adverbial Phrase
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = "Your house is great";
print "\nBITEXT API. Phrase Extraction endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to Phrase Extraction analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/phrases/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = "Your house is great"
print ("\nBITEXT API. Phrase Extraction endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to phrase extraction analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/phrases/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = "Your house is great"
puts ''
puts 'BITEXT API. Phrase Extraction endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to phrase extraction analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/phrases/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Phrases - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/phrases/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "Your house is great"}'
Phrases - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Phrases - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/phrases/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Phrases - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"phrasesanalysis": [
{
"phrase": "house",
"type": "NP"
},
{
"phrase": "is",
"type": "VP"
},
{
"phrase": "great",
"type": "JP"
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.
- Sentiment Analysis
Bitext Sentiment Analysis service analyzes opinions found in texts. It first identifies the topic(s) that are being discussed in a particular text and then evaluates the opinion(s) expressed about the topic(s). The result is a numeric score that is either positive or negative.
For example, for the sentence “I have a beautiful house in Madrid,” Bitext sentiment analysis would identify the topic being discussed as ‘house’ and then establish a relationship between 'house' and 'beautiful’ based on the Bitext engine’s deep knowledge of language. ‘Beautiful' is understood as a positive opinion expressed about the topic ‘house’ and so the numeric score of the sentiment analysis would be positive.
When a text is sent to the sentiment analysis API endpoint, it is divided into different sentences, and analyses are automatically performed on each sentence. If a sentence contains no sentiment expression, it receives a score of ’0’ and the corresponding fields for ‘topics’ and ‘sentiment expressions’ are left blank.
POST Request
Sentiment - POST request headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Sentiment - POST request data parameters.
{
"language": "...",
"text": "..."
}
Sentiment - POST request successful responses (HTTP status code 201)
{
"success": true,
"message": "Request accepted",
"resultid": "..."
}
Request
- Endpoint: /sentiment/
- URL: https://svc02.api.bitext.com/publicapi/sentiment/
- Method: POST
- Headers: (see code)
- Data parameters: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- language: language of the text you want to analyze (see available languages below)
- text: text you want to analyze
Available languages:
- "eng": English
- "cat": Catalan
- "deu": German
- "fra": French
- "ita": Italian
- "nld": Dutch
- "por": Portuguese
- "spa": Spanish
Successful responses
(see code)
GET Request
Sentiment - GET request Headers.
{
"Authorization": "bearer [token]",
"Content-Type": "application/json"
}
Sentiment - GET request successful responses (HTTP status code 202)
{
"resultid": "..."
}
Sentiment - GET request successful responses (HTTP status code 200)
{
"success": true,
"resultid": "...",
"sentimentanalysis": [
{
"topic": "...",
"topic_norm": "...",
"text": "...",
"text_norm": "...",
"score": "...",
"sentence": "..."
}
]
}
Request
- Endpoint: /sentiment/
- URL: https://svc02.api.bitext.com/publicapi/sentiment/:resultid/
- Method: GET
- Headers: (see code)
- token: your API token (can be found in the Profile section of the dashboard)
- resultid: identifier of the analysis request (returned by the POST request)
Successful responses
HTTP status code 202: The analysis with ID 'resultid' is not complete and must be requested again.
HTTP status code 200: The analysis with ID 'resultid' is complete
- resultid: identifier of the analysis request (returned by the POST request and sent in the current request)
- topic: target of an opinion
- topic_norm: normalized version of the topic
- text: opinion about the topic
- text_norm: normalized version of the text
- sentence: sentence in which a topic/text relation was found
Example code
use Mojo::UserAgent;
use Mojo::JSON qw(encode_json);
# User token, required for API access
my $oauth_token = "tokenprovidedbybitext";
# API request data: Language and text to be analyzed
my $user_language = "eng";
my $user_text = "Your house is beautiful but the street is not great";
print "\nBITEXT API. Sentiment Analysis endpoint. Perl sample code\n";
print "------------------------------------------------\n\n";
my $ua = Mojo::UserAgent->new;
# Building the POST request to Sentiment Analysis analysis endpoint
my $endpoint = "https://svc02.api.bitext.com/publicapi/sentiment/";
my $headers = { Authorization => "bearer $oauth_token", 'Content-Type' => 'application/json' };
my $params = {"language" => "$user_language","text" => "$user_text"};
# Sending the POST request
$tx = $ua->post($endpoint, $headers, json => $params);
# Processing the result of the POST request
my $post_result = $tx->res->json->{success}; # Success of the request
my $post_result_code = $tx->res->code; # Error code, if applicable
my $post_msg = $tx->res->json->{message}; # Error message, if applicable
my $action_id = $tx->res->json->{resultid}; # Identifier to request the analysis results
print "POST: '$post_msg'\n\n";
# 401 is the error code corresponding to an invalid token
if ($post_result_code == 401)
{
print "Your authentication token is not correct\n";
}
if ($post_result)
{
print "Waiting for analysis results...\n\n";
# GET request loop, using the response identifier returned in the POST answer
my $analysis;
until ($analysis)
{
$tx = $ua->get($endpoint.$action_id.'/', $headers);
eval { $analysis = $tx->res->json };
}
# The loop ends when we have response to the GET request
my $get_msg = $tx->res->message;
print "GET: '$get_msg'\n\n";
# In the GET response we have the result of the analysis
print "Analysis results:\n\n";
print encode_json $analysis;
print "\n";
}
import requests, json
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = "eng"
user_text = "Your house is beautiful but the street is not great"
print ("\nBITEXT API. Sentiment Analysis endpoint. Python sample code\n")
print ("--------------------------------------------------\n\n")
# Building the POST request to sentiment analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/sentiment/"
headers = { "Authorization" : "bearer " + oauth_token, "Content-Type" : "application/json" }
params = { "language" : user_language, "text" : user_text }
# Sending the POST request
res = requests.post(endpoint, headers=headers, data=json.dumps(params))
# Processing the result of the POST request
post_result = json.loads(res.text).get('success') # Success of the request
post_result_code = res.status_code # Error code, if applicable
post_msg = json.loads(res.text).get('message') # Error message, if applicable
action_id = json.loads(res.text).get('resultid') # Identifier to request the analysis results
print("POST: '" + post_msg + "'\n\n")
# 401 is the error code corresponding to an invalid token
if post_result_code == 401:
print("Your authentication token is not correct\n")
if (post_result):
print("Waiting for analysis results...\n\n")
# GET request loop, using the response identifier returned in the POST answer
analysis = None
while analysis == None:
res = requests.get(endpoint + action_id + '/', headers=headers)
if res.status_code == 200 :
analysis = res.text
# The loop ends when we have response to the GET request
get_msg = res.reason
print("GET: '" + get_msg + "'\n\n")
# In the GET response we have the result of the analysis
print("Analysis results:\n\n")
print(analysis + "\n")
require 'httpclient'
require 'json'
# User token, required for API access
oauth_token = 'tokenprovidedbybitext'
# API request data: Language and text to be analyzed
user_language = 'eng'
user_text = "Your house is beautiful but the street is not great"
puts ''
puts 'BITEXT API. Sentiment Analysis endpoint. Ruby sample code'
puts '------------------------------------------------'
puts ''
clnt = HTTPClient.new
# Building the POST request to sentiment analysis endpoint
endpoint = "https://svc02.api.bitext.com/publicapi/sentiment/"
headers = { "Authorization" => "bearer " + oauth_token, "Content-Type" => "application/json"}
params = {"language" => "" + user_language + "" , "text" => "" + user_text + ""}.to_json
# Sending the POST request
res = clnt.post(endpoint,params,headers)
# Processing the result of the POST request
content = JSON.parse(res.content)
post_result_code = res.status # Error code, if applicable
action_id = content["resultid"] # Identifier to request the analysis results
post_msg = content["message"] # Error message, if applicable
post_result = content["success"] # Success of the request
puts 'POST: ' + post_msg
puts ''
# 401 is the error code corresponding to an invalid token
if post_result_code == 401
puts 'Your authentication token is not correct'
end
if post_result
puts 'Waiting for analysis results...'
puts ''
# GET request loop, using the response identifier returned in the POST answer
analysis = ""
while analysis == "" do
res = clnt.get(endpoint + action_id + "/",{},headers)
if res.status == 200
analysis = res.content
elsif res.status != 202
puts "GET: Error code (#{res.status}), message: " + res.reason
exit
end
end
# The loop ends when we have response to the GET request
get_msg = res.reason;
puts 'GET: ' + get_msg
puts ''
# In the GET response we have the result of the analysis
puts 'Analysis results:'
puts ''
puts analysis
puts ''
end
Sentiment - Example POST Request
curl -s -X POST \
--url https://svc02.api.bitext.com/publicapi/sentiment/ \
-H "Authorization: bearer tokenprovidedbybitext" \
-H "Content-Type: application/json" \
--data '{"language": "eng", "text": "Your house is beautiful but the street is not great"}'
Sentiment - Example POST Response
{
"message": "Request accepted",
"success": true,
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9"
}
Sentiment - Example GET Request
curl -s -X GET \
--url https://svc02.api.bitext.com/publicapi/sentiment/22a0942f-7523-a1f1-97b9-459b8e7d0ae9/ \
-H "Authorization: bearer tokenprovidedbybitext" \
Sentiment - Example GET Response
{
"resultid": "22a0942f-7523-a1f1-97b9-459b8e7d0ae9",
"sentimentanalysis": [
{
"sentence": "Your house is beautiful but the street is not great",
"topic": "house",
"topic_norm": "house",
"text": "beautiful",
"text_norm": "beautiful",
"score": "3.000000"
},
{
"sentence": "Your house is beautiful but the street is not great",
"topic": "street",
"topic_norm": "street",
"text": "not,great",
"text_norm": "not,great",
"score": "-4.000000"
}
]
}
On the right you can find examples using curl, Python, Ruby, Java and Perl.