# Named Entity Recognition API

## API Server

[nlu-api.allganize.ai](https://nlu-api.allganize.ai) is Allganize's NLU API endpoint. If you are using on-prem, please use your API endpoint.

## **Getting API KEY**

The NLU API uses API keys to authenticate requests that you can find in the [Allganize NLU API dashboard](https://nlu.allganize.ai/projects). Go to Settings > General to find your API key. If you don't have an account yet, you can create one [here](https://nlu.allganize.ai/signup).

####  Provide your `API KEY` in the request header `API-KEY`.

## Named Entity Recognition API

<mark style="color:green;">`POST`</mark> `https://nlu-api.allganize.ai/api/inference`

#### Headers

| Name                                      | Type   | Description                                                                       |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| API-KEY<mark style="color:red;">\*</mark> | string | Your API key can be found on your dashboard Settings menu, under the General tab. |

#### Request Body

| Name | Type   | Description                                                                                                                                                                    |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| text | string | Input text you want to analyze. English, Japanese, Korean, and Chinese are supported. You can enter up to 2000 characters, after which the entered characters will be ignored. |

{% tabs %}
{% tab title="200 The response has a list of inferred results for the requested text.

startIndex: The start location of the word recognized as the named entity. Shown as a number.
endIndex: The end location of the word recognized as the named entity. Shown as a number.
tag: They type of the named entity. The types are defined in your NLU API dashboard.
token: The word recognized as the named entity." %}

```
{
  "inputText": STRING,
  "entities": [
    { 
      "startIndex": NUMBER, 
      "endIndex": NUMBER, 
      "tag": STRING,
      "token": STRING
    }, ...
  ]
}
```

{% endtab %}
{% endtabs %}

### Request Example

Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/ner-api#getting-api-key) section.

```
curl https://nlu-api.allganize.ai/api/inference \
-d '{"text": "I am traveling from Munich to Paris by Air France business class"}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"
```

### Response Example

```
{
  "inputText": "I am traveling from Munich to Paris by Air France business class",
  "entities": [
    {"startIndex": 20, "endIndex": 26, "tag": "DEPARTURE", "token": "Munich"},
    {"startIndex": 30, "endIndex": 35, "tag": "ARRIVAL", "token": "Paris"},
    {"startIndex": 39, "endIndex": 49, "tag": "AIRLINE", "token": "Air France"},
    {"startIndex": 50, "endIndex": 64, "tag": "SEAT_CLASS", "token": "business class"}
  ]
}
```

## Upload Training and Testing Data

<mark style="color:green;">`POST`</mark> `https://nlu-api.allganize.ai/api/add_phrase/<data_type>`

This API lets you upload training data in json format

#### Path Parameters

| Name       | Type   | Description                                                                                                                            |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| data\_type | String | <p>train - for training data</p><p>test - for testing data</p><p>Other values than train and test will use train as default value.</p> |

#### Headers

| Name                                      | Type   | Description                                                                       |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| API-KEY<mark style="color:red;">\*</mark> | String | Your API key can be found on your dashboard Settings menu, under the General tab. |
| Content-Type                              | String | application/json                                                                  |

#### Request Body

| Name     | Type   | Description                                                                                                                                                                   |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text     | String | Input text you want to analyze. English, Japanese, Korean, and Chinese are supported. You can enter up to 2000 characters, after which the entered characters will be ignored |
| entities | String | Array of entities                                                                                                                                                             |

{% tabs %}
{% tab title="200: OK success: True" %}

```javascript
{"success": true}
```

{% endtab %}
{% endtabs %}

### Request Example

Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/ner-api#getting-api-key) section.

```
curl https://nlu-api.allganize.ai/api/add_phrase/train \ 
-d '[{
  "text": "I am traveling from Munich to Paris by Air France business class",
  "entities": [
    {"start": 20, "end": 26, "tag": {"name": "DEPARTURE"}, "token": "Munich"},
    {"start": 30, "end": 35, "tag": {"name": "ARRIVAL"}, "token": "Paris"},
    {"start": 39, "end": 49, "tag": {"name": "AIRLINE"}, "token": "Air France"},
    {"start": 50, "end": 64, "tag": {"name": "SEAT_CLASS"}, "token": "business class"}
  ]
}' \ 
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"
```

### Response Example

```
{"success": true}
```

## Error Messages

Please read the error message you get if you don't get the response that you expected.&#x20;

| Status Code | Error Code | Name              | Message                                              | Description                                                                                       |
| ----------- | ---------- | ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 500         | 7000       | API Error         | Something went wrong                                 | Default API error message for any uncategorized errors.                                           |
| 403         | 7001       | Invalid API Key   | API-KEY is not valid.                                | When the API Key requested to the header is invalid.                                              |
| 403         | 7002       | Invalid JSON      | Cannot decode the requested JSON body.               | When the requested JSON is not decodable.                                                         |
| 400         | 7003       | Invalid Parameter | Requested parameters are not valid. 'text' is empty. | When the requested parameter is invalid (for example, when requesting inference with empty text). |
| 403         | 7004       | Payment error     | billing error.                                       | Overall payment related errors, e.g., payment is overdue                                          |
| 405         | -          | Wrong HTTP Method | -                                                    | When the HTTP method used is not valid.                                                           |

### Error Response example

```
{
    "type": "APIError",
    "code": 7000,
    "message": "Something went wrong."
}
```