API Documentation

The API is synchronous and offers a rapid, easy-to-integrate solution for processing text data. There is only one endpoint, which is described below. `POST: /linguistics/interpret-text`

Request Body

``` { "analysisInput": { "documents": [ { "id": "1", "language": "en", "text": "Jane Doe, a Marketing Manager at Global Tech Solutions, resides at 123 Elm Street, New York, NY 10001. Her contact information includes jane.doe@globaltech.com and +1-212-555-6789. On July 10, 2024, she attended the International Marketing Conference at the Hilton New York." } ] } } ```

Request Body Field Description

- **AnalysisInput:** An object containing document array (Batch). Each document contains: - **id:** Unique identifier for tracking results otherwise you will get 400 error. - **language:** Language code of the text (e.g., "en" for English). Check Below table for supported Language and code. - **text:** The content to be analyzed.

Response Example (200 OK) & Description

``` { "documents": [ { "id": "1", "entities": [ { "text": "Jane Doe", "category": "Person", "type": "Person", "offset": 0, "length": 8, "confidenceScore": 1.0, "tags": [ { "name": "Person", "confidenceScore": 1.0 } ] }, { "text": "Marketing Manager", "category": "PersonType", "type": "PersonType", "offset": 12, "length": 17, "confidenceScore": 0.84, "tags": [ { "name": "PersonType", "confidenceScore": 0.84 } ] }, { "text": "Global Tech Solutions", "category": "Organization", "type": "Organization", "offset": 33, "length": 21, "confidenceScore": 1.0, "tags": [ { "name": "Organization", "confidenceScore": 1.0 } ] }, { "text": "123 Elm Street, New York, NY 10001", "category": "Address", "type": "Address", "offset": 67, "length": 34, "confidenceScore": 1.0, "tags": [ { "name": "Address", "confidenceScore": 1.0 } ] }, { "text": "jane.doe@globaltech.com", "category": "Email", "type": "Email", "offset": 136, "length": 23, "confidenceScore": 0.8, "tags": [ { "name": "Email", "confidenceScore": 0.8 } ] }, { "text": "+1-212-555-6789", "category": "PhoneNumber", "type": "PhoneNumber", "offset": 164, "length": 15, "confidenceScore": 0.8, "tags": [ { "name": "PhoneNumber", "confidenceScore": 0.8 } ] }, { "text": "July 10, 2024", "category": "Temporal", "type": "Date", "offset": 184, "length": 13, "confidenceScore": 1.0, "tags": [ { "name": "Date", "confidenceScore": 1.0 }, { "name": "Temporal", "confidenceScore": 1.0 } ], "metadata": { "metadataKind": "DateMetadata", "dateValues": [ { "timex": "2024-07-10", "value": "2024-07-10" } ] } }, { "text": "International Marketing Conference", "category": "Event", "type": "Event", "offset": 216, "length": 34, "confidenceScore": 0.99, "tags": [ { "name": "Event", "confidenceScore": 0.99 } ] }, { "text": "Hilton New York", "category": "Location", "type": "Location", "offset": 258, "length": 15, "confidenceScore": 0.9, "tags": [ { "name": "Location", "confidenceScore": 0.9 } ] } ], "warnings": [] } ], "errors": [], "modelVersion": "2023-09-01" } ```

Response Breakdown

This is an example of the **Named Entity Recognition (NER) API** response. The key fields include the identified entities, their categories, types, confidence scores, and other metadata. - **documents**: An array of processed text results. Each document contains: - **id**: The unique identification for the input request. - **entities**: A listing of recognized entities with the following properties: - **text**: The specific text identified as an entity (e.g., "Jane Doe"). - **category**: The general category of the entity (e.g., "Person", "Organization", "Address"). - **type**: A more specific classification of the entity within its category. (Sub-Category) - **offset**: The position of the entity within the original text. - **length**: The number of characters in the identified entity. - **confidenceScore**: A confidence value (0 to 1) indicating the certainty of the entity classification. (Below 0.5 not good.) - **tags**: Additional labels for the entity with their own confidence scores. - **metadata** (Optional): Includes extra information for certain categories like dates (e.g., **timex** for standardized date formats). - **warnings**: Any difficulties found throughout the entity extraction procedure (empty in this case). - **errors**: Lists any errors encountered when processing the request (empty in this case).

