# Named Entity Recognition API

## API Server

Allganize 의 API 엔드포인트는 `nlu-api.allganize.ai` 입니다. On-prem 플랜을 사용중이시라면 사용을 원하는 API 엔드포인트를 사용하시면 됩니다.

## API 키 얻기

모든 NLU API 들은 요청을 검증하기 위해 API 키를 사용합니다. API 키는 [NLU API 대시보드](https://nlu.allganize.ai/projects)의 설정 메뉴에서 찾을 수 있습니다. NLU API 대시보드 계정이 없다면 [여기](https://nlu.allganize.ai/signup)에서 생성할 수 있습니다. 

####  Request 헤더의 `API-KEY` 에 할당된 `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 | string | 할당된 API 키입니다. 대시보드의 설정 메뉴 > 일반 탭에서 찾을 수 있습니다. |

#### Request Body

| Name | Type   | Description                                                                           |
| ---- | ------ | ------------------------------------------------------------------------------------- |
| text | string | 분석을 원하는텍스트입니다. 영어, 일본어, 한국어, 중국어를 지원합니다. 최대 2000자까지 입력하실 수 있으며, 그 이후의 텍스트는 처리되지 않습니다. |

{% tabs %}
{% tab title="200 Response 에는 요청된 텍스트에 대한 분석 결과가 포함되어 있습니다.

startIndex: Named entity 로 인식된 단어의 시작 위치를 나타냅니다. 숫자로 표시됩니다.
endIndex: Named entity 로 인식된 단어의 끝 위치를 나타냅니다. 숫자로 표시됩니다.
tag: 해당 Named entity 의 타입(카테고리)입니다. 타입의 종류는 NLU API 대시보드에서 정의할 수 있습니다.
token: Named entity로 인식된 단어입니다.
" %}

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

{% endtab %}
{% endtabs %}

### Request Example

YOUR API KEY 를 프로젝트의 API 키로 바꾸어야 합니다. [API 키 얻기](https://docs.allganize.ai/v/ko/ner-api#api) 항목을 참고하세요.

```
curl https://nlu-api.allganize.ai/api/inference \
-d '{"text": "뮌헨에서 파리까지 에어 프랑스 비즈니스 클래스로 여행중입니다."}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"
```

### Response Example

```
{
  "inputText": "뮌헨에서 파리까지 에어 프랑스 비즈니스 클래스로 여행중입니다.",
  "entities": [
    {"startIndex": 1, "endIndex": 4, "tag": "DEPARTURE", "token": "뮌헨"},
    {"startIndex": 10, "endIndex": 13, "tag": "ARRIVAL", "token": "파리"},
    {"startIndex": 19, "endIndex": 29, "tag": "AIRLINE", "token": "에어 프랑스"},
    {"startIndex": 31, "endIndex": 45, "tag": "SEAT_CLASS", "token": "비즈니스 클래스"}
}
```

## 에러 메시지

예상했던 response 를 받지 못한 경우 에러 메시지를 확인해 주세요.&#x20;

| Status Code | Error Code | Name              | Message                                              | Description                                    |
| ----------- | ---------- | ----------------- | ---------------------------------------------------- | ---------------------------------------------- |
| 500         | 7000       | API Error         | Something went wrong                                 | API 처리 실패에 대한 기본 메시지로, 분류되지 않은 에러 발생시 수령       |
| 403         | 7001       | Invalid API Key   | API-KEY is not valid                                 | 헤더에 요청한 API Key가 유효하지 않은 경우 수령                 |
| 403         | 7002       | Invalid JSON      | Cannot decode tuen requested JSON body               | 요청한 JSON 파일이 잘못되어 Decode가 불가능한 경우 수령           |
| 400         | 7003       | Invalid Parameter | Requested parameters are not valid. 'text' is empty. | 요청된 파라미터가 잘못된 경우(e.g., 빈 텍스트로 인퍼런스를 요청 등) 수령   |
| 403         | 7004       | Payment error     | billing error.                                       | 지불 관련 일반 오류 (e.g., 지불 기한이 넘어간 경우 등)가 발생한 경우 수령 |
| 405         | -          | Wrong HTTP Method | -                                                    | 잘못된 HTTP 메소드를 사용한 경우 수령                        |

### Error Response example

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