NAV
shell Python PHP R Java Ruby C# JavaScript
  1. Overview
  2. Quick Start
  3. Features & Functions
  4. Interactive Docs

Introduction

# This tab illustrates how to call that endpoint using cURL

# This tab illustrates how to call that endpoint using the Python binding

# The Python binding supports applications with Python 2.6 or greater

'''

python binding versions [1.5.0,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0


<?php
// This tab illustrates how to call that endpoint using the PHP binding

/*

php binding versions [1.5.0,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

*/
?>

// This tab illustrates how to call that endpoint using the Java binding

/*

java binding versions [1.7.1,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

*/

# This tab illustrates how to call that endpoint using the R binding

"

r binding versions [1.7.0,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

"

# This tab illustrates how to call that endpoint using the Ruby binding

=begin

ruby binding versions [1.5.0,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

=end

// This tab illustrates how to call that endpoint using the C# binding

/*

csharp binding versions [1.7.1,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

*/

// This tab illustrates how to call that endpoint using the Node.js binding

/*

nodejs binding versions [1.4.0,) are compatible with current Rosette API.
How to read the version range syntax:

Version Range Example       Versions Included
=====================       ====================
(,1.2.3]                    v <= 1.2.3
(,1.2.3)                    v < 1.2.3
[1.2.3]                     v == 1.2.3
[1.2.3,)                    v >= 1.2.3
(1.2.3,)                    v > 1.2.3
(1.2.3,2.0.0)               1.2.3 < v < 2.0.0
[1.2.3,2.0.0]               1.2.3 <= v <= 2.0.0

*/

Welcome to Rosette! This platform uses natural language processing, statistical modeling, and machine learning to analyze unstructured and semi-structured text across hundreds of language-encoding-script combinations, revealing valuable information and actionable data. Rosette provides endpoints for extracting entities and relationships, translating and comparing the similarity of names, categorizing and adding linguistic tags to text and more.

This Features and Functions documentation is organized by endpoint. Each endpoint includes an overview, as well as a description of configurable options and a list of supported languages. The panel on the right includes code samples in a variety of programming languages. You can select your preferred language with the tabs at the top of the panel.

GitHub Logo Looking to use Rosette in your preferred programming language? On GitHub we provide free bindings in Python, PHP, Java, Node.js, .NET/C#, Ruby, and R. If you’re not a coder, check out our RapidMiner extension or the recipes provided on our community GitHub.

NOTE: The code examples assume you are accessing Rosette through the Cloud. When using Rosette locally:

Authentication


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Send ping to check for reachability of Rosette API"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "ping";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err)
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class ping
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //ping yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI NewCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                //The results of the API call will come back in the form of a Dictionary
                PingResponse response = NewCAPI.Ping();
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

if (is.na(opt$url)) {
   result <- api(opt$key, "ping")
} else {
   result <- api(opt$key, "ping", FALSE, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

begin
  response = rosette_api.ping
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.PingResponse;

import java.io.IOException;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class PingExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new PingExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder().key(getApiKeyFromSystemProperty()).url(getAltUrlFromSystemProperty()).build();
        PingResponse response = rosetteApi.ping();
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}

$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);

try {
    $result = $api->ping();
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    try:
        return api.ping()
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)


curl "https://api.rosette.com/rest/v1/ping" -H "X-RosetteAPI-Key: [your_api-key]"

Ping returns a language specific data structure that represents the following JSON from Rosette


{
  "message": "Rosette at your service",
  "time": 1679921095090,
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:55 GMT",
    "content-type": "application/json",
    "content-length": "58",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-request-id": "7dde898553add95a867a7351f7915c14",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

Rosette uses API keys to allow access to the API. You can authenticate and send a ping with the same code.

You can find your Rosette API key on the Developer Portal, or Sign Up for a new API key.

Include your API key in all API requests to the server in a header:

X-RosetteAPI-Key="[your_api-key]"

NOTE: When using a local installation, no API key is required.

Using Rosette

All Rosette functions (endpoints) are accessed via a RESTful API.

Once you have your API Key, you can send HTTP requests to https://api.rosette.com/rest/v1/ followed by the endpoint name. For example, to identify the entities in a document using the /entities endpoint, the full URL would be https://api.rosette.com/rest/v1/entities.

NOTE: For local installations, no API key is required and the URL will be your local IP address.

The data is returned as a JSON structure that can be integrated into your application.

Language Selection

The documentation for each endpoint contains a Language Support section, which lists the endpoint’s supported languages and scripts. This list can be dynamically retrieved using the endoint’s GET /[endpoint]/supported-languages method. The methods will also return whether you are licensed for the language. This is most useful for local installations; cloud users are automatically licensed for all supported languages for licensed endpoints.

If you know the language of your input, include the three-letter language code as a parameter in your call. This will improve response time and the accuracy of your results. If you do not know the language of your text, Rosette will run an extra process to automatically detect it.

If no language is provided, and Rosette is unable to auto-detect it, an endpoint may provide a “Language xxx is not supported” error, where xxx indicates the language was not determined.

Parameters

Rosette accepts the following parameters:

Parameter Type Description
content string text to process
contentUri string URI to accessible content
language string ISO 639-3 language code

content and contentUri are mutually exclusive; only one can be specified per call.

NOTE: Exceptions are Rosette’s names processing endpoints /name-similarity, /name-translation, and /name-deduplication, which require different inputs and parameters. For more information, please see the endpoint-specific documentation.

Options


    api.set_option('optionName', 'value')

    api.set_option('calculateConfidence','true')

    LanguageCAPI.SetOption("optionName", "value");

    LanguageCAPI.SetOption("calculateConfidence", "true");

    params.rosette_options = { 'optionName' => 'value' }

    params.rosette_options = { 'calculateConfidence' => 'true' }

    $api->setOption('optionName', 'value');

    $api->setOption('calculateConfidence', 'true');

    LanguageOptions options = LanguageOptions.builder().optionName(value).build();

    LanguageOptions options = LanguageOptions.builder().calculateConfidence(true).build();

    options <- list()
    options[[ "optionName" ]] <- "value"

    options <- list()
    options[[ "calculateConfidence" ]] <- "true"


    -d '{"options": {"optionName": value}}'

    -d '{"options": {"calculateConfidence": true}}'


    api.parameters.options = { "optionName": "value" };

    api.parameters.options = { "calculateOptions": "true" };

Many endpoints use options to pass settings or override default values for settings. The syntax for options in Rosette is:

{"options": {"optionName": value}}

where optionName is the name of the option and value is the selected value for the call.

For example, to return the confidence score for each entity returned by the /entities endpoint, the option calculateConfidence must be set to true.

{"options": {"calculateConfidence": true}}

Limits

The maximum payload size is 600KB, with a maximum character count of 50,000.

By default, Rosette will only process one call (active HTTP connection) at a time. You can send a second call once you have received a response from the first. Interested in making multiple concurrent calls? Contact us.

The maximum size name for any of the name processing endpoints, (/name-similarity, /name-translation, /name-deduplication) is 500 characters.

Inter-Version Compatibilitys

In an effort to improve the accuracy and performance of our software we often make changes to our machine learned models. Occasionally, these adjustments may cause unexpected changes to the results our system outputs (e.g. the sentiment, entities and confidence reported by the system on a given document may change). Furthermore, the statistical nature of our software means that the results produced by different versions of Rosette will sometimes be incompatible or non-comparable.

Please let us know if you are caching, storing, indexing, or otherwise comparing results across versions so that we can provide timely warnings of non-comparable changes to Rosette results and/or work with you to ensure a smooth migration between versions. We are also happy to discuss on-premise deployment options which can be shielded from upgrades and other changes. Get in touch with us at support@rosette.com.

Address Similarity

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the similarity score of two names"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "addressSimilarity";

api.parameters.address1 = {"houseNumber": "1600", "road": "Pennsylvania Ave NW", "city": "Washington", "state": "DC", "postCode": "20500"}
api.parameters.address2 = "160 Pennsilvana Avenue, Washington, D.C., 20500"

api.rosette(endpoint, function(err, res){
  if(err){
    console.log(err);
  } else {
    console.log(JSON.stringify(res, null, 2));
  }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class address_similarity
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //address_similarity yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            } 
            try
            {
                CAPI cAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                //The results of the API call will come back in the form of a Dictionary
                AddressSimilarityResponse response = cAPI.AddressSimilarity(new FieldedAddress(houseNumber:"1600", road:"Pennsylvania Ave N.W.", city:"Washington", state:"DC", postCode: "20500"), new UnfieldedAddress(address:"160 Pennsylvana Avenue, Washington, D.C., 20500"));
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)


address1_data <- list("houseNumber" = "1600",
                      "road" = "Pennsylvania Ave NW",
                      "city" = "Washington",
                      "state" = "DC",
                      "postCode" = "20500")

address2_data <- "160 Pennsilvana Avenue, Washington, D.C., 20500"

parameters <- list()
parameters[["address1"]] <- address1_data
parameters[["address2"]] <- address2_data

if (is.na(opt$url)) {
   result <- api(opt$key, "address-similarity", parameters)
} else {
   result <- api(opt$key, "address-similarity", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

begin
  address1 = AddressParameter.new(
    house_number: '1600',
    road: 'Pennsylvania Ave NW',
    city: 'Washington',
    state: 'DC',
    post_code: '20500'
  )
  address2 = '160 Pennsilvana Avenue, Washington, D.C., 20500'
  params = AddressSimilarityParameters.new(address1, address2)
  response = rosette_api.get_address_similarity(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import java.io.IOException;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.AddressSimilarityRequest;
import com.basistech.rosette.apimodel.AddressSimilarityResponse;
import com.basistech.rosette.apimodel.FieldedAddress;
import com.basistech.rosette.apimodel.UnfieldedAddress;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.ADDRESS_SIMILARITY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class AddressSimilarityExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new AddressSimilarityExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String addressSimilarityHouseno1 = "1600";
        String addressSimilarityRoad1 = "Pennsylvania Ave NW";
        String addressSimilarityCity1 = "Washington";
        String addressSimilarityState1 = "DC";
        String addressSimilarityPostcode1 = "20500";
        FieldedAddress address1 = FieldedAddress.builder()
                .houseNumber(addressSimilarityHouseno1)
                .road(addressSimilarityRoad1)
                .city(addressSimilarityCity1)
                .state(addressSimilarityState1)
                .postCode(addressSimilarityPostcode1)
                .build();
        String addressSimilarityAddress2 = "160 Pennsilvana Avenue, Washington, D.C., 20500";
        UnfieldedAddress address2 = UnfieldedAddress.builder()
                .address(addressSimilarityAddress2)
                .build();
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        AddressSimilarityRequest request = AddressSimilarityRequest.builder()
                                                .address1(address1)
                                                .address2(address2)
                                                .build();
        AddressSimilarityResponse response = rosetteApi
                .perform(ADDRESS_SIMILARITY_SERVICE_PATH, request, AddressSimilarityResponse.class);

        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\FieldedAddress;
use rosette\api\UnfieldedAddress;
use rosette\api\AddressSimilarityParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}

$addressSimilarityHouseno1 = "1600";
$addressSimilarityRoad1 = "Pennsylvania Ave NW";
$addressSimilarityCity1 = "Washington";
$addressSimilarityState1 = "DC";
$addressSimilarityPostcode1 = "20500";

$addressSimilarityAddress2 = "160 Pennsilvana Ave, Washington, D.C., 20500";

$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new AddressSimilarityParameters(
    new FieldedAddress(
        $addressSimilarityHouseno1,
        $addressSimilarityRoad1,
        $addressSimilarityCity1,
        $addressSimilarityState1,
        $addressSimilarityPostcode1
    ),
    new UnfieldedAddress(
        $addressSimilarityAddress2
    )
);

try {
    $result = $api->addressSimilarity($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, AddressSimilarityParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    params = AddressSimilarityParameters()
    params["address1"] = {"houseNumber": "1600", "road": "Pennsylvania Ave NW", "city": "Washington", "state": "DC", "postCode": "20500"}
    params["address2"] = "160 Pennsilvana Avenue, Washington, D.C., 20500"

    try:
        return api.address_similarity(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{ "address1": {
            "houseNumber": "1600",
            "road": "Pennsylvania Ave N.W.",
            "city": "Washington",
            "state": "DC",
            "postcode": "20500"
          },
          "address2": "160 Pennsilvana Avenue, Washington, D.C., 20500"
          }
        }' \
    "https://api.rosette.com/rest/v1/address-similarity"



{
  "score": 0.79152402,
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:51 GMT",
    "content-type": "application/json",
    "content-length": "20",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-request-id": "49201178340ca55d2ac70d98d9d8f5e3",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Address Similarity REST endpoint is https://api.rosette.com/rest/v1/address-similarity

The Rosette Address similarity endpoint compares two addresses and returns a match score from 0 to 1 indicating how similar the two addresses are. Addresses can be entered either as a set of address fields or as a single string, which Rosette will parse into fields.

Rosette optimizes the matching algorithm to the field type. Named entity fields, such as street name, city, and state are matched using a linguistic, statistically-based system that handles name variations. Numeric and alphanumeric fields such as house number, postal code, and unit, are matched using numeric-based methods.

Advanced field matching support includes cross-field matching, for example, matching the value in the city field to the value in the state field, and field overrides, for example, matching England and UK.

You can modify the value of one or more parameters used in a request by adding the parameters object to the call. Any non-static parameter can be changed. For example, to change the weights for the postal code and states fields, add the parameters to the request:

"parameters": {"postCodeAddressFieldWeight": "2.0", "stateAddressFieldWeight": "0.5" }

See Address Matching Parameters for a list of parameters.

Request Fields

When you submit an address-similarity request, you can specify address1 and address2 using the fields in the following table. At least one field must be specified for each address, but no specific fields are required. You can also provide the address as a single string which Rosette will parse into fields.

Field1 Description Example
house venue or building name “Brooklyn Academy of Music”, “Empire State Building”
houseNumber usually refers to the external (street-facing) building number “123”
road street name “Harrison Avenue”
unit an apartment, unit, office, lot, or other secondary unit designator “Apt. 123”
level expression indicating a floor number “3rd Floor”, “Ground Floor”
staircase numbered/lettered staircase “2”
entrance numbered/lettered entrance “front gate”
suburb unofficial neighborhood name “Harlem”, “South Bronx”
cityDistrict a borough or district within a city “Brooklyn”, “Hackney”
city the city, town, village, etc “Boston”
island a named island “Maui”
stateDistrict a second-level administrative division or county “Saratoga”
state a first-level administrative division “Massachusetts”
countryRegion informal subdivision of a country “South/Latin America”
country a sovereign nation or its dependent territory, anything with an ISO-3166 code “United States of America”
worldRegion currently only used for appending “West Indies” after the country names, if appropriate “Jamaica, West Indies”
postCode postal code “02110”
poBox post office box “28”

Language Support

The Rosette address similarity endpoint is optimized for addresses in English, Simplified Chinese, and Traditional Chinese. Non-English addresses in Latin script may also be matched; results will vary by language.

You can use the GET /address-similarity/supported-languages method to dynamically retrieve the list of supported languages and scripts for the address-similarity endpoint.

Categorization

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the category of a piece of a document at a URL"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "categories";

var categories_url_data = "https://www.rosette.com/about/";
api.parameters.contentUri = categories_url_data;

api.rosette(endpoint, function(err, res){
  if(err){
    console.log(err);
  } else {
    console.log(JSON.stringify(res, null, 2));
  }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class categories
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //categories yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI CategoriesCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string categories_text_data = @"If you are a fan of the British television series Downton Abbey and you are planning to be in New York anytime before April 2nd, there is a perfect stop for you while in town.";
                //The results of the API call will come back in the form of a Dictionary
                CategoriesResponse response = CategoriesCAPI.Categories(categories_text_data,  null, null, null);
                Console.WriteLine(response.ContentAsJson);

                //Rosette API also supports Dictionary inputs
                //Simply instantiate a new dictionary object with the fields options as keys and inputs as values
                string categories_url_data = @"https://www.rosette.com/about/";
                response = CategoriesCAPI.Categories(new Dictionary<object, object>()
                {
                    {"contentUri", categories_url_data}

                });
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

categories_url_data <- "https://www.rosette.com/about/"

parameters <- list()
parameters[["contentUri"]] <- categories_url_data

if (is.na(opt$url)) {
   result <- api(opt$key, "categories", parameters)
} else {
   result <- api(opt$key, "categories", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

categories_url_data = "https://www.rosette.com/about/"
begin
  params = DocumentParameters.new(content_uri: categories_url_data)
  response = rosette_api.get_categories(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.CategoriesOptions;
import com.basistech.rosette.apimodel.CategoriesResponse;
import com.basistech.rosette.apimodel.DocumentRequest;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.CATEGORIES_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class CategoriesExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new CategoriesExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String categoriesUrlData = "https://www.rosette.com/about/";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                .key(getApiKeyFromSystemProperty())
                                .url(getAltUrlFromSystemProperty())
                                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        DocumentRequest<CategoriesOptions> request = DocumentRequest.<CategoriesOptions>builder()
                                                                    .contentUri(categoriesUrlData)
                                                                    .build();
        CategoriesResponse response = rosetteApi.perform(CATEGORIES_SERVICE_PATH, request, CategoriesResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$categories_url_data = "https://www.rosette.com/about/";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('contentUri', $categories_url_data);

try {
    $result = $api->categories($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os


from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    categories_url_data = "https://www.rosette.com/about/"
    url = categories_url_data
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#categorization

    # api.set_option('singleLabel', 'true')
    # api.set_option('scoreThreshold',- 0.20)

    params = DocumentParameters()

    # Use a URL to input data instead of a string
    params["contentUri"] = url
    try:
        return api.categories(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"contentUri": "https://www.rosette.com/about/" }' \
    "https://api.rosette.com/rest/v1/categories"



{
  "categories": [

  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:51 GMT",
    "content-type": "application/json",
    "content-length": "17",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "e9d980006ba1135dce5e17b08ac61221",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "categories": [

  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:51 GMT",
    "content-type": "application/json",
    "content-length": "17",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "e9d980006ba1135dce5e17b08ac61221",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Categorization REST endpoint is: https://api.rosette.com/rest/v1/categories

Based on its analysis of the content of a string in English, the Rosette categorizer recognizes the following contextual categories:

Categories
Arts & Entertainment Travel
Business Automotive
Education Careers
Food & Drink Family & Parenting
Hobbies & Interests Health & Fitness
Law, Gov’t & Politics Home & Garden
Personal Finance Pets
Real Estate Religion & Spirituality
Science Sports
Society Technology & Computing
Style & Fashion

These are based on the Tier 1 contextual categories defined by the IAB Tech Lab Content Taxonomy.

Before analyzing, Rosette filters out some stop words and punctuation, such as “the” “?” “a” “it”, to increase the accuracy of the analysis.

Rosette supports both singlelabel and multilabel categorization. By default, the categories endpoint is set to multilabel and will return all relevant category labels with a raw score above a threshold. If no categories exceed the threshold, an empty set will be returned. To override the default threshold, -0.25, set scoreThreshold to a value of your choosing.

In addition to a raw score, between negative infinity and infinity, each category label is returned with a confidence score between 0 and 1. The sum of the confidence scores for each category in a given document = 1. The confidence scrores reflect the likelihood that a given category label is accurate relative to all other possible category labels. For every document, all twenty one possible category labels are assigned a confidence score, and the sume of all these scores is one. If multiple labels are relevant to a given document, the confidence scores can be relatively low.

To return only a single category label per document, set {"options": {"singleLabel": true}} and Rosette returns only the category with the highest confidence score. When using this option, a category will always be returned, along with a raw score and a confidence score.

To return a set number of categories, set `{"options": {"numCategories": x}} where x is the number of categories. For example, {"options": {"numCategories": 4}} will return the 4 categories with the highest scores.

Language Support

You can use the GET /categories/supported-languages method to dynamically retrieve the list of supported languages and scripts for the categorization endpoint.

The Rosette categorization endpoint currently only supports English language input. When processing English text in which case should be ignored, specify the language code uen.

Entity Extraction and Linking

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the entities from a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "entities";
var entities_text_data = "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country.";

api.parameters.content = entities_text_data;

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class entities
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //entities yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI EntitiesCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string entities_text_data = @"The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country.";
                //The results of the API call will come back in the form of a Dictionary
                EntitiesResponse response = EntitiesCAPI.Entity(entities_text_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                // PrintContent() is a provided method to print the Dictionary to the console
                response.PrintContent();

                // Entities with full ADM
                EntitiesCAPI.SetUrlParameter("output", "rosette");
                response = EntitiesCAPI.Entity(entities_text_data);
                // response.Content contains the IDictionary results of the full ADM.
                // PrintContent() is a provided method to print the Dictionary to the console
                response.PrintContent();
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

entities_text_data <- "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country."

parameters <- list()
parameters[["content"]] <- entities_text_data

# advanced output
url_parameters <- list(output = "rosette")

if (is.na(opt$url)) {
   result <- api(opt$key, "entities", parameters,
                 url_parameters = url_parameters)
} else {
   result <- api(opt$key, "entities", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

entities_text_data = "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country."
begin
  params = DocumentParameters.new(content: entities_text_data)
  response = rosette_api.get_entities(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.EntitiesOptions;
import com.basistech.rosette.apimodel.EntitiesResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.ENTITIES_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class EntitiesExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new EntitiesExample().run();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private void run() throws IOException {
        String entitiesTextData = "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country.";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                .key(getApiKeyFromSystemProperty())
                                .url(getAltUrlFromSystemProperty())
                                .build();
        DocumentRequest<EntitiesOptions> request = DocumentRequest.<EntitiesOptions>builder()
                .content(entitiesTextData)
                .build();
        EntitiesResponse response = rosetteApi.perform(ENTITIES_SERVICE_PATH, request, EntitiesResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$entities_text_data = "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $entities_text_data;
$params->set('content', $content);

try {
    $result = $api->entities($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#entity-extraction-and-linking

    # api.set_option('calculateSalience','true')
    # api.set_option('linkEntities','false')

    entities_text_data = "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country."
    params = DocumentParameters()
    params["content"] = entities_text_data

    try:
        return api.entities(params)
    except RosetteException as exception:
        print(exception)

PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "The Securities and Exchange Commission today announced the leadership of the agency’s trial unit.  Bridget Fitzpatrick has been named Chief Litigation Counsel of the SEC and David Gottesman will continue to serve as the agency’s Deputy Chief Litigation Counsel. Since December 2016, Ms. Fitzpatrick and Mr. Gottesman have served as Co-Acting Chief Litigation Counsel.  In that role, they were jointly responsible for supervising the trial unit at the agency’s Washington D.C. headquarters as well as coordinating with litigators in the SEC’s 11 regional offices around the country." }' \
    "https://api.rosette.com/rest/v1/entities"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "entities": [
    {
      "type": "ORGANIZATION",
      "mention": "Securities and Exchange Commission",
      "normalized": "U.S. Securities and Exchange Commission",
      "count": 3,
      "mentionOffsets": [
        {
          "startOffset": 4,
          "endOffset": 38
        },
        {
          "startOffset": 166,
          "endOffset": 169
        },
        {
          "startOffset": 536,
          "endOffset": 539
        }
      ],
      "entityId": "Q953944",
      "confidence": 0.61838603,
      "linkingConfidence": 0.77937726
    },
    {
      "type": "PERSON",
      "mention": "Bridget Fitzpatrick",
      "normalized": "Bridget Fitzpatrick",
      "count": 2,
      "mentionOffsets": [
        {
          "startOffset": 99,
          "endOffset": 118
        },
        {
          "startOffset": 287,
          "endOffset": 298
        }
      ],
      "entityId": "T1",
      "confidence": 0.92276227
    },
    {
      "type": "PERSON",
      "mention": "David Gottesman",
      "normalized": "David Gottesman",
      "count": 2,
      "mentionOffsets": [
        {
          "startOffset": 174,
          "endOffset": 189
        },
        {
          "startOffset": 307,
          "endOffset": 316
        }
      ],
      "entityId": "Q5234268",
      "confidence": 0.93117422,
      "linkingConfidence": 0.19686381
    },
    {
      "type": "TITLE",
      "mention": "Chief Litigation Counsel",
      "normalized": "Chief Litigation Counsel",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 134,
          "endOffset": 158
        }
      ],
      "entityId": "T2",
      "confidence": 0.2819823
    },
    {
      "type": "TITLE",
      "mention": "Deputy Chief Litigation Counsel",
      "normalized": "Deputy Chief Litigation Counsel",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 229,
          "endOffset": 260
        }
      ],
      "entityId": "T5",
      "confidence": 0.74621999
    },
    {
      "type": "TEMPORAL:DATE",
      "mention": "December 2016",
      "normalized": "December 2016",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 268,
          "endOffset": 281
        }
      ],
      "entityId": "T6"
    },
    {
      "type": "TITLE",
      "mention": "Ms.",
      "normalized": "Ms.",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 283,
          "endOffset": 286
        }
      ],
      "entityId": "T7",
      "confidence": 0.7271831
    },
    {
      "type": "TITLE",
      "mention": "Mr.",
      "normalized": "Mr.",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 303,
          "endOffset": 306
        }
      ],
      "entityId": "T9",
      "confidence": 0.63842607
    },
    {
      "type": "ORGANIZATION",
      "mention": "Co-Acting",
      "normalized": "Co-Acting",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 332,
          "endOffset": 341
        }
      ],
      "entityId": "T11",
      "confidence": 0.00765693
    },
    {
      "type": "TITLE",
      "mention": "Chief Litigation Counsel",
      "normalized": "Chief Litigation Counsel",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 342,
          "endOffset": 366
        }
      ],
      "entityId": "T12",
      "confidence": 0.00790393
    },
    {
      "type": "LOCATION",
      "mention": "Washington D.C.",
      "normalized": "Washington, D.C.",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 460,
          "endOffset": 475
        }
      ],
      "entityId": "Q61",
      "linkingConfidence": 0.75941488
    }
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:52 GMT",
    "content-type": "application/json",
    "transfer-encoding": "chunked",
    "connection": "close",
    "server": "openresty",
    "vary": "Accept-Encoding",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "b305685dfbf20d88f43879f4c55a789c",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Entity Extraction REST endpoint is: https://api.rosette.com/rest/v1/entities

The Rosette entity extraction endpoint uses statistical or deep neural network based models, patterns, and exact matching to identify entities in documents. An entity refers to an object of interest such as a person, organization, location, date, or email address. Identifying entities can help you classify documents and the kinds of data they contain.

The statistical models are based on computational linguistics and human-annotated training documents. The patterns are regular expressions that identify entities such as dates, times, and geographical coordinates. The exact matcher uses lists of entities to match words exactly in one or more languages.

Statistical model based extractions can return confidence scores for each entity. Confidence score calculation correlates well with precision and may be used for thresholding and removal of false positives. Confidence is calculated by default if linkEntities is on. Otherwise, to include the scores in the result, simply add an option to the request:

{"content": "your_text_here", "options": {"calculateConfidence": true}}

The entity extraction endpoint can also return a salience score for each extracted entity. Salience indicates whether the entity is important to the overall scope of the document, for example, if it would be included in a summary of the document. Returned salience scores are binary, either 0 (not salient) or 1 (salient). To include the salience scores in your results, simply add an option to the request:

{"content": "your_text_here", "options": {"calculateSalience": true}}

The normalized field returns the entity name with normalized white space around each word, one white space per token, which allows entity mention occurrences with different white space usage to be clustered together.

Rosette also has a deep neural network model (currently in BETA) that can be used in place of the statistical model for selected languages. By default Rosette uses the statistical models rather than the deep neural network based model. You can customize which model Rosette uses via the modelType option, which defaults to statistical. To enable the deep neural network model, provide DNN for the modelType. Example:

{"content": "your_text_here", "options": {"modelType": "DNN"}}

Deep Neural Network Language Support

Currently Rosette supports the following languages with the deep neural network model:

Structured Region Processing

The statistical and DNN models are trained to extract entities from unstructured text, using the syntactic content in sentences to help identify entities and entity types. The entities endpoint can be configured to skip structured regions, such as tables and lists, to minimize false positives and noisy results.

By default, structured regions are processed the same as unstructured regions. You can change how structured regions are handled by setting the structuredRegionsProcessingType option:

To enable the Apache Tika processor to extract lists and tables for contentUri (HTML) input, set the enableStructuredRegion option to true. How the extracted tables and lists (the structured regions) are then processed is determined by the value of the structuredRegionProcessingType option.

Know what your language is?

If you know the language of your input, include the three-letter language code in your call to speed up the response time.

Otherwise, Rosette identifies the language of your input.

Entity Types

The Rosette entity extraction endpoint can extract the following entity types:

The following entities are available in select languages. Contact us for more information.

Use the GET /entities/info method to dynamically retrieve the list of supported entity types by language and processor type.

When the call includes {"options": {"includeDBpediaTypes": true}, Rosette supports additional top-level entity types and over 700 additional types drawn from the DBpedia ontology.

Entity Linking

Text that refers to an entity is called an entity mention, such as “Bill Clinton” and “William Jefferson Clinton”. Rosette connects these two entity mentions with entity linking, since they refer to the same real-world PERSON entity. Linking helps establish the identity of the entity by disambiguating common names and matching a variety of names, such as nicknames and formal titles, with an entity ID.

Rosette uses the Wikidata knowledge base as a base to link Person, Location, and Organization entities. If the entity exists in Wikidata, then Rosette returns the Wikidata QID, such as Q1 for the Universe.

Each QID is also assigned a linking confidence score. Linking confidence scores represent the certainty level of the link between an in-document entity mention and its linked QID, and may be used for thresholding and removal of false positive links. Linking confidence is enabled by default. To disable linkingConfidence add {"options": {"linkingConfidence": false}}.

If Rosette cannot link the entity, then it creates a placeholder temporary (“T”) entity ID to link mentions of the same entity in the document. However, the TID may be different across documents for the same entity.

By default, the linker processor both extracts and links entity candidates. These functions are separate from the default entity extraction performed by the statistical, pattern-matching (regex), and exact-matching (gazetteers) processors. You can choose to link the candidates from the default processors instead of the linker processor by adding {"options": {"linkMentionMode": "entities"}}.

Entity linking is on by default for Rosette Cloud and off by default for local installations. To disable entity linking add {"options": {"linkEntities": false}} to improve the call speed. When entity linking is turned off Rosette returns the entities with a TID.

Rosette supports linking to other knowledge bases: specifically the DBpedia ontology and the Refinitiv PermID.

DBpedia includes over 700 entity types spanning seven layers of granularity. When this feature is enabled, each extracted entity will be returned with an additional “dbpediaTypes” field. This field returns a list containing one or more types within the DBpedia hierarchy. Entities linked to DBpedia will also be returned with a QID and a confidence score.

By default, linking to DBpedia is turned off. To turn it on, add {"options": {"includeDBpediaTypes": true}} to your call. The entity linking option must also be enabled. DBpedia types are supported for all languages supported by the entity extraction endpoint.

Thomson Reuters’ PermIDs are available for a subset of entities. By default, linking to PermIDs is turned off. To turn it on, add {"options": {"includePermID": true}} to your call. The entity linking option must be enabled.

Language Support

You can use the GET /entities/supported-languages method to dynamically retrieve the list of supported languages and scripts for the entity extraction endpoint.

Language (code)

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Language Identification


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Determine the language of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "language";
var appHeader = [];
appHeader[0] = "X-RosetteAPI-App"
appHeader[1] = "app";
api.parameters.customHeaders = [appHeader];

var language_data = "Por favor Señorita, says the man.";

api.parameters.content = language_data;
var appHeader = [];
appHeader[0] = "X-RosetteAPI-App"
appHeader[1] = "app";
api.parameters.customHeaders = [appHeader];

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class language
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //language yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            } 
            try
            {
                CAPI LanguageCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string language_data = @"Por favor Señorita, says the man.";
                //The results of the API call will come back in the form of a Dictionary
                LanguageCAPI.SetCustomHeaders("X-RosetteAPI-App", "csharp-app");
                LanguageIdentificationResponse response = LanguageCAPI.Language(language_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

language_data <- "Por favor Señorita, says the man."

parameters <- list()
parameters[["content"]] <- language_data
custom_headers <- c("X-RosetteAPI-App" = "r-application-test")

if (is.na(opt$url)) {
  result <- api(opt$key, "language", parameters = parameters,
                custom_headers = custom_headers)
} else {
  result <- api(opt$key, "language", parameters = parameters,
                custom_headers = custom_headers, NULL, url = opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

language_data = "Por favor Señorita, says the man."
begin
  params = DocumentParameters.new(content: language_data)
  params.custom_headers = { 'X-RosetteAPI-App' => 'ruby-app' }
  response = rosette_api.get_language(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.LanguageOptions;
import com.basistech.rosette.apimodel.LanguageResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.LANGUAGE_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class LanguageExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new LanguageExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String languageData = "Por favor Señorita, says the man.";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        DocumentRequest<LanguageOptions> request = DocumentRequest.<LanguageOptions>builder()
                                                                  .content(languageData)
                                                                  .build();
        LanguageResponse response = rosetteApi.perform(LANGUAGE_SERVICE_PATH, request, LanguageResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$language_data = "Por favor Señorita, says the man.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $language_data;
$params->set('content', $content);
$api->setCustomHeader('X-RosetteAPI-App', 'php-app');

try {
    $result = $api->language($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    language_data = "Por favor Señorita, says the man."
    params = DocumentParameters()
    params["content"] = language_data
    api.set_custom_headers("X-RosetteAPI-App", "python-app")
    try:
        return api.language(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Por favor Señorita, says the man." }' \
    "https://api.rosette.com/rest/v1/language"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "languageDetections": [
    {
      "language": "spa",
      "confidence": 0.32382496
    },
    {
      "language": "eng",
      "confidence": 0.22137269
    },
    {
      "language": "por",
      "confidence": 0.04536385
    },
    {
      "language": "deu",
      "confidence": 0.02814723
    },
    {
      "language": "swe",
      "confidence": 0.02624879
    }
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:52 GMT",
    "content-type": "application/json",
    "content-length": "239",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "spa",
    "x-rosetteapi-request-id": "f2d19d10301b19cbb937ce5425feacd5",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Language Identification REST endpoint is: https://api.rosette.com/rest/v1/language

The Rosette language identifier endpoint identifies in which language(s) the input is written. The endpoint returns a list of language identification results in descending order of confidence, so the first result is the best.

The input data may be in any of 364 language–encoding–script combinations, involving 56 languages, 48 encodings, and 18 writing scripts. The language identifier uses an n-gram algorithm to detect language. Each of the 155 built-in profiles contains the quad-grams (i.e., four consecutive bytes) that are most frequently encountered in documents in a given language, encoding, and script. The default number of n-grams is 10,000 for double-byte encodings and 5,000 for single-byte encodings.

When input text is submitted for detection, a similar n-gram profile is built based on that data. The input profile is then compared with all the built-in profiles (a vector distance measure between the input profile and the built-in profile is calculated). The pre-built profiles are then returned in ascending order by the (shortest) distance of the input from the pre-built profiles.

For all supported languages, the endpoint provides a different proprietary algorithm for detecting the language of short strings (140 characters or less).

Multilingual Documents

Rosette can detect different language regions in a multilingual document. In addition to the whole-document language identification results, it returns a list of language region results in descending order of confidence. To receive language regions, add this to the body of your call: "options": {"multilingual": true}.

Confidence

Rosette returns a confidence score with each language result, ranging from 0 to 1. You can use this score as a threshold for filtering out low-confidence results.

Language Support

You can use the GET /language/supported-languages method to dynamically retrieve the list of supported languages and scripts for the language identification endpoint.

Language (code) Short Strings Support
Albanian (sqi) ✓
Arabic (ara) ✓ 5
Bengali (ben) ✓
Bulgarian (bul) ✓
Catalan (cat) ✓
Chinese (zho) ✓
Croatian (hrv) ✓
Czech (ces) ✓
Danish (dan) ✓
Dutch (nld) ✓
English (eng) 1 ✓
Estonian (est) ✓
Finnish (fin) ✓
French (fra) ✓
German (deu) ✓
Greek (ell) ✓
Gujarati (guj) ✓
Hebrew (heb) ✓
Hindi (hin) ✓
Hungarian (hun) ✓
Icelandic (isl) ✓
Indonesian (ind) ✓
Italian (ita) ✓
Japanese (jpn) ✓
Kannada (kan) ✓
Korean (kor) 2 ✓
Korean - North (qkp) 2 ✓
Korean - South (qkr) 2 ✓
Kurdish (kur) ✓
Latvian (lav) ✓
Lithuanian (lit) ✓
Macedonian (mkd) ✓
Malay, Standard (zsm) ✓
Malayalam (mal) ✓
Norwegian (nor) ✓
Pashto (pus) ✓
Persian (fas) ✓
Polish (pol) ✓
Portuguese (por) ✓
Romanian (ron) ✓
Russian (rus) ✓
Serbian (srp) 3 ✓ 4
Slovak (slk) ✓
Slovenian (slv) ✓
Somali (som) ✓
Spanish (spa) ✓
Swedish (swe) ✓
Tagalog (tgl) ✓
Tamil (tam) ✓
Telugu (tel) ✓
Thai (tha) ✓
Turkish (tur) ✓
Ukrainian (ukr) ✓
Urdu (urd) ✓ 5
Uzbek (uzb) ✓
Vietnamese (vie) ✓

Morphological Analysis

Introduction

The Morphological Analysis REST endpoint is: https://api.rosette.com/rest/v1/morphology/{morphoFeature}

The Rosette morphology endpoint provides language-specific tools for returning parts of speech, lemmas (dictionary form), compound components, and Han readings for each token in the input.

For languages with compound words, Rosette divides the words into components which improves recall for search engines.

For Chinese tokens in Han script, Rosette returns pinyin transcriptions as the Han reading. For Japanese tokens in Han script (kanji), Rosette returns hiragana transcriptions as the Han reading.

We offer two algorithms for Chinese and Japanese tokenization and morphological analysis. Prior to August 2018, the default algorithm was a perceptron. To return to that algorithm, add this to the body of your call:

{"options": {"modelType": "perceptron"}}

For Hebrew only, there is an option disambiguatorType to control which disambiguator is used. The disambiguator is responsible for choosing the correct analysis - part of speech, lemma, etc. - of a given word, out of several candidate analyses. The values are perceptron, DNN (a TensorFlow-based deep neural network model), and dictionary. The default is perceptron. To enable another disambiguator, for example the DNN disambiguator, add this to the body of your call:

{"options": {"disambiguatorType": "DNN"}}

You can append a morphoFeature or a comma-delimited list of features to the /morphology/ endpoint to specify which feature or features you want Rosette to return. /morphology/complete returns all results for all features available for the language of the input text.

morphoFeature options
Complete (all of the above)
Decompounding
Han Readings
Lemmas
Parts of Speech

Complete


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the complete morphological analysis of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "morphology";

var morphology_complete_data = "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)";
var content = morphology_complete_data;

api.parameters.content = content;
api.parameters.morphology = "complete";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class morphology_complete
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //morphology_complete yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            } 
            try
            {
                CAPI MorphologyCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string morphology_complete_data = @"The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)";
                //The results of the API call will come back in the form of a Dictionary
                MorphologyResponse response = MorphologyCAPI.Morphology(morphology_complete_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

morphology_complete_data <- "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)"

parameters <- list()
parameters[["content"]] <- morphology_complete_data
parameters[["morphology"]] <- "complete"

if (is.na(opt$url)) {
   result <- api(opt$key, "morphology", parameters)
} else {
   result <- api(opt$key, "morphology", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

morphology_complete_data = "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)"
begin
  params = DocumentParameters.new(content: morphology_complete_data)
  response = rosette_api.get_morphology_complete(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.api.MorphologicalFeature;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.MorphologyOptions;
import com.basistech.rosette.apimodel.MorphologyResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.MORPHOLOGY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class MorphologyCompleteExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new MorphologyCompleteExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String morphologyCompleteData = "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        DocumentRequest<MorphologyOptions> request = DocumentRequest.<MorphologyOptions>builder().content(morphologyCompleteData).build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        MorphologyResponse response = rosetteApi.perform(MORPHOLOGY_SERVICE_PATH + "/" + MorphologicalFeature.COMPLETE, request, MorphologyResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$morphology_complete_data = "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $morphology_complete_data);

try {
    $result = $api->morphology($params, RosetteConstants::$MorphologyOutput['COMPLETE']);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#morphological-analysis-introduction

    # api.set_option('modelType','perceptron') #Valid for Chinese and Japanese only

    morphology_complete_data = "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)"
    params = DocumentParameters()
    params["content"] = morphology_complete_data
    try:
        return api.morphology(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "The quick brown fox jumped over the lazy dog. 👍🏾 Yes he did. B)"}' \
    "https://api.rosette.com/rest/v1/morphology/complete"

The example above returns JSON with the following fragments:


{
  "tokens": [
    "The",
    "quick",
    "brown",
    "fox",
    "jumped",
    "over",
    "the",
    "lazy",
    "dog",
    ".",
    "👍🏾",
    "Yes",
    "he",
    "did",
    ".",
    "B)"
  ],
  "posTags": [
    "DET",
    "ADJ",
    "ADJ",
    "NOUN",
    "VERB",
    "ADP",
    "DET",
    "ADJ",
    "NOUN",
    "PUNCT",
    "SYM",
    "ADV",
    "PRON",
    "VERB",
    "PUNCT",
    "SYM"
  ],
  "lemmas": [
    "the",
    "quick",
    "brown",
    "fox",
    "jump",
    "over",
    "the",
    "lazy",
    "dog",
    ".",
    "👍",
    "yes",
    "he",
    "do",
    ".",
    "B)"
  ],
  "compoundComponents": [
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null
  ],
  "hanReadings": [
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:52 GMT",
    "content-type": "application/json",
    "content-length": "564",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "5699c077df34ba58816362a594344b8a",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Complete Morphology REST endpoint is https://api.rosette.com/rest/v1/morphology/complete

You can call the complete set of Morphology features and Rosette returns the lemmas, compound components, Han readings, and parts of speech tags for the input text.

Check Language Support for the input languages supported by each of the features.

Decompounding


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the complete morphological analysis of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "morphology";

var morphology_compound_components_data = "Rechtsschutzversicherungsgesellschaften";
var content = morphology_compound_components_data;

api.parameters.content = content;
api.parameters.morphology = "compound-components";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    }
        console.log(JSON.stringify(res, null, 2));

});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class morphology_compound_components
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //morphology_compound_components yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI MorphologyCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string morphology_compound_components_data = @"Rechtsschutzversicherungsgesellschaften";
                //The results of the API call will come back in the form of a Dictionary
                MorphologyResponse response = MorphologyCAPI.Morphology(morphology_compound_components_data, null, null, null, MorphologyFeature.compoundComponents);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

morphology_compound_components_data <- "Rechtsschutzversicherungsgesellschaften"

parameters <- list()
parameters[["content"]] <- morphology_compound_components_data
parameters[["morphology"]] <- "compound-components"

if (is.na(opt$url)) {
   result <- api(opt$key, "morphology", parameters)
} else {
   result <- api(opt$key, "morphology", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

morphology_compound_components_data = "Rechtsschutzversicherungsgesellschaften"
begin
  params = DocumentParameters.new(
    content: morphology_compound_components_data
  )
  response = rosette_api.get_compound_components(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.api.MorphologicalFeature;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.MorphologyOptions;
import com.basistech.rosette.apimodel.MorphologyResponse;
import com.basistech.util.LanguageCode;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.MORPHOLOGY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class MorphologyCompoundComponentsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new MorphologyCompoundComponentsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String morphologyCompoundComponentsData = "Rechtsschutzversicherungsgesellschaften";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        DocumentRequest<MorphologyOptions> request = DocumentRequest.<MorphologyOptions>builder().content(morphologyCompoundComponentsData)
                .language(LanguageCode.GERMAN) // example of specifying the language.
                .build();
        MorphologyResponse response = rosetteApi.perform(MORPHOLOGY_SERVICE_PATH + "/" + MorphologicalFeature.COMPOUND_COMPONENTS,
                request, MorphologyResponse.class);

        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$morphology_compound_components_data = "Rechtsschutzversicherungsgesellschaften";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $morphology_compound_components_data);

try {
    $result = $api->morphology($params, RosetteConstants::$MorphologyOutput['COMPOUND_COMPONENTS']);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#morphological-analysis-introduction

    # api.set_option('modelType','perceptron') #Valid for Chinese and Japanese only

    morphology_compound_components_data = "Rechtsschutzversicherungsgesellschaften"
    params = DocumentParameters()
    params["content"] = morphology_compound_components_data
    try:
        return api.morphology(params, api.morphology_output['COMPOUND_COMPONENTS'])
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Rechtsschutzversicherungsgesellschaften"}' \
    "https://api.rosette.com/rest/v1/morphology/compound-components"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "tokens": [
    "Rechtsschutzversicherungsgesellschaften"
  ],
  "compoundComponents": [
    [
      "Recht",
      "Schutz",
      "Versicherung",
      "Gesellschaft"
    ]
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:53 GMT",
    "content-type": "application/json",
    "content-length": "126",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "deu",
    "x-rosetteapi-request-id": "941ccf2e32ff87d0c44fcf88c920f5ff",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Decompounding REST endpoint is https://api.rosette.com/rest/v1/morphology/compound-components

With the decompounding feature, Rosette breaks down compound words into sub-components and returns the individual elements. This is useful for increasing search relevancy in languages such as German and Korean.

For example, the German compound word “Rechtsschutzversicherungsgesellschaften” means “legal expenses insurance companies”.
Rosette returns these compound components: “Recht”, “Schutz”, “Versicherung”, and “Gesellschaft”.

You can specify the language of your input by including the three-letter language code within your request. If you do not include this field then Rosette automatically detects the language of the input.

Han Readings


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the complete morphological analysis of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "morphology";

var morphology_han_readings_data = "北京大学生物系主任办公室内部会议";
var content = morphology_han_readings_data;

api.parameters.content = content;
api.parameters.morphology = "han-readings";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class morphology_han_readings
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //morphology_han_readings yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI MorphologyCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string morphology_han_readings_data = @"北京大学生物系主任办公室内部会议";
                //The results of the API call will come back in the form of a Dictionary
                MorphologyResponse response = MorphologyCAPI.Morphology(morphology_han_readings_data, null, null, null, MorphologyFeature.hanReadings);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

morphology_han_readings_data <- "北京大学生物系主任办公室内部会议"

parameters <- list()
parameters[["content"]] <- morphology_han_readings_data
parameters[["morphology"]] <- "han-readings"

if (is.na(opt$url)) {
   result <- api(opt$key, "morphology", parameters)
} else {
   result <- api(opt$key, "morphology", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

morphology_han_readings_data = "北京大学生物系主任办公室内部会议"
begin
  params = DocumentParameters.new(content: morphology_han_readings_data)
  response = rosette_api.get_han_readings(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.api.MorphologicalFeature;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.MorphologyOptions;
import com.basistech.rosette.apimodel.MorphologyResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.MORPHOLOGY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class MorphologyHanReadingsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new MorphologyHanReadingsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String morphologyHanReadingsData = "北京大学生物系主任办公室内部会议";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        DocumentRequest<MorphologyOptions> request = DocumentRequest.<MorphologyOptions>builder().content(morphologyHanReadingsData)
                .build();
        MorphologyResponse response = rosetteApi.perform(MORPHOLOGY_SERVICE_PATH + "/" + MorphologicalFeature.HAN_READINGS,
                request, MorphologyResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$morphology_han_readings_data = "北京大学生物系主任办公室内部会议";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $morphology_han_readings_data);

try {
    $result = $api->morphology($params, RosetteConstants::$MorphologyOutput['HAN_READINGS']);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)
    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#morphological-analysis-introduction

    # api.set_option('modelType','perceptron') #Valid for Chinese and Japanese only

    morphology_han_readings_data = "北京大学生物系主任办公室内部会议"
    params = DocumentParameters()
    params["content"] = morphology_han_readings_data
    try:
        return api.morphology(params, api.morphology_output['HAN_READINGS'])
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "北京大学生物系主任办公室内部会议"}' \
    "https://api.rosette.com/rest/v1/morphology/han-readings"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "tokens": [
    "北京大学",
    "生物",
    "系主任",
    "办公室",
    "内部",
    "会议"
  ],
  "hanReadings": [
    [
      "běijīngdàxué"
    ],
    [
      "shēngwù"
    ],
    [
      "xìzhǔrèn"
    ],
    [
      "bàngōngshì"
    ],
    [
      "nèibù"
    ],
    [
      "huìyì"
    ]
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:53 GMT",
    "content-type": "application/json",
    "content-length": "187",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "zho",
    "x-rosetteapi-request-id": "6055a85d4cc3729b9ad3245e0887e54e",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Han Readings REST endpoint is https://api.rosette.com/rest/v1/morphology/han-readings

The Han readings feature provides pronounciation information for Han script, in both Chinese and Japanese input text. The algorithm selected will impact the Han reading returned.

For Chinese tokens in Han script, by default Rosette returns pinyin transcriptions using diacritics. Multiple possible readings may be returned for each word. If you call Rosette with “美国大选中的”, it returns these Han readings: [[“měiguó”], [“dàxuǎn”], [“zhōng”, “zhòng”], [“de”, “di”, “dī”, “dí”, “dì”]]. Note that the last two tokens each contain multiple possible readings.

For Japanese tokens in Han script (kanji), by default Rosette returns hiragana transcriptions. If you call Rosette with “医療番組”, it returns these Han readings: “いりょう”, “ばんぐみ”.

You can specify that Rosette should use the perceptron algorithm instead of the default algorithm ("options": {"modelType": "perceptron"}).

For Chinese tokens, using the perceptron algorithm, Rosette returns one pinyin transcription per token, using digits. If you call Rosette with “美国大选中的”, it returns these Han readings: “Mei3-guo2”, “da4-xuan3”, “zhong1”, “de0”.

For Japanese, using the perceptron algorithm, Rosette returns katakana transcriptions. If you call Rosette with “医療番組”, it returns these Han readings: “イリョウ”, “バングミ”.

You can specify the language of your input by including the three-letter language code within your request. If you do not include this field then Rosette automatically detects the language of the input.

Lemmas


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the complete morphological analysis of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "morphology";

var morphology_lemmas_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
var content = morphology_lemmas_data;

api.parameters.content = content;
api.parameters.morphology = "lemmas";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class morphology_lemmas
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //morphology_lemmas yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI MorphologyCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string morphology_lemmas_data = @"The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
                //The results of the API call will come back in the form of a Dictionary
                RosetteResponse response = MorphologyCAPI.Morphology(morphology_lemmas_data, null, null, null, MorphologyFeature.lemmas);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ContentAsJson);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

morphology_lemmas_data <- "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"

parameters <- list()
parameters[["content"]] <- morphology_lemmas_data
parameters[["morphology"]] <- "lemmas"

if (is.na(opt$url)) {
   result <- api(opt$key, "morphology", parameters)
} else {
   result <- api(opt$key, "morphology", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

morphology_lemmas_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"
begin
  params = DocumentParameters.new(content: morphology_lemmas_data)
  response = rosette_api.get_lemmas(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.api.MorphologicalFeature;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.MorphologyOptions;
import com.basistech.rosette.apimodel.MorphologyResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.MORPHOLOGY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class MorphologyLemmasExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new MorphologyLemmasExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String morphologyLemmasData = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        DocumentRequest<MorphologyOptions> request = DocumentRequest.<MorphologyOptions>builder().content(morphologyLemmasData)
                .build();
        MorphologyResponse response = rosetteApi.perform(MORPHOLOGY_SERVICE_PATH + "/" + MorphologicalFeature.LEMMAS,
                request, MorphologyResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$morphology_lemmas_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $morphology_lemmas_data);

try {
    $result = $api->morphology($params, RosetteConstants::$MorphologyOutput['LEMMAS']);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#morphological-analysis-introduction

    # api.set_option('modelType','perceptron') #Valid for Chinese and Japanese only

    morphology_lemmas_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"
    params = DocumentParameters()
    params["content"] = morphology_lemmas_data
    try:
        return api.morphology(params, api.morphology_output['LEMMAS'])
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "The fact is that the geese just went back to get a rest and I\u0027m not banking on their return soon"}' \
    "https://api.rosette.com/rest/v1/morphology/lemmas"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "tokens": [
    "The",
    "fact",
    "is",
    "that",
    "the",
    "geese",
    "just",
    "went",
    "back",
    "to",
    "get",
    "a",
    "rest",
    "and",
    "I",
    "'m",
    "not",
    "banking",
    "on",
    "their",
    "return",
    "soon"
  ],
  "lemmas": [
    "the",
    "fact",
    "be",
    "that",
    "the",
    "goose",
    "just",
    "go",
    "back",
    "to",
    "get",
    "a",
    "rest",
    "and",
    "I",
    "be",
    "not",
    "bank",
    "on",
    "they",
    "return",
    "soon"
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:53 GMT",
    "content-type": "application/json",
    "content-length": "301",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "974e8e3669c05b65652eebf16874ec1e",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Lemmas REST endpoint is https://api.rosette.com/rest/v1/morphology/lemmas

A lemma is the dictionary form of a word. Rosette determines the lemma each word in the input based on its usage and context.

For example, saw can be used as a noun or a past tense verb.
In the sentence “The carpenter picked up the saw from the workbench,” Rosette returns the lemma “saw”, a noun.
However, in the sentence “The bird saw the worm in the shade of the tree,” Rosette returns the lemma “see”, the dictionary-form of the verb.

You can specify the language of your input by including the three-letter language code within your request. If you do not include this field then Rosette automatically detects the language of the input.

Parts of Speech


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the complete morphological analysis of a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "morphology";

var morphology_parts_of_speech_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
var content = morphology_parts_of_speech_data;

api.parameters.content = content;
api.parameters.morphology = "parts-of-speech";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class morphology_parts_of_speech
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //morphology_parts_of_speech yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI MorphologyCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string morphology_parts_of_speech_data = @"The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
                //The results of the API call will come back in the form of a Dictionary
                MorphologyResponse response = MorphologyCAPI.Morphology(morphology_parts_of_speech_data, null, null, null, MorphologyFeature.partsOfSpeech);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

morphology_parts_of_speech_data <- "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"

parameters <- list()
parameters[["content"]] <- morphology_parts_of_speech_data
parameters[["morphology"]] <- "parts-of-speech"

if (is.na(opt$url)) {
   result <- api(opt$key, "morphology", parameters)
} else {
   result <- api(opt$key, "morphology", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

morphology_parts_of_speech_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"
begin
  params = DocumentParameters.new(content: morphology_parts_of_speech_data)
  response = rosette_api.get_parts_of_speech(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.api.MorphologicalFeature;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.MorphologyOptions;
import com.basistech.rosette.apimodel.MorphologyResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.MORPHOLOGY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class MorphologyPartsOfSpeechExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new MorphologyPartsOfSpeechExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String morphologyPartsOfSpeechData = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        DocumentRequest<MorphologyOptions> request = DocumentRequest.<MorphologyOptions>builder().content(morphologyPartsOfSpeechData)
                .build();
        MorphologyResponse response = rosetteApi.perform(MORPHOLOGY_SERVICE_PATH + "/" + MorphologicalFeature.PARTS_OF_SPEECH,
                request, MorphologyResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$morphology_parts_of_speech_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $morphology_parts_of_speech_data);

try {
    $result = $api->morphology($params, RosetteConstants::$MorphologyOutput['PARTS_OF_SPEECH']);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#morphological-analysis-introduction

    # api.set_option('modelType','perceptron') # Valid for Chinese and Japanese only

    morphology_parts_of_speech_data = "The fact is that the geese just went back to get a rest and I'm not banking on their return soon"
    params = DocumentParameters()
    params["content"] = morphology_parts_of_speech_data
    try:
        return api.morphology(params, api.morphology_output['PARTS_OF_SPEECH'])
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "The fact is that the geese just went back to get a rest and I\u0027m not banking on their return soon"}' \
    "https://api.rosette.com/rest/v1/morphology/parts-of-speech"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "tokens": [
    "The",
    "fact",
    "is",
    "that",
    "the",
    "geese",
    "just",
    "went",
    "back",
    "to",
    "get",
    "a",
    "rest",
    "and",
    "I",
    "'m",
    "not",
    "banking",
    "on",
    "their",
    "return",
    "soon"
  ],
  "posTags": [
    "DET",
    "NOUN",
    "VERB",
    "SCONJ",
    "DET",
    "NOUN",
    "ADV",
    "VERB",
    "ADV",
    "PART",
    "VERB",
    "DET",
    "NOUN",
    "CONJ",
    "PRON",
    "VERB",
    "PART",
    "VERB",
    "ADP",
    "DET",
    "NOUN",
    "ADV"
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:53 GMT",
    "content-type": "application/json",
    "content-length": "313",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "f6570c6f5263eab07ed07861f4821edf",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Parts of Speech REST endpoint is https://api.rosette.com/rest/v1/morphology/parts-of-speech

The morphology endpoint grammatically analyzes text to determine the role of each word within the input. The Parts of Speech feature returns a part-of-speech (POS) tag for each of the words, depending on the context of how it is used.

For example, spoke can be classified as a noun or a verb. “The wheel spoke creaked,” (noun) compared to, “She spoke the truth” (verb).

Universal POS Tags

All of the supported languages return the following Universal Parts of Speech Tags:

An array of null values may be returned for the posTags if a language does not support parts of speech tags.

Language Support

You can use the GET /morphology/supported-languages method to dynamically retrieve the list of supported languages and associated scripts for the morphological analysis endpoint. Calls to all sub-endpoints are supported.

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Language (code) Complete Parts of Speech Lemmas Compound Components Han Readings
Arabic (ara) ✓ ✓ ✓
Catalan (cat) ✓ ✓
Chinese (zho) ✓ ✓ ✓ ✓
Czech (ces) ✓ ✓ ✓
Danish (dan) ✓ ✓ ✓
Dutch (nld) ✓ ✓ ✓ ✓
English (eng) ✓ ✓ ✓
Estonian (est) ✓ ✓
Finnish (fin) ✓
French (fra) ✓ ✓ ✓
German (deu) ✓ ✓ ✓ ✓
Greek (ell) ✓ ✓ ✓
Hebrew (heb) ✓ ✓ ✓
Hungarian (hun) ✓ ✓ ✓ ✓
Indonesian (ind) ✓ ✓ ✓
Italian (ita) ✓ ✓ ✓
Japanese (jpn) ✓ ✓ ✓ ✓
Korean (kor) ✓ ✓ ✓
Korean - North (qkp) ✓ ✓ ✓
Korean - South (qkr) ✓ ✓ ✓
Latvian (lav) ✓ ✓
Malay, Standard (zsm) ✓ ✓ ✓
Norwegian (nor) ✓ ✓ ✓
Norwegian (Bokmål) (nob) ✓ ✓ ✓
Norwegian (Nynorsk) (nno) ✓ ✓ ✓
Pashto (pus) ✓
Persian (fas) ✓ ✓ ✓
Persian - Afghan (prs) ✓ ✓ ✓
Persian - Iranian (pes) ✓ ✓ ✓
Polish (pol) ✓ ✓ ✓
Portuguese (por) ✓ ✓ ✓
Romanian (ron) ✓ ✓
Russian (rus) ✓ ✓ ✓
Serbian (srp) 1 ✓ ✓ (Latin script Only)
Slovak (slk) ✓ ✓
Spanish (spa) ✓ ✓ ✓
Swedish (swe) ✓ ✓ ✓
Tagalog (tgl) ✓ ✓ ✓
Thai (tha) ✓ ✓
Turkish (tur) ✓ ✓
Ukrainian (ukr) ✓
Urdu (urd) ✓ ✓

Name Deduplication

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Deduplicate a list of names"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "nameDeduplication";

var name_dedupe_data = "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday";

api.parameters.names = name_dedupe_data.split(",").map(function(name) {
    return {"text": name, "language": "eng", "entityType": "PERSON"}
});
api.parameters.threshold = 0.75;

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class name_deduplication
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //matched_name yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI rosetteApi = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string name_dedupe_data = @"Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday";

                List<string> dedup_names = name_dedupe_data.Split(',').ToList<string>();
                List<Name> names = dedup_names.Select(name => new Name(name, "eng", "Latn")).ToList();
                float threshold = 0.75f;

                //The results of the API call will come back in the form of a Dictionary
                NameDeduplicationResponse response = rosetteApi.NameDeduplication(names, threshold);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

name_dedupe_data <- "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday"


text <- unlist(strsplit(name_dedupe_data, ","))
target_language <- rep("eng", length(text))
target_script <- rep("Latn", length(text))

names <- data.frame(text, target_language, target_script)
parameters <- list()
parameters[["names"]] <- names
parameters[["threshold"]] <- 0.75

if (is.na(opt$url)) {
   result <- api(opt$key, "name-deduplication", parameters)
} else {
   result <- api(opt$key, "name-deduplication", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

name_dedupe_data = "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday"

threshold = 0.75
names = name_dedupe_data.split(',').map { |n| NameParameter.new(n) }
begin
  params = NameDeduplicationParameters.new(names, threshold)
  response = rosette_api.get_name_deduplication(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.Name;
import com.basistech.rosette.apimodel.NameDeduplicationRequest;
import com.basistech.rosette.apimodel.NameDeduplicationResponse;

import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.NAME_DEDUPLICATION_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class NameDeduplicationExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new NameDeduplicationExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String nameDedupeData = "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday";
        List<String> listOfNames = new ArrayList<String>(Arrays.asList(nameDedupeData.split(",")));

        ArrayList<Name> names = new ArrayList<>();
        for (String name: listOfNames) {
            names.add(Name.builder().text(name).build());
        }
        double threshold = 0.75;

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        NameDeduplicationRequest request = NameDeduplicationRequest.builder().names(names).threshold(threshold).build();
        NameDeduplicationResponse response = rosetteApi.perform(NAME_DEDUPLICATION_SERVICE_PATH, request,
                NameDeduplicationResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\Name;
use rosette\api\NameDeduplicationParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$name_dedupe_data = "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday";

$dedup_array = array();
$threshold = 0.75;
foreach (explode(',', $name_dedupe_data) as $name) {
    array_push($dedup_array, new Name($name));
}
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new NameDeduplicationParameters($dedup_array, $threshold);

try {
    $result = $api->nameDeduplication($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, NameDeduplicationParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    name_dedupe_data = "Alice Terry,Alice Thierry,Betty Grable,Betty Gable,Norma Shearer,Norm Shearer,Brigitte Helm,Bridget Helem,Judy Holliday,Julie Halliday"
    threshold = 0.75
    params = NameDeduplicationParameters()
    params["names"] = name_dedupe_data.split(',')
    params["threshold"] = threshold
    try:
        return api.name_deduplication(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"names": [{"text":"Alice Terry"},{"text":"Alice Thierry"},{"text":"Betty Grable"},{"text":"Betty Gable"},{"text":"Norma Shearer"},{"text":"Norm Shearer"},{"text":"Brigitte Helm"},{"text":"Bridget Helem"},{"text":"Judy Holliday"},{"text":"Julie Halliday"}] , "threshold": 0.75 }' \
    "https://api.rosette.com/rest/v1/name-deduplication"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "results": [
    "4",
    "4",
    "2",
    "2",
    "6",
    "3",
    "1",
    "1",
    "5",
    "5"
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:54 GMT",
    "content-type": "application/json",
    "content-length": "53",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-request-id": "0c176c969caee7ae12a5e7688445dda3",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Name Deduplication REST endpoint is https://api.rosette.com/rest/v1/name-deduplication

This endpoint is designed for users who have a list of names that they wish to deduplicate. Deduplication is accomplished by grouping similar names into clusters. Rosette matches across name variations (such as misspellings and nicknames) with multilingual support by using a linguistic, statistically-based system. A threshold parameter determines how much variation between names is permitted in any given cluster. There is a limit of 1000 names per list per call.

Given a list of names as input, the output is a cluster ID for each name. Similar names are given the same cluster ID. The output may then be sorted by cluster ID to group together possible duplicate names.

Input (names) Output (cluster ID)
John Smith 1
Cyndi McBoysen 2
Dmitri Shostakovich 4
Jim Hockenberry 3
Takeshi Suzuki 5
Jon Smythe 1
James Hawkenbury 3
Cindy MacBoysen 2
Дми́трий Шостако́вич 4

Request Fields

Example:

{
  "names": [
    {"text": "Alice Terry", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Alice Thierry", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Betty Grable", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Betty Gable", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Norma Shearer", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Norm Shearer", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Brigitte Helm", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Bridget Helem", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Judy Holliday", "entityType":"PERSON", "script":"Latn", "language":"eng"},
    {"text": "Julie Halliday", "entityType":"PERSON", "script":"Latn", "language":"eng"}
  ],
  "threshold": 0.8
}

{
    "results": [
        "3",
        "3",
        "7",
        "7",
        "6",
        "6",
        "4",
        "5",
        "1",
        "2"
    ]
}

When you submit a name-deduplication request, you need only input a list of names and an optional threshold; however, we strongly recommend specifying the source language (if known) for better accuracy. If you do not specify the source language then the Rosette name similarity algorithm will guess the language.

NOTE: Do not use the Rosette language detection endpoint to determine source language of names as the language guesser within the name similarity endpoint uses an algorithm tuned specifically for names rather than general text.

For each name in the input name list, you may also include any of the additional fields that appear in the following table.

Field Description Required
text1 Name to match yes
language Three-letter language code for the name no (but strongly recommended if source language is known)
entityType PERSON (default), LOCATION, or ORGANIZATION no
script Four-letter language code for script in which name is written no

Language Support

You can use the GET /name-deduplication/supported-languages method to dynamically retrieve the list of supported languages and associated scripts for the name-deduplication endpoint.

The Rosette Name Deduplication functions support matching names within each language in the table below (e.g., RUS name ⇔ RUS name) and between each language and English (e.g., RUS name ⇔ ENG name). Additionally, it supports name matching between Chinese, Japanese, and, Korean names. (e.g., ZHO name ⇔ KOR name ⇔ JPN name)

Language (code) Script(s) (Abbr.)
Arabic (ara) Arabic (Arab)
Burmese (mya) Burmese (Mymr)
Chinese (zho)¹ Han (Hani)
English (eng) Latin (Latn)
French (fra) Latin (Latn)
German (deu) Latin (Latn)
Greek (ell) Greek (Grek)
Hebrew (heb) Hebrew (Hebr)
Hungarian (hun) Latin (Latn)
Italian (ita) Latin (Latn)
Japanese (jpn)¹ Han (Hani), Hiragana (Hira), Katakana (Kana), (Hrkt) Hira + Kana, Japanese (Jpan) Han + Hira + Kana
Korean (kor)¹ Hangul (Hang), Han (Hani), Korean (Kor) Hang + Hani
Pashto (pus) Arabic (Arab)
Persian (fas) Arabic (Arab)
Portuguese (por) Latin (Latn)
Russian (rus) Cyrillic (Cyrl)
Spanish (spa) Latin (Latn)
Thai (tha) Thai (Thai)
Turkish (tur) Latin (Latn)
Urdu (urd) Arabic (Arab)
Vietnamese (vie) Latin (Latn)

Name Similarity

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the similarity score of two names"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "nameSimilarity";

var matched_name_data1 = "Michael Jackson";
var matched_name_data2 = "迈克尔·杰克逊";

api.parameters.name1 = {"text": matched_name_data1, "language": "eng", "entityType": "PERSON"};
api.parameters.name2 = {"text": matched_name_data2, "entityType": "PERSON"};

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class matched_name
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //matched_name yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            } 
            try
            {
                CAPI MatchedNameCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string matched_name_data1 = @"Michael Jackson";
                string matched_name_data2 = @"迈克尔·杰克逊";
                //The results of the API call will come back in the form of a Dictionary
                NameSimilarityResponse response = MatchedNameCAPI.NameSimilarity(new Name(matched_name_data1, "eng", null, "PERSON"), new Name(matched_name_data2, null, null, "PERSON"));
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)


matched_name_data1 <- "Michael Jackson"
matched_name_data2 <- "迈克尔·杰克逊"

parameters <- list()
parameters[["name1"]] <- matched_name_data1
parameters[["name2"]] <- matched_name_data2

if (is.na(opt$url)) {
   result <- api(opt$key, "name-similarity", parameters)
} else {
   result <- api(opt$key, "name-similarity", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

matched_name_data1 = "Michael Jackson"
matched_name_data2 = "迈克尔·杰克逊"
begin
  name1 = NameParameter.new(
    matched_name_data1,
    entity_type: 'PERSON',
    language: 'eng'
  )
  params = NameSimilarityParameters.new(name1, matched_name_data2)
  response = rosette_api.get_name_similarity(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.Name;
import com.basistech.rosette.apimodel.NameSimilarityRequest;
import com.basistech.rosette.apimodel.NameSimilarityResponse;
import com.basistech.util.ISO15924;
import com.basistech.util.LanguageCode;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.NAME_SIMILARITY_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class NameSimilarityExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new NameSimilarityExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String matchedNameData1 = "Michael Jackson";
        String matchedNameData2 = "迈克尔·杰克逊";
        Name name1 = Name.builder().text(matchedNameData1)
                .entityType("PERSON")
                .script(ISO15924.Zyyy)
                .language(LanguageCode.ENGLISH)
                .build();
        Name name2 = Name.builder().text(matchedNameData2).build();
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        NameSimilarityRequest request = NameSimilarityRequest.builder().name1(name1).name2(name2).build();
        NameSimilarityResponse response = rosetteApi.perform(NAME_SIMILARITY_SERVICE_PATH, request, NameSimilarityResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\Name;
use rosette\api\NameSimilarityParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$name_similarity_data1 = "Michael Jackson";
$name_similarity_data2 = "迈克尔·杰克逊";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new NameSimilarityParameters(new Name($name_similarity_data1), new Name($name_similarity_data2));

try {
    $result = $api->nameSimilarity($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, NameSimilarityParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    matched_name_data1 = "Michael Jackson"
    matched_name_data2 = "迈克尔·杰克逊"
    params = NameSimilarityParameters()
    params["name1"] = {"text": matched_name_data1, "language": "eng", "entityType": "PERSON"}
    params["name2"] = {"text": matched_name_data2, "entityType": "PERSON"}
    try:
        return api.name_similarity(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"name1": {"text": "Michael Jackson"}, "name2": {"text": "迈克尔·杰克逊"} }' \
    "https://api.rosette.com/rest/v1/name-similarity"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "score": 0.9897961,
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:54 GMT",
    "content-type": "application/json",
    "content-length": "19",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-request-id": "e95a0e8f9cdc68f8c7944b05ef99a221",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Name Similarity REST endpoint is https://api.rosette.com/rest/v1/name-similarity

Rosette can compare two entity names (Person, Location, Organization, or Identifier) and return a match score from 0 to 1.

Rosette handles name variations (such as misspellings and nicknames) with multilingual support by using a linguistic, statistically-based system.

You can modify the value of one or more parameters used in a request by adding the parameters object to the call. Any non-static parameter can be changed. For example, to change the value of the deletionScore, add parameters to the request:

"parameters": {"deletionScore": "0.2" }

See Name Matching Parameters for a list of parameters.

Request Fields

Example:

{
  "name1": {
    "text": "Влади́мир Влади́мирович Пу́тин",
    "language": "rus",
    "entityType": "PERSON"
  },
  "name2": {
    "text": "Vladimir Putin",
    "language": "eng",
    "entityType": "PERSON"
  }
}

{
  "result": {
    "score": 0.9486632809417912
  }
}

When you submit a name-similarity request, you must specify name1 and name2 with the text for each. Although not required, we strongly recommend specifying the source language (if known) for better accuracy. If you do not specify the source language then the Rosette name similarity algorithm will guess the language.

NOTE: Do not use the Rosette language detection endpoint to determine source language of names as the language guesser within the name similarity endpoint uses an algorithm tuned specifically for names rather than general text.

For each name, you can also include any of the additional fields that appear in the following table.

Where known, we recommend specifying the entityType to identify the type of name. Name Similarity uses the entityType field to optimize the algorithms used for matching. When not specified, Name Similarity may return less accurate results.

Field Description Required
text1 Name to match yes
language Three-letter language code for the name no
entityType PERSON (default), LOCATION, ORGANIZATION, or IDENTIFIER no
script Four-letter language code for script in which the name is written no

Based on the text of the two names, the Rosette Name Similarity endpoint infers values for any of the fields you do not specify, and uses these values when it calculates the match score. If you know the value, especially entityType and language (in cases where the language may be difficult to infer accurately, such as a Japanese or Korean name in Han script), you may improve the accuracy of the match score by specifying the field. See Language Support for languages that are supported.

The Rosette Name Similarity endpoint determines a score by matching tokens generated from both input names. If the names do not have a specified entityType, Rosette Name Similarity will attempt to match the names the best it can. Without more information, names with a small number of generated tokens may produce the same similarity score. For example, without an entityType of Location, the similarity scores for Canada to Mexico and Beijing to Mexico are the same.

Parameters

Parameter Description
conflictScore The score that is assigned to unmatched conflict tokens. Increasing leads to higher final score
initialsConflictScore The score that is assigned to unmatched conflict initials. Increasing leads to higher final score
initialsScore The score that is assigned to an initial matching a token. Increasing leads to higher final score
initialismScore Score assigned to initialism matching a name. Increasing leads to higher final score

Language Support

You can use the GET /name-similarity/supported-languages method to dynamically retrieve language pairs supported by the name-similarity endpoint. The endpoint supports matching between the source and target of each pair. The language, script, and transliteration scheme are listed for each source and target.

The Rosette Name Similarity endpoint supports matches between names in the following languages. It also supports matching names between all these languages and English.

Language (code) Script(s) (Abbr.)
Arabic (ara) Arabic (Arab)
Burmese (mya) Burmese (Mymr)
Chinese (zho)¹ Han (Hani)
English (eng) Latin (Latn)
French (fra) Latin (Latn)
German (deu) Latin (Latn)
Greek (ell) Greek (Grek)
Hebrew (heb) Hebrew (Hebr)
Hungarian (hun) Latin (Latn)
Italian (ita) Latin (Latn)
Japanese (jpn)¹ Han (Hani), Hiragana (Hira), Katakana (Kana), (Hrkt) Hira + Kana, Japanese (Jpan) Han + Hira + Kana
Korean (kor)¹ Hangul (Hang), Han (Hani), Korean (Kor) Hang + Hani
Pashto (pus) Arabic (Arab)
Persian (fas) Arabic (Arab)
Portuguese (por) Latin (Latn)
Russian (rus) Cyrillic (Cyrl)
Spanish (spa) Latin (Latn)
Thai (tha) Thai (Thai)
Turkish (tur) Latin (Latn)
Urdu (urd) Arabic (Arab)
Vietnamese (vie) Latin (Latn)

Name Translation

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Translate a name from one language to another"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "nameTranslation";

var translated_name_data = "معمر محمد أبو منيار القذاف";
api.parameters.name = translated_name_data;
api.parameters.entityType = "PERSON";
api.parameters.targetLanguage = "eng";
api.parameters.targetScript = "Latn";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class translated_name
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //translated_name yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI TranslatedNameCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string translated_name_data = @"معمر محمد أبو منيار القذاف";
                //The results of the API call will come back in the form of a Dictionary
                TranslateNamesResponse response = TranslatedNameCAPI.NameTranslation(translated_name_data, null, null, "eng", "Latn", null, null, "PERSON");
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

translated_name_data <- "معمر محمد أبو منيار القذاف"

parameters <- list()
parameters[["name"]] <- translated_name_data
parameters[["targetLanguage"]] <- "eng"
parameters[["targetScript"]] <- "Latn"

if (is.na(opt$url)) {
   result <- api(opt$key, "name-translation", parameters)
} else {
   result <- api(opt$key, "name-translation", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

translated_name_data = "معمر محمد أبو منيار القذاف"
begin
  params = NameTranslationParameters.new(
    translated_name_data,
    'eng',
    target_script: 'Latn'
  )
  response = rosette_api.get_name_translation(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.NameTranslationRequest;
import com.basistech.rosette.apimodel.NameTranslationResponse;
import com.basistech.util.LanguageCode;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.NAME_TRANSLATION_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class NameTranslationExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new NameTranslationExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String translatedNameData = "معمر محمد أبو منيار القذاف";
        NameTranslationRequest request = NameTranslationRequest.builder()
                .name(translatedNameData)
                .targetLanguage(LanguageCode.ENGLISH)
                .build();

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                    .key(getApiKeyFromSystemProperty())
                                    .url(getAltUrlFromSystemProperty())
                                    .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        NameTranslationResponse response = rosetteApi.perform(NAME_TRANSLATION_SERVICE_PATH, request, NameTranslationResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\NameTranslationParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$name_translation_data = "معمر محمد أبو منيار القذاف";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new NameTranslationParameters();
$params->set('name', $name_translation_data);
$params->set('targetLanguage', 'eng');
$params->set('targetScript', 'Latn');
$params->set('targetScheme', 'IC');
$params->set('sourceLanguageOfOrigin', 'ara');
$params->set('sourceLanguageOfUse', 'ara');


try {
    $result = $api->nameTranslation($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, NameTranslationParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    translated_name_data = "معمر محمد أبو منيار القذاف"
    params = NameTranslationParameters()
    params["name"] = translated_name_data
    params["entityType"] = "PERSON"
    params["targetLanguage"] = "eng"
    params["targetScript"] = "Latn"
    try:
        return api.name_translation(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"name": "معمر محمد أبو منيار القذاف", "targetLanguage": "eng", "targetScript": "Latn"}"' \
    "https://api.rosette.com/rest/v1/name-translation"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "targetLanguage": "eng",
  "targetScript": "Latn",
  "targetScheme": "IC",
  "translation": "Mu'ammar Muhammad Abu-Minyar al-Qadhaf",
  "confidence": 0.06856099,
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:54 GMT",
    "content-type": "application/json",
    "content-length": "145",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-request-id": "15e8139f25b05f75e788ea710c036a85",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Name Translation REST endpoint is: https://api.rosette.com/rest/v1/name-translation

The name translation endpoint transliterates the name of an entity (Person, Location, or Organization) from English to another language, or to English from another language.

When you are converting from English to another language, the endpoint is optimized to convert the English version of a person’s name back to the native language of that name. For example, you can translate Vladimir Nabokov into Russian (rus) and the endpoint returns "translation": "Владимир Набоков".

Confidence

Rosette returns a confidence score with each entity result, ranging from 0 to 1. It is a measurement that you can use as a threshold for filtering out undesired results.

Request Fields

You must specify the name and the targetLanguage for the translation when you submit a request to the /name-translation endpoint.

For example, to translate “بدر شاكر السياب” from Arabic to English, “Badr Shakir al-Sayyab”, you would use the values in the Example column.

Field Description Value Example
name1 Name to translate String “بدر شاكر السياب”
targetLanguage Translate name into this language 3-letter language code eng

Optionally, you can include any of the following fields:

Field Description Value Example
entityType The type of name PERSON (default), LOCATION, or ORGANIZATION PERSON
sourceScript Script of the name as in the input 4-letter script abbr. Arab
sourceLanguageOfOrigin Native language the name originates in 3-letter language code ara
sourceLanguageOfUse Language of the name as in the input 3-letter language code ara
targetScript Translate name into this script 4-letter script abbr. Latn
targetScheme (ADVANCED USE ONLY) Scheme for transliteration Translit. scheme abbr. IC

We recommend that you include sourceLanguageOfUse for optimal results, if you know the value. If you do not specify the language, then Rosette detects it using an algorithm specific to names.

Examples:

For the name Mahmoud Abbas, the language of use is English but the language of origin is Arabic since it is an Arabic name transliterated to English.

For ドナルド・トランプ the language of use is Japanese, but the language of origin is English since it is the name Donald Trump rendered in katakana.

For 上海 and 北京, they are Chinese names of Chinese cities, so the language of use and origin are the same.

Language Support

You can use the GET /name-translation/supported-languages method to dynamically retrieve language pairs supported by the name-translation endpoint. The endpoint supports transliteration of the source language into the target language of each pair. The language, script, and transliteration scheme are listed for each source and target.

The Rosette Name Translation endpoint supports:

When translating from English, we recommend you use the endpoint to translate names of people to the name’s native language.

Language (code) Script(s) (Abbr.) Transliteration scheme(s) (ABBR.) ¹
Arabic (ara) Arabic (Arab) Intelligence Community (IC, default); Basis (BASIS); Buckwalter (BUCKWALTER); Folk (FOLK); Intelligence Community Extended (EXT_IC); Standard Arabic Technical Transliteration System (SATTS); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN); US Foreign Broadcast Information Service (FBIS)
Burmese (mya) Burmese (Mymr) MCLTS (mclts)
Chinese (zho)2, 3 Han (Hani) Hanyu Pinyin (HYPY, default); Chinese Telegraph Code (CTC); Hanyu Pinyin Toned (HYPY_TONED); Intelligence Community (IC); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN); Wade-Giles (WADE_GILES)
English (eng) Latin (Latn) Native (NATIVE, default)4
Greek (ell) Greek (Grek) Romanized Greek Alphabet (ISO843_1997, default); ICU (ICU)
Hebrew (heb) Hebrew (Hebr) Folk (FOLK, default); ICU (ICU); ISO 259-2:1994 (ISO_259_2_1994)
Hindi (hin) Devanagari (Deva) Intelligence Community (IC, default)
Japanese (jpn)2 Kanji (Hani), Hiragana (Hira), Katakana (Kana) Hebon Romaji (HEBON, default); Kunrei Romaji (KUNREI)
Korean (kor)2 Hangul (Hang), Hanja (Hani) Revised Romanization of Korean (MOCT, default); Folk (FOLK); Intelligence Community (IC); Korean Normalization for Data Applications (KORDA); McCune-Reischauer (MCR); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN)
Pashto (pus) Arabic (Arab) Intelligence Community (IC, default); Folk (FOLK); US Board on Geographic Names (BGN); US Board on Geogrpahic Names - Diacritics Removed (UND_BGN)
Persian (fas) Arabic (Arab) US Board on Geographic Names (BGN, default); Folk (FOLK); US Board on Geographic Names - Diacritics Removed (UND_BGN)
Persian - Afghan (prs), Persian - Iranian (pes) Arabic (Arab) Intelligence Community (IC, default); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN)
Russian (rus) Cyrillic (Cyrl) Intelligence Community (IC, default); Romanization of Cyrillic Alphabet (ISO9_1995); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN)
Thai (tha) Thai (Thai) Romanization of Thai Alphabet - Sequel (ISO_11940_2_2007, default); ICU (ICU); Romanization of Thai Alphabet (ISO_11940_25)
Urdu (urd) Arabic (Arab) Intelligence Community (IC, default); Folk (FOLK); US Board on Geographic Names (BGN); US Board on Geographic Names - Diacritics Removed (UND_BGN)

Relationship Extraction

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
    addHelp: true,
    description: "Get the relationships from a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "relationships";

var relationships_text_data = "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai.";
var content = relationships_text_data;

api.parameters.content = content;

api.rosette(endpoint, function(err, res) {
    if (err) {
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class relationships
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //relationships yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI RelationshipsCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string relationships_text_data = @"FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai.";
                //The results of the API call will come back in the form of a Dictionary
                RelationshipsResponse response = RelationshipsCAPI.Relationships(relationships_text_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

relationships_text_data <- "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai."

parameters <- list()
parameters[["content"]] <- relationships_text_data

if (is.na(opt$url)) {
   result <- api(opt$key, "relationships", parameters)
} else {
   result <- api(opt$key, "relationships", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

relationships_text_data = "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai."

begin
  params = DocumentParameters.new(content: relationships_text_data)
  response = rosette_api.get_relationships(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.RelationshipsOptions;
import com.basistech.rosette.apimodel.RelationshipsResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.RELATIONSHIPS_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class RelationshipsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new RelationshipsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String relationshipsTextData = "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai.";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        DocumentRequest<RelationshipsOptions> request = DocumentRequest.<RelationshipsOptions>builder().content(relationshipsTextData).build();
        RelationshipsResponse response = rosetteApi.perform(RELATIONSHIPS_SERVICE_PATH, request, RelationshipsResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$relationships_text_data = "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $relationships_text_data);

try {
    $result = $api->relationships($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)
    relationships_text_data = "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai."
    params = DocumentParameters()
    params["content"] = relationships_text_data
    try:
        return api.relationships(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC’s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR’s security cameras to the same government officials.  At the time, Timms was the head of FLIR’s Middle East office in Dubai."}' \
    "https://api.rosette.com/rest/v1/relationships/"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "relationships": [
    {
      "predicate": "Organization Headquarters",
      "predicateId": "ORG-HEADQUARTERS",
      "arg1": "FLIR Systems",
      "arg2": "Oregon",
      "arg2Id": "Q824"
    },
    {
      "predicate": "Citizen of",
      "predicateId": "CIT-OF",
      "arg1": "Timms",
      "arg1Id": "T5",
      "arg2": "Dubai",
      "arg2Id": "Q612",
      "confidence": 0.89470345
    },
    {
      "predicate": "Person Employee or Member of",
      "predicateId": "PER-EMPLOYEE-MEMBER-OF",
      "arg1": "Timms",
      "arg2": "FLIR"
    },
    {
      "predicate": "Organization top employees",
      "predicateId": "ORG-TOP-EMPLOYEES",
      "arg1": "FLIR",
      "arg2": "Timms"
    }
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:55 GMT",
    "content-type": "application/json",
    "content-length": "501",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "7a1300ee99405be18e49a9cd1b33da40",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Relationship Extraction REST endpoint is: https://api.rosette.com/rest/v1/relationships

Building on the results of entity extraction and linking, Rosette relationship extraction identifies how entities are related to each other.

Rosette performs targeted relationship extraction by finding anything within the text that looks like one of the supported relationship types. This allows you to filter and process the results according to your needs.

Using linguistic tools and Wikidata to bootstrap its knowledge, Rosette identifies the exact action connecting the entities and other related information. It uses machine learning methods over parse trees and entity mentions to analyze the connection, and then return the components within the relationships.

Relationship Types

Relation Description
ORG-FOUNDED Holds between an organization and a person or another organization that founded it
ORG-HEADQUARTERS Holds between an organization and the location where its headquarters are located
ORG-SUBSIDIARY-OF Holds between two organizations where the first is a subsidiary of the second
ORG-COLLABORATORS Holds between two organizations the are working together toward a project or a goal
ORG-ACQUIRED-BY Holds between two organizations where the first organization was acquired by the second one
ORG-PROVIDER-TO Holds between two organization where the first organization is providing services or products to the second organization
ORG-TOP-EMPLOYEES Holds between an organization and a person who is one of the organization’s top employees
PER-BIRTH-PLACE Holds between a person and the location in which he was born
PER-EMPLOYEE-MEMBER-OF Holds between a person and an organization with which the person is affiliated
PER-RESIDENCE Holds between a person and its current or past location of residence
PER-PARENTS Holds between two person entities where the second is the parent of the first
PER-SIBLINGS Holds between two person entities which are siblings of one another
PER-SPOUSE Holds between two person entities which are the life partners of one another
PER-OTHER-FAMILY Holds between two person entities that belong to the same family but are not siblings, parents, children, or spouse of one another
CIT-OF Holds between a person and his country of citizenship
EDU-AT Holds between a person and an academic institution he is affiliated with

Relationship Components

The endpoint identifies the following elements:

Language Support

You can use the GET /relationships/supported-languages method to dynamically retrieve the list of supported languages and scripts for the relationship extraction endpoint.

The Rosette relationship extraction endpoint currently only supports English language input.

Semantic Similarity

Introduction

The Semantic Similarity REST endpoint is: https://api.rosette.com/rest/v1/semantics/{semanticsFeature}

The Rosette semantic similarity endpoints provide tools for generating and using text vectors to identify semantically similar words in multiple supported languages.

Text vectors provide a mechanism for comparing documents or words based on their semantic similarity. For any given term (which may be a document or a single word), a location in semantic space, as represented by a vector of floating point numbers, is calculated. This vector can be mathematically compared with other term or document vectors. Words with similar meanings have similar contexts, so Rosette maps them close to each other. The terms being compared can be in the same or different languages, providing cross-lingual semantic similarity evaluation without the need for any translation.

In the semantic space, corresponding words in different languages have similar meanings and therefore similar mappings. Take for example, “Washington was the first president of the United States” and" Washington fue el primer presidente de los Estados Unidos“. These sentences have roughly equivalent meanings in both Spanish and English, which will be reflected in the proximity of their text vectors.

Contact us to discuss ways to build text vectors into your applications, or check out our blog post and sample code for an example use case.

Semantic Vectors


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the text embedding from a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "textEmbedding";
var semantic_vectors_data = "Cambridge, Massachusetts"

api.parameters.content = semantic_vectors_data;
api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class semantic_vectors
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //semantic-vectors yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI EmbeddingCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string semantic_vectors_data = @"Cambridge, Massachusetts";
                //The results of the API call will come back in the form of a Dictionary
                SemanticVectorsResponse response = EmbeddingCAPI.SemanticVectors(semantic_vectors_data);
                foreach (KeyValuePair<string, string> h in response.Headers)
                {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }

                Console.WriteLine(response.ContentAsJson);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

semantic_vectors_data <- "Cambridge, Massachusetts"

parameters <- list()
parameters[["content"]] <- semantic_vectors_data

if (is.na(opt$url)) {
   result <- api(opt$key, "semantics/vector", parameters)
} else {
   result <- api(opt$key, "semantics/vector", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

semantic_vectors_data = "Cambridge, Massachusetts"
begin
  params = DocumentParameters.new(content: semantic_vectors_data)
  response = rosette_api.get_semantic_vectors(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.SemanticVectorsOptions;
import com.basistech.rosette.apimodel.SemanticVectorsResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.SEMANTIC_VECTORS_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class SemanticVectorsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new SemanticVectorsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String semanticVectorsData = "Cambridge, Massachusetts";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        // When no options, use <?>.
        DocumentRequest<SemanticVectorsOptions> request = DocumentRequest.<SemanticVectorsOptions>builder()
            .content(semanticVectorsData)
            .build();
        SemanticVectorsResponse response = rosetteApi.perform(SEMANTIC_VECTORS_SERVICE_PATH, request, SemanticVectorsResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$semantic_vectors_data = "Cambridge, Massachusetts";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $semantic_vectors_data;
$params->set('content', $content);

try {
    $result = $api->semanticVectors($params, false);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#semantic-vectors

    # api.set_option('perToken', 'true')

    semantic_vectors_data = "Cambridge, Massachusetts"
    params = DocumentParameters()
    params["content"] = semantic_vectors_data
    try:
        return api.semantic_vectors(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Cambridge, Massachusetts" }' \
    "https://api.rosette.com/rest/v1/semantics/vector"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "documentEmbedding": [
    0.0220256,
    0.03633998,
    0.05246549,
    -0.03751056,
    0.0347335,
    0.02479751,
    -0.03860506,
    0.00603574,
    -0.04244069,
    0.00521813,
    0.01740657,
    -0.08501768,
    -0.01918706,
    -0.05974227,
    0.00762913,
    -0.00020686,
    -0.04639495,
    0.00458408,
    0.01220596,
    0.06160719,
    -0.03988802,
    -0.03095652,
    -0.01182547,
    0.04861571,
    0.02967435,
    -0.04560868,
    -0.16111824,
    -0.06562275,
    0.00208866,
    0.01622739,
    -0.09196278,
    0.13520485,
    0.03665138,
    -0.01748736,
    0.05908763,
    0.07113674,
    0.04435388,
    -0.04436791,
    -0.0018729,
    -0.03612895,
    0.00324841,
    0.0218222,
    0.00414962,
    0.02750619,
    -0.00466647,
    -0.03516347,
    0.00061686,
    0.03071387,
    0.060716,
    -0.05394382,
    -0.03460756,
    -0.0916905,
    -0.04351116,
    0.03095916,
    0.07264832,
    0.00440244,
    -0.06487004,
    -0.0124327,
    -0.02594845,
    0.06403252,
    0.05990276,
    0.08421157,
    0.00113943,
    -0.05188083,
    0.01336752,
    0.05737128,
    0.0868928,
    -0.02797472,
    0.02951868,
    -0.06528687,
    -0.02593506,
    -0.1377904,
    0.05021935,
    -0.00331138,
    0.00345429,
    -0.0806604,
    -0.02997256,
    0.04178474,
    -0.16860084,
    -0.00202994,
    0.04082655,
    0.04052638,
    -0.02616019,
    -0.07079905,
    0.04114204,
    -0.05405192,
    -0.02079529,
    0.03362259,
    0.12866253,
    0.04686183,
    0.03205459,
    0.01844979,
    0.10577367,
    -0.04331236,
    0.03550498,
    0.03498939,
    -0.05236725,
    0.05650697,
    -0.03229797,
    -0.05911481,
    0.08041807,
    -0.01093418,
    -0.04541076,
    0.00499057,
    0.03379054,
    0.01985912,
    0.05434353,
    -0.06876269,
    -0.02142489,
    -0.04368682,
    -0.02340091,
    0.04271708,
    -0.03868493,
    0.03260612,
    -0.00310602,
    -0.08135383,
    0.03890613,
    0.05206529,
    0.01902638,
    -0.03261049,
    -0.01225097,
    -0.04929554,
    0.06811376,
    -0.10045446,
    -0.03772711,
    0.06436889,
    0.0335337,
    0.03110947,
    -0.01010367,
    -0.03986244,
    0.01340914,
    -0.06304926,
    0.05365673,
    -0.07044137,
    0.06421522,
    0.0632241,
    -0.04348637,
    0.13118945,
    -0.02082631,
    0.07590587,
    -0.04813327,
    -0.02577493,
    0.05642929,
    0.00033935,
    -0.01024516,
    0.06391647,
    0.03264675,
    -0.02187326,
    0.04832495,
    0.02241259,
    0.05681982,
    -0.04124964,
    0.08708096,
    0.06066873,
    -0.03356391,
    -0.03327714,
    -0.03449181,
    -0.02047219,
    0.06597982,
    0.08629483,
    0.03777988,
    0.01191289,
    0.10955901,
    -0.05159367,
    1.431e-05,
    -0.00435081,
    -0.07139333,
    -0.10915583,
    -0.06582265,
    -0.02754464,
    0.04510804,
    0.09508634,
    -0.02923319,
    0.03627863,
    0.02647047,
    0.06838391,
    0.07216309,
    -0.00809051,
    0.07248835,
    0.0123264,
    -0.09173338,
    -0.02095788,
    0.02871792,
    -0.03392723,
    0.05959549,
    -0.10397915,
    -0.03820326,
    -0.05222115,
    -0.02296818,
    -0.06410559,
    0.02745123,
    0.02334865,
    -0.02446206,
    -0.12417631,
    -0.01871051,
    0.02439541,
    -0.02481432,
    -0.03880155,
    0.04188481,
    0.02300973,
    0.10600527,
    0.02696968,
    0.02788247,
    0.05024018,
    0.05907565,
    0.02856795,
    -0.00740766,
    0.02289764,
    -0.0643627,
    -0.00749485,
    -0.03111451,
    0.06580845,
    0.02102997,
    -0.10717536,
    0.16490568,
    0.03047366,
    -0.02454999,
    0.07184675,
    -0.02504459,
    -0.11541119,
    0.03915355,
    -0.03187835,
    -0.05494586,
    -0.15862629,
    -0.02779816,
    0.00724561,
    0.00901807,
    -0.01519001,
    0.04528573,
    -0.05221211,
    0.01260346,
    -0.01652065,
    0.01324382,
    -0.01688977,
    0.01070876,
    -0.03916383,
    -0.03296183,
    -0.06774635,
    -0.05388693,
    -0.01320887,
    0.07467077,
    0.06863626,
    -0.06439278,
    0.06113409,
    -0.00122581,
    -0.0411741,
    0.11657882,
    -0.01979883,
    -0.01714609,
    -0.00621283,
    0.05906631,
    0.00404663,
    0.02791196,
    -0.11955266,
    -0.0623432,
    -0.12302965,
    0.04749805,
    -0.05722075,
    0.08342554,
    -0.0616898,
    0.0171079,
    0.1030134,
    0.00575187,
    -0.01223959,
    -0.01106031,
    0.02733183,
    -0.05465746,
    -0.00639093,
    0.10582153,
    0.05119603,
    -0.16957831,
    0.0605646,
    0.05737981,
    0.12555394,
    -0.00963913,
    -0.15966235,
    0.06239227,
    -0.01519997,
    -0.00653814,
    -0.01759958,
    -0.00281965,
    -0.07387377,
    0.01542045,
    -0.01574635,
    0.09960862,
    0.06726488,
    0.01381977,
    0.03104461,
    0.05140565,
    -0.08996302,
    0.06713541,
    -0.10765704,
    -0.00975681,
    0.15130819,
    0.0128835,
    -0.00251494,
    -0.02743187,
    0.00955417,
    -0.10639542,
    0.04656886
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:56 GMT",
    "content-type": "application/json",
    "transfer-encoding": "chunked",
    "connection": "close",
    "server": "openresty",
    "vary": "Accept-Encoding",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "86867011415d00b270f98f6c810387fd",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Semantic Vectors REST endpoint is: https://api.rosette.com/rest/v1/semantics/vector

The Semantic Vectors endpoint returns a single vector of floating point numbers for your input, representing the location of the input in semantic space. The length of the input can range from a single word to an entire document. Among other uses, a text vector enables you to calculate the similarity between two documents or two words.

By default, Rosette returns a vector representative of the entire input document, regardless of length. To return a vector for each individual token, add {"options": {"perToken": true}} to your call.

Similar Terms


"use strict";

 var Api = require("../lib/Api");
 var ArgumentParser = require("argparse").ArgumentParser;

 var parser = new ArgumentParser({
   addHelp: true,
   description: "Get the terms similar to an input in other languages"
 });
 parser.addArgument(["--key"], {help: "Rosette API key", required: true});
 parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
 var args = parser.parseArgs();

 var api = new Api(args.key, args.url);
 var endpoint = "similarTerms";
 var similar_terms_data = "spy"
 var options = {"resultLanguages": ["spa", "deu", "jpn"]}

 api.parameters.content = similar_terms_data;
 api.parameters.options = options;
 api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
 });



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class similar_terms
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //similar-terms yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI EmbeddingCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string similar_terms_data = "spy";
                //The results of the API call will come back in the form of a Dictionary
                EmbeddingCAPI.SetOption("resultLanguages", new List<String>() {"spa", "deu", "jpn"});
                SimilarTermsResponse response = EmbeddingCAPI.SimilarTerms(similar_terms_data);
                foreach (KeyValuePair<string, string> h in response.Headers)
                {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }

                Console.WriteLine(response.ContentAsJson);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

similar_terms_data <- "spy"
opts <- list()
opts[["resultLanguages"]] <- list("deu", "spa", "jpn")

parameters <- list()
parameters[["content"]] <- similar_terms_data
parameters[["options"]] <- opts

if (is.na(opt$url)) {
   result <- api(opt$key, "semantics/similar", parameters)
} else {
   result <- api(opt$key, "semantics/similar", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

similar_terms_data = "spy"
begin
  params = DocumentParameters.new(content: similar_terms_data)
  params.rosette_options = { 'resultLanguages' => %w[spa deu jpn] }
  response = rosette_api.get_similar_terms(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.SimilarTermsOptions;
import com.basistech.rosette.apimodel.SimilarTermsResponse;
import com.basistech.util.LanguageCode;
import com.google.common.collect.Lists;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.SIMILAR_TERMS_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class SimilarTermsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new SimilarTermsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String similarTermsData = "spy";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        // When no options, use <?>.
        DocumentRequest<SimilarTermsOptions> request = DocumentRequest.<SimilarTermsOptions>builder()
                .content(similarTermsData)
                .options(SimilarTermsOptions.builder()
                        .resultLanguages(Lists.newArrayList(LanguageCode.SPANISH, LanguageCode.GERMAN, LanguageCode.JAPANESE))
                        .build())
                .build();
        SimilarTermsResponse response = rosetteApi.perform(SIMILAR_TERMS_SERVICE_PATH, request, SimilarTermsResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$similar_terms_data = "spy";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $similar_terms_data;
$params->set('content', $content);
$api->setOption('resultLanguages', array('spa', 'deu', 'jpn'));

try {
    $result = $api->similarTerms($params, false);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#similar-terms

    api.set_option("resultLanguages", ['spa', 'deu', 'jpn'])

    similar_terms_data = "spy"
    params = DocumentParameters()
    params["content"] = similar_terms_data
    try:
        return api.similar_terms(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                             os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "spy", "options": {"resultLanguages": ["spa", "deu", "jpn"]}}' \
    "https://api.rosette.com/rest/v1/semantics/similar"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "similarTerms": {
    "jpn": [
      {
        "term": "スパイ",
        "similarity": 0.5544399
      },
      {
        "term": "諜報",
        "similarity": 0.46903181
      },
      {
        "term": "MI6",
        "similarity": 0.46344957
      },
      {
        "term": "殺し屋",
        "similarity": 0.41098994
      },
      {
        "term": "正体",
        "similarity": 0.40109193
      },
      {
        "term": "プレデター",
        "similarity": 0.39433435
      },
      {
        "term": "レンズマン",
        "similarity": 0.3918637
      },
      {
        "term": "S.H.I.E.L.D.",
        "similarity": 0.38338536
      },
      {
        "term": "サーシャ",
        "similarity": 0.37628397
      },
      {
        "term": "黒幕",
        "similarity": 0.37256041
      }
    ],
    "spa": [
      {
        "term": "espía",
        "similarity": 0.61295485
      },
      {
        "term": "cia",
        "similarity": 0.46201307
      },
      {
        "term": "desertor",
        "similarity": 0.42849663
      },
      {
        "term": "cómplice",
        "similarity": 0.36646274
      },
      {
        "term": "subrepticiamente",
        "similarity": 0.36629659
      },
      {
        "term": "asesino",
        "similarity": 0.36264464
      },
      {
        "term": "misterioso",
        "similarity": 0.35466132
      },
      {
        "term": "fugitivo",
        "similarity": 0.35033143
      },
      {
        "term": "informante",
        "similarity": 0.34707013
      },
      {
        "term": "mercenario",
        "similarity": 0.34658083
      }
    ],
    "deu": [
      {
        "term": "Deckname",
        "similarity": 0.51391315
      },
      {
        "term": "GRU",
        "similarity": 0.50809389
      },
      {
        "term": "Spion",
        "similarity": 0.50051737
      },
      {
        "term": "KGB",
        "similarity": 0.49981388
      },
      {
        "term": "Informant",
        "similarity": 0.48774603
      },
      {
        "term": "Geheimagent",
        "similarity": 0.48700801
      },
      {
        "term": "Geheimdienst",
        "similarity": 0.48512384
      },
      {
        "term": "Spionin",
        "similarity": 0.47224587
      },
      {
        "term": "MI6",
        "similarity": 0.46969846
      },
      {
        "term": "Decknamen",
        "similarity": 0.44730526
      }
    ]
  },
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:56 GMT",
    "content-type": "application/json",
    "transfer-encoding": "chunked",
    "connection": "close",
    "server": "openresty",
    "vary": "Accept-Encoding",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "88fb55f79e6e1165e5068124832aa419",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Similar Terms REST endpoint is: https://api.rosette.com/rest/v1/semantics/similar

Rosette uses text vectors to identify semantically similar terms. By calculating the text vector for a term, Rosette can find similar terms in the semantic space in multiple supported languages. All languages are supported for both input terms and result languages.

To find semantically similar terms with Rosette, provide an input term and one or more result languages to the similar endpoint. By default, the endpoint will return 10 similar terms in each requested language. You can request up to 50 terms for each language. For each returned term, Rosette also returns a similarity value between -1 and 1, where a value closer to 1 indicates a higher degree of similarity.

The desired output languages are supplied with the required resultLanguages option. The statement {“options”: {“resultLanguages”: [“spa”, “jpn”]} returns Spanish and Japanese terms.

To specify the number of terms to return (between 1 and 50), use the count option. For example, to return 20 terms in Spanish and 20 terms in Japanese, add {“options”: {“resultLanguages”: [“spa”, “jpn”], “count”: 20}} to your call.

You can specify the language of your input by including the three-letter language code within your request. If you do not include this field Rosette will automatically detect the language of the input.

Language Support

You can use the GET /semantics/vector/supported-languages and GET /semantics/similar/supported-languages methods to dynamically retrieve the list of supported languages and scripts for the semantic vectors and similar terms endpoints, respectively.

At this time, both endpoints support the same languages.

Language (code)

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Sentence Tagging

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get sentences from a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "sentences";

var sentences_data = "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me.";
var content = sentences_data;

api.parameters.content = content;

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class sentences
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //sentences yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI SentencesCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string sentences_data = @"This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me.";
                //The results of the API call will come back in the form of a Dictionary
                SentenceTaggingResponse response = SentencesCAPI.Sentences(sentences_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

sentences_data <- "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me."

parameters <- list()
parameters[["content"]] <- sentences_data

if (is.na(opt$url)) {
   result <- api(opt$key, "sentences", parameters)
} else {
   result <- api(opt$key, "sentences", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

sentences_data = "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me."

begin
  params = DocumentParameters.new
  params.content = sentences_data
  response = rosette_api.get_sentences(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.SentencesResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.SENTENCES_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class SentencesExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new SentencesExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String sentencesData = "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me.";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        // When no options, use <?>.
        DocumentRequest<?> request = DocumentRequest.builder().content(sentencesData).build();
        SentencesResponse response = rosetteApi.perform(SENTENCES_SERVICE_PATH, request, SentencesResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$sentences_data = "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $sentences_data;
$params->set('content', $content);

try {
    $result = $api->sentences($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    sentences_data = "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me."
    params = DocumentParameters()
    params["content"] = sentences_data

    try:
        return api.sentences(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me." }' \
    "https://api.rosette.com/rest/v1/sentences"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "sentences": [
    "This land is your land. ",
    "This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. ",
    "This land was made for you and Me. ",
    "As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me."
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:55 GMT",
    "content-type": "application/json",
    "content-length": "346",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "8fa31f61ad7cc00ff70f2d418851ea83",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Sentence Tagging REST endpoint is https://api.rosette.com/rest/v1/sentences

Rosette can parse your input and return a list of sentences.

It can identify the start and end of each sentence, even though punctuation may be ambiguous.

Language Support

You can use the GET /sentences/supported-languages method to dynamically retrieve the list of supported languages and scripts for the sentence tagging endpoint.

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Language (code)

Sentiment Analysis

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;
var tmp = require("temporary");

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the sentiment of the text in a local file"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var file = new tmp.File();
var sentiment_file_data = "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>";
var fileContents = sentiment_file_data;

file.writeFileSync(fileContents);

var api = new Api(args.key, args.url);
var endpoint = "sentiment";

api.parameters.documentFile = file.path;
api.parameters.language = "eng";

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class sentiment
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //sentiment yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }

            try
            {
                CAPI SentimentCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                var newFile = Path.GetTempFileName();
                StreamWriter sw = new StreamWriter(newFile);
                string sentiment_file_data = @"<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>";
                sw.WriteLine(sentiment_file_data);
                sw.Flush();
                sw.Close();
                //Rosette API provides File upload options (shown here)
                //Simply create a new RosetteFile using the path to a file
                //The results of the API call will come back in the form of a Dictionary
                SentimentResponse response = SentimentCAPI.Sentiment(new RosetteFile(newFile, @"application/octet-stream", "{\"language\":\"eng\"}"));
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());

                if (File.Exists(newFile)) {
                    File.Delete(newFile);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

sentiment_file_data <- "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>"

parameters <- list()
parameters[["content"]] <- sentiment_file_data
parameters[["documentFile"]] <- "true"

if (is.na(opt$url)) {
   result <- api(opt$key, "sentiment", parameters)
} else {
   result <- api(opt$key, "sentiment", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'tempfile'
require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

file = Tempfile.new(%w[foo .html])
sentiment_file_data = "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>"
file.write(sentiment_file_data)
file.close
begin
  params = DocumentParameters.new(file_path: file.path, language: 'eng')
  response = rosette_api.get_sentiment(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.SentimentOptions;
import com.basistech.rosette.apimodel.SentimentResponse;

import java.io.IOException;
import java.io.InputStream;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.SENTIMENT_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class SentimentExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new SentimentExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        // the temp file substitutes for an actual disk file.
        String sentimentFileData = "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>";
        try (InputStream inputStream = Files.newInputStream(createTempDataFile(sentimentFileData))) {
            HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                    .key(getApiKeyFromSystemProperty())
                    .url(getAltUrlFromSystemProperty())
                    .build();
            //The api object creates an http client, but to provide your own:
            //api.httpClient(CloseableHttpClient)
            // When no options, use <?>.
            DocumentRequest<SentimentOptions> request = DocumentRequest.<SentimentOptions>builder().content(inputStream, "text/html").build();
            SentimentResponse response = rosetteApi.perform(SENTIMENT_SERVICE_PATH, request, SentimentResponse.class);
            System.out.println(responseToJson(response));
        }

    }

    private static Path createTempDataFile(String data) throws IOException {
        Path file = Files.createTempFile("example.", ".html");
        try (Writer writer = Files.newBufferedWriter(file, StandardCharsets.UTF_8)) {
            writer.write(data);
        }
        file.toFile().deleteOnExit();
        return file;
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$sentiment_file_data = "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('language', 'eng');
$content = $sentiment_file_data;
$temp = tmpfile();  // write above html content to a temp file
fwrite($temp, $content);
$params->loadDocumentFile(stream_get_meta_data($temp)['uri']);

try {
    $result = $api->sentiment($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
} finally {
    fclose($temp);  // clean up the temp file
}



import argparse
import json
import os
import tempfile

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create default file to read from
    temp_file = tempfile.NamedTemporaryFile(suffix=".html")
    sentiment_file_data = "<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”</p></body></html>"
    message = sentiment_file_data
    temp_file.write(message if isinstance(message, bytes) else message.encode())
    temp_file.seek(0)

    # Create an API instance
    api = API(user_key=key, service_url=alt_url)
    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#sentiment-analysis

    # api.set_option('modelType','dnn') #Valid for English only

    params = DocumentParameters()
    params["language"] = "eng"

    # Use an HTML file to load data instead of a string
    params.load_document_file(temp_file.name)
    try:
        result = api.sentiment(params)
    except RosetteException as exception:
        print(exception)
    finally:
        # Clean up the file
        temp_file.close()

    return result


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn’t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, “The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy.”" }' \
    "https://api.rosette.com/rest/v1/sentiment"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "document": {
    "label": "pos",
    "confidence": 0.7962072
  },
  "entities": [
    {
      "type": "PERSON",
      "mention": "Original Ghostbuster Dan Aykroyd",
      "normalized": "Original Ghostbuster Dan Aykroyd",
      "count": 2,
      "mentionOffsets": [
        {
          "startOffset": 0,
          "endOffset": 32
        },
        {
          "startOffset": 185,
          "endOffset": 192
        }
      ],
      "entityId": "T0",
      "confidence": 0.44447255,
      "sentiment": {
        "label": "pos",
        "confidence": 0.70096395
      }
    },
    {
      "type": "PRODUCT",
      "mention": "The Hollywood Reporter",
      "normalized": "The Hollywood Reporter",
      "count": 1,
      "mentionOffsets": [
        {
          "startOffset": 156,
          "endOffset": 178
        }
      ],
      "entityId": "Q61503",
      "linkingConfidence": 0.46985524,
      "sentiment": {
        "label": "pos",
        "confidence": 0.49633306
      }
    }
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:55 GMT",
    "content-type": "application/json",
    "content-length": "625",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "141e1a83748b8d2cafd0335897b81d12",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Sentiment REST endpoint is: https://api.rosette.com/rest/v1/sentiment

Rosette analyzes the sentiment (subjective attitude) of the input as positive (pos), negative (neg), or neutral (neu). Given an input, Rosette returns a sentiment label with a confidence score between 0 and 1. The sum of the confidence scores for the three sentiment labels for a given document is always equal to one, though only the highest one is returned.

When Rosette detects entities within your input, it also returns the sentiment for each unique entity in the document. It groups all of the relevant sentiment about that entity into one mention, identified by its entity ID.

Before analyzing, Rosette filters out some stop words and punctuation, such as “the” “?” “a” “it”, to increase the accuracy of the assessment.

When working with English text, there is also an option to use an alternative, deep neural network sentiment model. As this model is new, we do not guarantee its results, but are eager to hear your feedback. To use this model, add this to the body of your call: "options": {"modelType": "DNN"}. The DNN model may return different scores than the standard model.

Language Support

You can use the GET /sentiment/supported-languages method to dynamically retrieve the list of supported languages and scripts for the sentiment endpoint.

Language (code)

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Syntactic Dependencies

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the syntactic dependencies from a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();

var api = new Api(args.key, args.url);
var endpoint = "syntax_dependencies";
var syntax_dependencies_data = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday.";

api.parameters.content = syntax_dependencies_data;
api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class entities
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //entities yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI api = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string syntax_dependencies_data = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday.";
                //The results of the API call will come back in the form of a Dictionary
                SyntaxDependenciesResponse response = api.SyntaxDependencies(syntax_dependencies_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

syntax_dependencies_data <- "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday."

parameters <- list()
parameters[["content"]] <- syntax_dependencies_data

if (is.na(opt$url)) {
   result <- api(opt$key, "syntax/dependencies", parameters)
} else {
   result <- api(opt$key, "syntax/dependencies", parameters,
                 NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

syntax_dependencies_data = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday."

begin
  params = DocumentParameters.new(content: syntax_dependencies_data)
  response = rosette_api.get_syntax_dependencies(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.SyntaxDependenciesResponse;
import com.basistech.rosette.apimodel.DocumentRequest;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.SYNTAX_DEPENDENCIES_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class SyntaxDependenciesExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new SyntaxDependenciesExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String syntaxDependenciesData = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday.";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                                .key(getApiKeyFromSystemProperty())
                                .url(getAltUrlFromSystemProperty())
                                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        DocumentRequest<?> request = DocumentRequest.builder().content(syntaxDependenciesData).build();
        SyntaxDependenciesResponse response = rosetteApi.perform(SYNTAX_DEPENDENCIES_SERVICE_PATH, request, SyntaxDependenciesResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$syntax_dependencies_data = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$content = $syntax_dependencies_data;
$params->set('content', $content);

try {
    $result = $api->syntaxDependencies($params, false);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    syntax_dependencies_data = "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday."
    params = DocumentParameters()
    params["content"] = syntax_dependencies_data
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)
    try:
        return api.syntax_dependencies(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday." }' \
    "https://api.rosette.com/rest/v1/syntax/dependencies"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "sentences": [
    {
      "startTokenIndex": 0,
      "endTokenIndex": 19,
      "dependencies": [
        {
          "dependencyType": "name",
          "governorTokenIndex": 1,
          "dependentTokenIndex": 0
        },
        {
          "dependencyType": "nsubjpass",
          "governorTokenIndex": 9,
          "dependentTokenIndex": 1
        },
        {
          "dependencyType": "punct",
          "governorTokenIndex": 1,
          "dependentTokenIndex": 2
        },
        {
          "dependencyType": "det",
          "governorTokenIndex": 6,
          "dependentTokenIndex": 3
        },
        {
          "dependencyType": "amod",
          "governorTokenIndex": 6,
          "dependentTokenIndex": 4
        },
        {
          "dependencyType": "compound",
          "governorTokenIndex": 6,
          "dependentTokenIndex": 5
        },
        {
          "dependencyType": "appos",
          "governorTokenIndex": 1,
          "dependentTokenIndex": 6
        },
        {
          "dependencyType": "punct",
          "governorTokenIndex": 1,
          "dependentTokenIndex": 7
        },
        {
          "dependencyType": "auxpass",
          "governorTokenIndex": 9,
          "dependentTokenIndex": 8
        },
        {
          "dependencyType": "root",
          "governorTokenIndex": -1,
          "dependentTokenIndex": 9
        },
        {
          "dependencyType": "det",
          "governorTokenIndex": 12,
          "dependentTokenIndex": 10
        },
        {
          "dependencyType": "compound",
          "governorTokenIndex": 12,
          "dependentTokenIndex": 11
        },
        {
          "dependencyType": "dobj",
          "governorTokenIndex": 9,
          "dependentTokenIndex": 12
        },
        {
          "dependencyType": "case",
          "governorTokenIndex": 14,
          "dependentTokenIndex": 13
        },
        {
          "dependencyType": "nmod",
          "governorTokenIndex": 12,
          "dependentTokenIndex": 14
        },
        {
          "dependencyType": "cc",
          "governorTokenIndex": 14,
          "dependentTokenIndex": 15
        },
        {
          "dependencyType": "conj",
          "governorTokenIndex": 14,
          "dependentTokenIndex": 16
        },
        {
          "dependencyType": "case",
          "governorTokenIndex": 18,
          "dependentTokenIndex": 17
        },
        {
          "dependencyType": "nmod",
          "governorTokenIndex": 9,
          "dependentTokenIndex": 18
        },
        {
          "dependencyType": "punct",
          "governorTokenIndex": 9,
          "dependentTokenIndex": 19
        }
      ]
    }
  ],
  "tokens": [
    "Yoshinori",
    "Ohsumi",
    ",",
    "a",
    "Japanese",
    "cell",
    "biologist",
    ",",
    "was",
    "awarded",
    "the",
    "Nobel",
    "Prize",
    "in",
    "Physiology",
    "or",
    "Medicine",
    "on",
    "Monday",
    "."
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:56 GMT",
    "content-type": "application/json",
    "transfer-encoding": "chunked",
    "connection": "close",
    "server": "openresty",
    "vary": "Accept-Encoding",
    "x-rosetteapi-processedlanguage": "eng",
    "x-rosetteapi-request-id": "52d313f9cb90025ce18cb63bc9bdd7a0",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Syntactic Dependencies REST endpoint is: https://api.rosette.com/rest/v1/syntax/dependencies

The rules governing the hierarchical structure of a sentence are called “syntax” in linguistics. Knowing the structure of a sentence helps to understand how the words in a sentence are related to each other. In a sentence like “I don’t like beer”, syntax is what tells us that the verb “like” is what’s negated by “not”. In fact, Rosette’s relationships functionality uses syntax to help understand the relationships between entities in sentences.

Dependency grammars are a specific approach to modelling syntax which identify labeled dependencies, or direct connections, between words rather than intervening structures like a verb phrase or noun phrase. A dependency grammar places the verb as the structural root of the sentence, to which all other dependencies link directly or indirectly.

The /syntax/dependencies endpoint will return the list of tokens, or words, in the input sentence, as well as the labeled directed links each token has to another token in the sentence. The indices correspond to the list of tokens within the results; the list of tokens returned from Rosette’s /tokens endpoint may vary.

Language Support

You can use the GET /dependencies/supported-languages method to dynamically retrieve the list of supported languages and scripts for the syntactic dependencies endpoint.

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Language (code)

Tokenization

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the words in a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "tokens";

var tokens_data = "北京大学生物系主任办公室内部会议";
var content = tokens_data;
api.parameters.content = content;

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class tokens
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //tokens yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI TokensCAPI = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string tokens_data = @"北京大学生物系主任办公室内部会议";
                //The results of the API call will come back in the form of a Dictionary
                TokenizationResponse response = TokensCAPI.Tokens(tokens_data, null, "sentence", null);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

tokens_data <- "北京大学生物系主任办公室内部会议"

parameters <- list()
parameters[["content"]] <- tokens_data

if (is.na(opt$url)) {
   result <- api(opt$key, "tokens", parameters)
} else {
   result <- api(opt$key, "tokens", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

tokens_data = "北京大学生物系主任办公室内部会议"
begin
  params = DocumentParameters.new(content: tokens_data)
  response = rosette_api.get_tokens(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.TokensResponse;

import java.io.IOException;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.TOKENS_SERVICE_PATH;

@SuppressWarnings({"java:S1166", "java:S2221", "java:S106"})
public final class TokensExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new TokensExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws IOException {
        String tokensData = "北京大学生物系主任办公室内部会议";

        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        //The api object creates an http client, but to provide your own:
        //api.httpClient(CloseableHttpClient)
        // When no options, use <?>.
        DocumentRequest<?> request = DocumentRequest.builder().content(tokensData).build();
        TokensResponse response = rosetteApi.perform(TOKENS_SERVICE_PATH, request, TokensResponse.class);
        System.out.println(responseToJson(response));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$tokens_data = "北京大学生物系主任办公室内部会议";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $tokens_data);

try {
    $result = $api->tokens($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#tokenization

    # api.set_option('modelType','perceptron') #Valid for Chinese and Japanese only

    tokens_data = "北京大学生物系主任办公室内部会议"
    params = DocumentParameters()
    params["content"] = tokens_data
    try:
        return api.tokens(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "北京大学生物系主任办公室内部会议"}' \
    "https://api.rosette.com/rest/v1/tokens"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "tokens": [
    "北京大学",
    "生物",
    "系主任",
    "办公室",
    "内部",
    "会议"
  ],
  "responseHeaders": {
    "date": "Mon, 27 Mar 2023 12:44:57 GMT",
    "content-type": "application/json",
    "content-length": "78",
    "connection": "close",
    "server": "openresty",
    "x-rosetteapi-processedlanguage": "zho",
    "x-rosetteapi-request-id": "942fe324dbf35ab5ce44a6c763e4eb03",
    "strict-transport-security": "max-age=63072000; includeSubDomains; preload",
    "x-rosetteapi-app-id": "1409611464116",
    "x-rosetteapi-concurrency": "5"
  }
}

The Tokenization REST endpoint is: https://api.rosette.com/rest/v1/tokens

Rosette identifies and separates each word into one or more tokens through advanced statistical modeling. A token is an atomic element such as a word, number, possessive affix, or punctuation.

The resulting token output minimizes index size, enhances search accuracy, and increases relevancy.

We offer two algorithms for Chinese and Japanese tokenization and morphological analysis. Prior to August 2018, the default algorithm was a perceptron. To return to that algorithm, add this to the body of your call:

"options": {"modelType": "perceptron"}

Language Support

You can use the GET /tokens/supported-languages method to dynamically retrieve the list of supported languages and scripts for the tokenization endpoint.

You can specify the language of your input with the three-letter language code. If you do not specify the language then Rosette automatically detects it.

Language (code)

Topic Extraction

Introduction


"use strict";

var Api = require("../lib/Api");
var ArgumentParser = require("argparse").ArgumentParser;

var parser = new ArgumentParser({
  addHelp: true,
  description: "Get the key phrases and concepts in a piece of text"
});
parser.addArgument(["--key"], {help: "Rosette API key", required: true});
parser.addArgument(["--url"], {help: "Rosette API alt-url", required: false});
var args = parser.parseArgs();
var api = new Api(args.key, args.url);
var endpoint = "topics";

var topics_data = "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project."
var content = topics_data;
api.parameters.content = content;

api.rosette(endpoint, function(err, res){
    if(err){
        console.log(err);
    } else {
        console.log(JSON.stringify(res, null, 2));
    }
});



using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Web.Script.Serialization;
using rosette_api;

namespace rosette_apiExamples
{
    class topics
    {
        static void Main(string[] args)
        {
            //To use the C# API, you must provide an API key
            string apikey = "Your API key";
            string alturl = string.Empty;

            //You may set the API key via command line argument:
            //tokens yourapikeyhere
            if (args.Length != 0)
            {
                apikey = args[0];
                alturl = args.Length > 1 ? args[1] : string.Empty;
            }
            try
            {
                CAPI api = string.IsNullOrEmpty(alturl) ? new CAPI(apikey) : new CAPI(apikey, alturl);
                string topics_data = @"Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project.";
                //The results of the API call will come back in the form of a Dictionary
                TopicsResponse response = api.Topics(content: topics_data);
                foreach (KeyValuePair<string, string> h in response.Headers) {
                    Console.WriteLine(string.Format("{0}:{1}", h.Key, h.Value));
                }
                Console.WriteLine(response.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}



source("../R/Api.R")
library(jsonlite)
library(optparse)

option_list <- list(
  make_option(c("-k", "--key"),
    action = "store", default = NA, type = "character",
    help = "Rosette API key"),
  make_option(c("-u", "--url"),
    action = "store", default = NA, type = "character",
    help = "Rosette API url"))
opt_parser <- OptionParser(option_list = option_list)
opt <- parse_args(opt_parser)

topics_data <- "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project."

parameters <- list()
parameters[["content"]] <- topics_data

if (is.na(opt$url)) {
   result <- api(opt$key, "topics", parameters)
} else {
   result <- api(opt$key, "topics", parameters, NULL, NULL, opt$url)
}
print(jsonlite::toJSON(result$header, pretty = TRUE))
print(jsonlite::toJSON(result$content, pretty = TRUE))



# frozen_string_literal: true

require 'rosette_api'

api_key, url = ARGV

rosette_api = if url
                RosetteAPI.new(api_key, url)
              else
                RosetteAPI.new(api_key)
              end

topics_data = "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project."

begin
  params = DocumentParameters.new(content: topics_data)
  response = rosette_api.get_topics(params)
  puts JSON.pretty_generate(response)
rescue RosetteAPIError => e
  printf('Rosette API Error (%<status_code>s): %<message>s',
         status_code: e.status_code,
         message: e.message)
end



package com.basistech.rosette.examples;

import com.basistech.rosette.api.HttpRosetteAPI;
import com.basistech.rosette.apimodel.DocumentRequest;
import com.basistech.rosette.apimodel.TopicsOptions;
import com.basistech.rosette.apimodel.TopicsResponse;
import com.basistech.util.LanguageCode;

import static com.basistech.rosette.api.common.AbstractRosetteAPI.TOPICS_SERVICE_PATH;

public class TopicsExample extends ExampleBase {
    public static void main(String[] args) {
        try {
            new TopicsExample().run();
        } catch (Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    private void run() throws Exception {
        String topicsData = "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project.";
        HttpRosetteAPI rosetteApi = new HttpRosetteAPI.Builder()
                .key(getApiKeyFromSystemProperty())
                .url(getAltUrlFromSystemProperty())
                .build();
        DocumentRequest<TopicsOptions> request = DocumentRequest.<TopicsOptions>builder()
                .language(LanguageCode.ENGLISH)
                .content(topicsData)
                .build();
        TopicsResponse resp = rosetteApi.perform(TOPICS_SERVICE_PATH, request, TopicsResponse.class);
        System.out.println(responseToJson(resp));
    }
}



<?php

require_once dirname(__FILE__) . '/../vendor/autoload.php';
use rosette\api\Api;
use rosette\api\DocumentParameters;
use rosette\api\RosetteConstants;
use rosette\api\RosetteException;

$options = getopt(null, array('key:', 'url::'));
if (!isset($options['key'])) {
    echo 'Usage: php ' . __FILE__ . " --key <api_key> --url=<alternate_url>\n";
    exit();
}
$topics_data = "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project.";
$api = isset($options['url']) ? new Api($options['key'], $options['url']) : new Api($options['key']);
$params = new DocumentParameters();
$params->set('content', $topics_data);

try {
    $result = $api->topics($params);
    var_dump($result);
} catch (RosetteException $e) {
    error_log($e);
}



import argparse
import json
import os

from rosette.api import API, DocumentParameters, RosetteException


def run(key, alt_url='https://api.rosette.com/rest/v1/'):
    """ Run the example """
    # Create an API instance
    api = API(user_key=key, service_url=alt_url)

    # Set selected API options.
    # For more information on the functionality of these
    # and other available options, see Rosette Features & Functions
    # https://developer.rosette.com/features-and-functions#topic-extraction

    # api.set_option('keyphraseSalienceThreshold','.5')
    # api.set_option('conceptSalienceThreshold','.1')

    topics_data = "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight's J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project."
    params = DocumentParameters()
    params["content"] = topics_data
    try:
        return api.topics(params)
    except RosetteException as exception:
        print(exception)


PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
                                 description='Calls the ' +
                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
PARSER.add_argument('-u', '--url', help="Alternative API URL",
                    default='https://api.rosette.com/rest/v1/')

if __name__ == '__main__':
    ARGS = PARSER.parse_args()
    RESULT = run(ARGS.key, ARGS.url)
    print(RESULT)



curl -s -X POST \
    -H "X-RosetteAPI-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Cache-Control: no-cache" \
    -d '{"content": "Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight\u0027s J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project."}' \
    "https://api.rosette.com/rest/v1/topics"

The example above returns a language specific data structure that represents the following JSON from Rosette


{
  "keyphrases": [
    {
      "phrase": "J.R.R. Tolkien biopic Tolkien",
      "salience": 1.0
    },
    {
      "phrase": "Lily Collins",
      "salience": 0.52003408
    },
    {
      "phrase": "Chernin Entertainment",
      "salience": 0.38167696
    },
    {
      "phrase": "famed author",
      "salience": 0.37297132
    },
    {
      "phrase": "Scorpius Malfoy",
      "salience": 0.63209603
    },
    {
      "phrase": "Dome Karukoski",
      "salience": 0.61936971
    },
    {
      "phrase": "British play Harry Potter",
      "salience": 0.44406311
    },
    {
      "phrase": "Nicholas Hoult",
      "salience": 0.81107516
    }
  ],
  "concepts": [
    {
      "phrase": "Fantasy",
      "salience": 0.18614235,
      "conceptId": "Q7151195"
    },
    {
      "phrase": "Harry Potter and the Cursed Child",
      "salience": 0.1458407,
      "conceptId": "Q20711488"
    },
    {
      "phrase": "Literature",
      "salience": 0.14539019,
      "conceptId": "Q8259"
    },
    {
      "phrase": "Media franchises",
      "salience": 0.14506509,
      "conceptId": "Q6430929"
    },
    {
      "phrase": "English culture",
      "salience": 0.12982228,
      "conceptId": "Q7151900"
    },
    {
      "phrase": "Works based on works",
      "salience": 0.12405845,
      "conceptId": "Q9402597"
    },
    {
      "phrase": "Hobbit",
      "salience": 0.11799788,
      "conceptId": "Q74359"
    },
    {
      "phrase": "Harry Potter",
      "salience": 0.11380053,
      "conceptId": "Q8337"
    },
    {
      "phrase": "Nicholas Hoult",
      "salience": 0.1134257,
      "conceptId": "Q298347"
    },
    {
      "phrase": "The Hobbit",
      "salience": 0.11231594,
      "conceptId": "Q9890290"
    },
    {
      "phrase": "Series",
      "salience": 0.10957315,
      "conceptId": "Q7034355"
    },
    {
      "phrase": "Fantasy novels",
      "salience": 0.1094