API Constraints

- **Document Size:** Each document may include up to 5,000 characters. - **Document Processing Capacity:** Each request can process up to ten document batch.

API Constraints Error Response Examples.

1. The response indicates that request was too big to process for one of your documents. It went up to 5120 characters which is a limitation. Please note that if other documents in batch satisfy the constraint they will be processed. ``` { "documents": [], "errors": [ { "id": "11", "error": { "code": "InvalidArgument", "message": "Invalid Document in request.", "innererror": { "code": "InvalidDocument", "message": "A document within the request was too large to be processed. Limit document size to: 5120 text elements. For additional details on the data limitations." } } } ], "modelVersion": "2023-09-01" } ``` 2. This error is to let you know that maximum document in batch request cannot be more than 10. This can be corrected by making sure that you request no more than 10 documents per batch. ``` { "error": { "code": "InvalidRequest", "message": "Invalid Document in request.", "innererror": { "code": "InvalidDocumentBatch", "message": "Batch request contains too many records. Max 10 records are permitted." } } } ```

Comprehensive Overview of Prebuilt Entities

Entity Types	Entity Sub-Types	Description	Supported Languages
Person	N/A	Names of individuals.	ar, cs, da, nl, en, fi, fr, de, he, hu, it, ja, ko, no, pl, pt-br, pt-pt, ru, es, sv, tr
Person Type	N/A	Job titles or roles of individuals.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Location	Geopolitical (Cities, states), Structural (Man-made structures), Geographical (Natural features)	Natural and man-made landmarks, structures, and geographical features.	ar, cs, da, nl, en, fi, fr, de, he, hu, it, ja, ko, no, pl, pt-br, pt-pt, ru, es, sv, tr
Organization	Medical, Stock exchange, Sports	Companies, political groups, bands, sport clubs, etc.	ar, cs, da, nl, en, fi, fr, de, he, hu, it, ja, ko, no, pl, pt-br, pt-pt, ru, es, sv, tr
Event	Cultural, Natural, Sports	Historical, social, and natural occurrences.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Product	Computing products	Physical objects across various categories.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Skill	N/A	Abilities, expertise, or proficiency.	en, es, fr, de, it, pt-pt, pt-br
Address	N/A	Complete mailing address.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Phone Number	N/A	Telephone numbers (US and EU only).	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Email	N/A	Email addresses.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
URL	N/A	URLs to websites.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
IP	N/A	Network IP addresses.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
DateTime	Date, Time, DateRange, TimeRange, Duration, Set	Dates and times of day.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br
Quantity	Number, Percentage, Ordinal numbers, Age, Currency, Dimensions, Temperature	Numeric values and quantities.	en, es, fr, de, it, zh-hans, ja, ko, pt-pt, pt-br

## Use Cases Across Indutries - **Healthcare:** Named Entity Extractor enhances patient data extraction through entity tagging of **names**, **addresses**, and **medical institutions** in health records. - **Financial Services:** This improves and accelerates the searching of documents related to transactions, client names, and financial institutions in finance. It enables to automate the audit workflow by reading financial dates and **amounts. - **Legal:** NER help law firms in reducing time and effort by auto-tagging the **legal entities** such as **dates**, **names** & **organizations**. - **Media and Publishing:** It provides for the curation of content related to **named entities** (like **people**, **events**, and **organizations**), making it easier to find relevant articles. - **Real Estate:** Address & Geography extraction to search and classify addresses along with property type. Client Details Extraction helps in the easy management of properties from a list. - **Human Resources:** The HR application helps parse resumes by quickly pulling out relevant information such as **candidate names**, **skills**, and **job titles**. - **Customer Support and Analytics:** It extracts important information like **names**, **email addresses**, **phone numbers**, **company names**, or **locations** from unstructured text such as **customer emails**, **chat logs**, and **support tickets**. Identifying these entities helps in automation for creating the support tickets through NER.

Final Note

This doc cover all major features and scenarios. If you have any feedback, don't hesitate to reach out. For custom requirements, we have private plans with dedicated endpoints. *Thanks, and happy coding!*