NER (Named Entity Recognition) API Documentation

Description:

This API allows you to extract named entities from text input. Below, you'll find comprehensive guidance on how to use this API effectively.

Endpoint: https://kafkai.io/api/v1.0/ner-api/

Authentication

To access the NER API, you need to include your API token in the headers of your requests.

Headers:

• Authorization (string): Set this header to include your API token in the following format: Token <your_api_key>.

Example:

curl -X POST "https://kafkai.io/api/v1.0/ner-api/" -d "source_text=John Mikel is a software engineer at XYZ labs Corporation." 
-H "Authorization: Token <your_api_key>"

Input and Output

POST Method (Create NER Data)

Input: To initiate a named entity recognition, send a POST request with the following parameter:

• source_text (string): The text you want to analyze.

Output: Upon a successful request, the API will respond with the following details:

• uid (string): A unique identifier for the NER data entry.
• time (timestamp): The timestamp when the NER data entry was created.
• source_text (string): The input text you provided.
• output_data (object): A dictionary containing the extracted named entity data.
• meta_data (object): A dictionary containing metadata related to the NER results.

Notes:

• The POST method is used to create new NER data.
• You provide input parameters like source_text.
• The API returns a response containing details of the named entity recognition.

GET Method (Retrieve NER Data)

Input: To access existing NER data, submit a GET request with the uid parameter specifying the unique ID of the NER data entry you want to retrieve.

Output: The API will provide the following information:

• uid (string): The unique ID of the NER data entry.
• time (timestamp): The timestamp when the NER data entry was created.
• source_text (string): The source text.
• output_data (object): A dictionary containing the extracted named entity data.
• meta_data (object): A dictionary containing metadata related to the NER results.

Notes:

• The GET method is used to retrieve existing NER data.
• You provide the uid parameter to specify which NER data entry to retrieve.
• The API responds with detailed information about the requested NER data.

Practical Examples

Creating New NER Data (POST Method)

Scenario 1: Analyze the text "John Mikel is a software engineer at XYZ labs Corporation."

Using CURL:

curl -X POST "https://kafkai.io/api/v1.0/ner-api/" 
    -d "source_text=John Mikel is a software engineer at XYZ labs Corporation." -H "Authorization: Token <your_api_key>"

Expected Result (JSON Response):

{
    "uid": "ab337bc4-00fb-47d6-af20-b6e02de86116",
    "time": "2023-09-28T12:00:00Z",
    "source_text": "John Mikel is a software engineer at XYZ labs Corporation.",
    "output_data": {
        "PERSON": ["John Mikel"],
        "ORG": ["XYZ labs Corp"]
    },
    "meta_data": {
        "model_version": "v1.0"
    }
}

Using Python (requests library):

import requests

data = {
    'source_text': 'John Mikel is a software engineer at XYZ labs Corporation.'
}

headers = {
    'Authorization': 'Token <your_api_key>'
}

response = requests.post('https://kafkai.io/api/v1.0/ner-api/', data=data, headers=headers)
print(response.json())

Notes:

• In this scenario, we analyze a specific text.
• The CURL command and Python script send a POST request to create NER data with the API token included in the headers.

Scenario 2: Analyze the text "Stella works at Micro Ltd."

Using CURL:

curl -X POST "https://kafkai.io/api/v1.0/ner-api/" -d "source_text=Stella works at Micro Ltd." -H "Authorization: Token <your_api_key>"

Expected Result (JSON Response):

{
    "uid": "c7f511b0-7e56-4a20-a112-1906e0e91d14",
    "time": "2023-09-28T12:00:00Z",
    "source_text": "Stella works at Micro Ltd.",
    "output_data": {
        "PERSON": ["Stella"],
        "ORG": ["Micro Ltd."]
    },
    "meta_data": {
        "model_version": "v1.0"
    }
}

Using Python (requests library):

import requests

data = {
    'source_text': 'Stella works at Micro Ltd.'
}

headers = {
    'Authorization': 'Token <your_api_key>'
}

response = requests.post('https://kafkai.io/api/v1.0/ner-api/', data=data, headers=headers)
print(response.json())

Notes:

• In this scenario, we analyze a different text.
• The CURL command and Python script send a POST request to create NER data with the API token included in the headers.

Retrieving Existing NER Data (GET Method)

Scenario: Retrieve NER data with a known uid.

Using CURL:

curl "https://kafkai.io/api/v1.0/ner-api/?uid=ab337bc4-00fb-47d6-af20-b6e02de86116" -H "Authorization: Token <your_api_key>"

Expected Result (JSON Response):

{
    "uid": "ab337bc4-00fb-47d6-af20-b6e02de86116",
    "time": "2023-09-28T12:00:00Z",
    "source_text": "John Mikel is a software engineer at XYZ labs Corporation",
    "output_data": {
        "PERSON": ["John Mikel"],
        "ORG": ["XYZ labs Corp"]
    },
    "meta_data": {
        "model_version": "v1.0"
    }
}

Using Python (requests library):

import requests

headers =

 {
    'Authorization': 'Token <your_api_key>'
}

response = requests.get('https://kafkai.io/api/v1.0/ner-api/?uid=ab337bc4-00fb-47d6-af20-b6e02de86116', headers=headers)
print(response.json())

Notes:

• In these examples, we retrieve NER data with a known uid.
• The CURL command and Python script send a GET request to access the NER data with the API token included in the headers.

---