Information detection
Detection and detectors
Information detection identifies and extracts information from a text.
The software modules performing information detection are called detectors.
Available detectors are:
Detector name | English | Spanish | French | German | Italian |
---|---|---|---|---|---|
pii |
✔ | ✔ | |||
writeprint |
✔ | ✔ | ✔ | ✔ | ✔ |
temporal-information |
✔ | ✔ | ✔ | ✔ | ✔ |
esg-sentiment |
✔ | ||||
hate-speech |
✔ | ||||
sentiment |
✔ |
Detectors' API resources have paths like:
detect/detector name/language code
Boxed parts are placeholders, so for example:
https://nlapi.expert.ai/v2/detect/pii/en
is the URL of the pii
detector resource performing PII detection on an English text.
These resources must be requested with the POST
method, submitting the text in which to detect information.
In the reference section of this manual you will find all the information you need to perform information detection using the API's RESTful interface, specifically:
- The format of the request to be submitted to the resources.
- How to build resources' paths and full endpoints.
- The output format.
Note
Even if you consume the API through a ready-to-use client that hides low-level requests and responses, knowing the output format helps you understand and navigate the results.
Here is an example of PII detection on a short English text:
This example code uses expertai-nlapi, the open-source Python client corresponding to the nlapi-python GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program detects Personally Identifiable Information (PII) in a short English text and prints the portion of the output containing results in JSON-LD format.
import json
from expertai.nlapi.cloud.client import ExpertAiClient
client = ExpertAiClient()
text = "Michael Jordan was one of the best basketball players of all time. Scoring was Jordan's stand-out skill, but he still holds a defensive NBA record, with eight steals in a half."
detector = 'pii'
language= 'en'
output = client.detection(body={"document": {"text": text}}, params={'detector': detector, 'language': language})
# Output extra data containing the JSON-LD object
print("extra_data: ",json.dumps(output.extra_data, indent=4, sort_keys=True))
This example code uses @expertai/nlapi, the open-source NodeJS client corresponding to the nlapi-nodejs GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program detects Personally Identifiable Information (PII) in a short English text and prints the portion of the output containing results in JSON-LD format.
import {NLClient} from "@expertai/nlapi";
import {Language} from "@expertai/nlapi";
var nlClient = new NLClient();
var text = "Michael Jordan was one of the best basketball players of all time. Scoring was Jordan's stand-out skill, but he still holds a defensive NBA record, with eight steals in a half.";
nlClient.detect(text, {
language: Language.EN,
detector: "pii"
}).then((result) => {
console.log(result.data.extraData["JSON-LD"])
})
This example code uses nlapi-java-sdk, the open-source Java client corresponding to the nlapi-java GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the JSON response.
import ai.expert.nlapi.security.Authentication;
import ai.expert.nlapi.security.Authenticator;
import ai.expert.nlapi.security.BasicAuthenticator;
import ai.expert.nlapi.security.DefaultCredentialsProvider;
import ai.expert.nlapi.v2.API;
import ai.expert.nlapi.v2.cloud.Detector;
import ai.expert.nlapi.v2.cloud.DetectorConfig;
import ai.expert.nlapi.v2.message.DetectResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
public class Main {
public static Authentication createAuthentication() throws Exception {
DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider();
Authenticator authenticator = new BasicAuthenticator(credentialsProvider);
return new Authentication(authenticator);
}
public static Detector createDetector() throws Exception {
return new Detector(DetectorConfig.builder()
.withVersion(API.Versions.V2)
.withDetector("pii")
.withLanguage(API.Languages.en)
.withAuthentication(createAuthentication())
.build());
}
public static void main(String[] args) {
try {
String text = "Michael Jordan was one of the best basketball players of all time. Scoring was Jordan's stand-out skill, but he still holds a defensive NBA record, with eight steals in a half.";
Detector detector = createDetector();
DetectResponse detection = detector.detect(text);
// Output the JSON-LD object contained in the response
System.out.println("JSON-LD output:");
Object jsonLd = detection.getData().getExtraData().get("JSON-LD");
System.out.println(new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(jsonLd));
}
catch(Exception ex) {
ex.printStackTrace();
}
}
}
The following curl command posts a document to the Personally Identifiable Information (PII) detection resource of the API's REST interface.
Run the command from a shell after replacing token
with the actual authorization token.
curl -X POST https://nlapi.expert.ai/v2/detect/pii/en \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"document": {
"text": "Michael Jordan was one of the best basketball players of all time. Scoring was Jordan'\''s stand-out skill, but he still holds a defensive NBA record, with eight steals in a half."
}
}'
The server returns a JSON object.
The following curl command posts a document to the Personally Identifiable Information (PII) detection resource of the API's REST interface.
Open a command prompt in the folder where you installed curl and run the command after replacing token
with the actual authorization token.
curl -X POST https://nlapi.expert.ai/v2/detect/pii/en -H "Authorization: Bearer token" -H "Content-Type: application/json; charset=utf-8" -d "{\"document\": {\"text\": \"Michael Jordan was one of the best basketball players of all time. Scoring was Jordan's stand-out skill, but he still holds a defensive NBA record, with eight steals in a half.\"}}"
The server returns a JSON object.
The following articles describe the capabilities of the available detectors.
Self-documentation resource
The API provides a self-documentation resource to programmatically discover available detectors and their features. Learn more about this resource in the dedicated article.