Skip to content

Detectors

Introduction

A detector is an API software module that carries out information detection on a text.

In the API REST interface, the detector name is used to identity information detection resources.

Several information detection resources can exist for the same detector, each supporting a different language. The complete endpoint of an information detection resource must thus contain both the detector name and the language.

To date, the API exposes information detection resources for the pii detector.
The table below shows the supported languages.

Detector name English Spanish French German Italian
pii

To discover available detectors and the language they support, the API provides a self-documentation resource.

pii detector

The pii detector is capable of identifying personal data also knwon as personally identifiable information (PII) and return them together with their positions in the text as linked data in JSON-LD format (see also https://json-ld.org/).

The detector's output allows you to determine if a document contains potentially sensitive data and possibly create a new version of the text in which the PII is de-identified.

These are the information types pii cat detect:

Information type Notes
Personal attributes Of a real person or a fictional character
Postal address
Bank account
IP address
E-mail address
URL
Financial product Credit or debit card
Phone number

These are the properties of each information type:

Information type Property Linked data reference
Personal attributes
Full name of the person https://schema.org/Person
First name https://schema.org/givenName
Last name https://schema.org/familyName
Age https://schema.org/Number
Gender https://schema.org/gender
Nationality https://schema.org/nationality
Date of birth https://schema.org/birthDate
Place of birth https://schema.org/birthPlace
Date of death https://schema.org/deathDate
Place of death https://schema.org/deathPlace
Any date or a time related to the person https://schema.org/Date
Postal address
Full address https://schema.org/Text
Street name and house number https://schema.org/streetAddress
Country https://schema.org/addressCountry
Postal code https://schema.org/postalCode
Locality https://schema.org/addressLocality
Region https://schema.org/addressRegion
PO box number https://schema.org/postOfficeBoxNumber
Bank account
IBAN code https://schema.org/PropertyValue
IBAN code country https://schema.org/Country
IP address
Address https://schema.org/Text
E-mail address
Address https://schema.org/email
URL
URL https://schema.org/URL
Financial product
Number of the credit/debit card https://schema.org/Text
Card Verification Value (CVV) or Card Verification Code (CVC) https://schema.org/Number
Card expiration date https://schema.org/Date
Phone number
Number https://schema.org/telephone

For more information read about the description of the output.

Tip

To play with the JSON-LD object and get ideas for its possible uses, take a look at the JSON-LD playground site, where you can paste the JSON-LD object returned by the pii detector.

Self-documentation resource

The API provides a self-documentation resource to discover available detectors and their features. It has this path:

detectors

Therefore, the complete URL is:

https://nlapi.expert.ai/v2/detectors

It must be requested with the GET method.
It returns the list of available detectors along with the supported languages—as in the above table.

In the reference section of this manual you will find all the information you need to get detectors information using the API's RESTful interface, specifically:

Even if you use the API through a client that hides the REST interface, whether it is made by you or offered by expert.ai, the last piece of information is useful as it helps understand the data returned by the API.

Here is an example of getting detectors information:

This example is based on the Python client you can find on GitHub.

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 list of taxonomies with the language they support.

from expertai.nlapi.cloud.client import ExpertAiClient
client = ExpertAiClient()

output = client.detectors()

# Detectors

print("Detectors:\n")

for detector in output.detectors:
    print(detector.name)
    print("\tLanguages:")
    for language in detector.languages:
        print("\t\t{}".format(language.code))
    print("\tContract: {}".format(detector.contract))

This example is based on the Java client you can find on GitHub.

The client gets user credentials from two environment variables:

EAI_USERNAME
EAI_PASSWORD

Set those variables with you 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.message.TaxonomiesResponse;
import ai.expert.nlapi.v2.InfoAPI;
import ai.expert.nlapi.v2.InfoAPIConfig;

public class Main {

    public static Authentication createAuthentication() throws Exception {
        DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider();
        Authenticator authenticator = new BasicAuthenticator(credentialsProvider);
        return new Authentication(authenticator);
    }

    public static void main(String[] args) {
        try {
            InfoAPI infoAPI = new InfoAPI(InfoAPIConfig.builder()
               .withAuthentication(createAuthentication())
               .withVersion(API.Versions.V2)
               .build());

            TaxonomiesResponse taxonomies = infoAPI.getTaxonomies();
            taxonomies.prettyPrint();
        }
        catch(Exception ex) {
            ex.printStackTrace();
        }
    }
}

The following curl command gets the taxonomies documentation resource of the API's REST interface.
Run the command from a shell after replacing token with the actual authorization token.

curl -X GET https://nlapi.expert.ai/v2/taxonomies \
    -H 'Authorization: Bearer token'

The server returns a JSON object.

The following curl command gets the detectors documentation 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 GET https://nlapi.expert.ai/v2/detectors -H "Authorization: Bearer token"

The server returns a JSON object.