This page applies to versions before 3.0-rc3

This page describes how to call the REST interface in Bareun versions before 3.0-rc3. In those versions, a separate proxy (envoyproxy) sat in front of the server, and you called paths of the form /bareun/api/v1/....

The current version does not need a proxy. The server handles gRPC, connect-web, and HTTP+JSON on a single port, so REST calls also use the Connect path (POST /bareun.<service>/<method>). If you are on version 3.0-rc3 or later, see the REST API page.

Requirements

The Bareun API is built on gRPC by default. It is faster than a REST interface and also very stable.

On the other hand, many developers and environments prefer REST. With a technology called envoyproxy, a REST API can be provided easily. We used it to support the REST interface as well.

REST API port

Port 5656 in the Docker version

When you use the Docker version, requests to port 5656 handle gRPC, REST, and grpc-web all at once. All the examples below use this port. This one port serves three kinds of services at the same time.

gRPC API
REST API
grpc-web API

Port 5655 in the standard installed version

From v3.0.rc2, the REST API is supported on port 5655. The installed versions for Linux, macOS, and Windows all provide the REST service through this port.

API URLs and features

Feature	URL	HTTP/1.1 METHOD
Morphological analysis	`/bareun/api/v1/analyze`	POST
Morphological analysis (no sentence splitting)	`/bareun/api/v1/analyze-list`	POST
Word tokenization	`/bareun/api/v1/tokenize`	POST
List custom dictionaries	`/bareun/api/v1/customdict`	GET
Get a custom dictionary	`/bareun/api/v1/customdict/{domain}`	GET
Update a custom dictionary	`/bareun/api/v1/customdict/{domain}`	POST
Delete a custom dictionary	`/bareun/api/v1/customdict/delete`	POST
Check custom dictionary conflicts	`/bareun/api/v1/customdict/check-conflict`	POST
Spell check	`/bareun/api/v1/correct-error`	POST

Full URL

Adding the port you use when running Docker, the full URL is as follows.

http://localhost:5656/bareun/api/v1/analyze

To test the API with a tool such as curl, do the following.

Examples

Morphological analysis

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/analyze \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'

Morphological analysis (no sentence splitting)

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/analyze-list \
  -d '{"document": {"sentences": ['안녕하세요.', '바른 형태소분석기입니다.', '만나서 반갑습니다.'], "language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'

Word tokenization

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/tokenize \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8"}'

Get the list of dictionaries

Returns the names and metadata of all registered custom dictionaries. You can check the list of dictionaries currently in service here.

curl  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  http://localhost:5656/bareun/api/v1/customdict

Get a dictionary

After checking the list of all dictionaries with the list API above, you can download the contents of an individual custom dictionary.

curl   -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  http://localhost:5656/bareun/api/v1/customdict/mydomain

Update or create a custom dictionary

You can update a dictionary by changing the contents in the same data format you downloaded earlier. The URL is the same, but you now send it with POST.


curl  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/customdict/mydomain \
  -d '{ "domain_name": "mydomain", \
     "dict": \
       {"domain_name": "mydomain", \
         "np_set": { \
           "items": { \
              "광화문": 1 \
              "숭례문": 1 \
              "흥인지문": 1 \
           }, "type": "WORD_LIST", "name": "np_set"}, \
         "cp_set": { \
           "items": {\
              "논밭": 1 \
              "봄비": 1 \
              "자유여행": 1 \
           }, "type": "WORD_LIST", "name": "cp_set"},\
          "cp_caret_set": { \
           "items": { \
              "가격^파괴": 1 \
              "소비자^만족": 1 \
              "블루투스^이어폰": 1 \
           },"type": "WORD_LIST", "name": "cp_caret_set"}}}'

Delete a custom dictionary

When you delete a dictionary, you can delete all of it or only part of it. With "all" : true, everything is deleted.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/customdict/delete \
  -d '{"domain_names": ["mydomain"],"all": true}'

Check custom dictionary conflicts

You can use more than one dictionary at the same time, which can produce unintended results. You can specify two or more custom dictionaries to compare them.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/customdict/check-conflict \
  -d '{"domain_names": ["compare1", "compare2"]}'

Spell check

Send the sentence whose grammar, word spacing, standard-language usage, and so on you want corrected.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5656/bareun/api/v1/correct-error \
  -d '{"document": {"content": "밥이 떡처럼 되서 못먹었어요","language": "ko-KR"}, "encoding_type": "UTF32", "custom_dict_names": ["testDomain"]}'

API specification

Morphological analysis

Function: Performs the core morphological analysis.
Path: /bareun/api/v1/analyze
Method: POST

Request

Name	Sub	Description
document	{}	Input document
	content	Holds the document or sentences. For multiple sentences, you can separate them with line breaks. If you want automatic line splitting, turn on the `auto_split_sentence` option.
	language	Only Korean is supported at present, so you do not need to specify it. An ISO or BCP-47 language code is used. Enter a value such as ko_KR.
encoding_type	-	Choose from `UTF8`, `UTF16`, and `UTF32`. The usual choice differs by development language. Use `UTF32` for Python 3, `UTF16` for Java, and `UTF8` for C or Go.
auto_split_sentence	-	Whether to split sentences when several sentences are sent together. By default, sentences are split at line breaks.
auto_spacing	-	Whether to apply automatic word spacing. The libraries default to `true`. With `REST`, you must set it yourself.
auto_jointing	-	Whether to apply automatic joining (removing spaces). The libraries default to `true`. With `REST`, you must set it yourself.
custom_domain	-	Specifies the name of the custom dictionary to use. The dictionary name must be registered beforehand through a separate API. If the dictionary name you want does not exist, it is ignored. ~~Deprecated.~~
custom_dict_names	-	Specifies the names of the custom dictionaries to use. You can specify several pre-registered dictionaries. They are applied in the order specified, starting with the first.

Morphological analysis (no sentence splitting)

Function: Performs morphological analysis, returns multiple input sentences in their original order, and does not split sentences.
Path: /bareun/api/v1/analyze-list
Method: POST

Request

Variable	Description
sentences	Enter the text as an array.
language	Only Korean is supported at present, so you do not need to specify it. An ISO or BCP-47 language code is used. Enter a value such as ko_KR.
encoding_type	Choose from `UTF8`, `UTF16`, and `UTF32`. The usual choice differs by development language. Use UTF32 for Python 3, `UTF16` for Java, and `UTF8` for C or Go.
auto_spacing	Whether to apply automatic word spacing. The libraries default to `true`. With REST, you must set it yourself.
auto_jointing	Whether to apply automatic joining (removing spaces). The libraries default to `true`. With REST, you must set it yourself.
custom_domain	Specifies the name of the custom dictionary to use. The dictionary name must be registered beforehand through a separate API. If the dictionary name you want does not exist, it is ignored.
custom_dict_names	-

Response

Name	Sub1	Sub2	Sub3	Sub4	Description
sentences	[]				Divided into one or more sentences.
	refined				Marked as refined if the sentence was changed by word spacing, joining, and so on
	text	{}			Text span of the whole sentence
		content			Content of the sentence
		begin_offset			Start position of the sentence
		length			Length of the sentence
	tokens	[]			Array of eojeols (space-delimited word units)
		text	{}		Text span of the eojeol
			content		Content of the eojeol
			begin_offset		Start position of the eojeol
			length		Length of the eojeol
		lemma			Base form
		tagged			String built in tagged form
		modified			If joining was applied, the joined result
		morphemes	[]		Array of morphemes
			text	{}	Text span of the morpheme
				content	Content of the morpheme
				begin_offset	Start position of the morpheme
				length	Length of the morpheme
			tag		Morpheme tag. 47 parts of speech are used in total.
			probability		Accuracy of the morpheme classification
			out_of_vocab		Shows how a dictionary was used in the classification. `IN_WORD_EMBEDDING`: included in the word embeddings `OUT_OF_VOCAB`: automatic guess `IN_CUSTOM_DICT`: found in a user-provided dictionary `IN_BUILTIN_DICT` : included in the default dictionary
			custom_dict_name		If the word was specified in a custom dictionary, shows the name of that dictionary.
language					Language of this response. ko_KR is the default.

List custom dictionaries

Function: List custom dictionaries
Path: /bareun/api/v1/customdict
Method: GET

Request

There is nothing to send in the request.

Response

Name	Sub1	Sub2	Description
domain_dicts	[]		One or more metadata entries
	domain_name		Name of the dictionary
	np_set	{}	Proper noun dictionary information
		name	Name of the dictionary
		items_count	Dictionary size information
		type	"WORD_LIST"
	cp_set	{}	Compound noun dictionary information
		name	Name of the dictionary
		items_count	Dictionary size information
		type	"WORD_LIST"
	cp_caret_set	{}	Compound noun splitting dictionary information
		name	Name of the dictionary
		items_count	Dictionary size information
		type	"WORD_LIST"
	vv_set	{}	Verb dictionary information
		name	Name of the dictionary
		items_count	Dictionary size information
		type	"WORD_LIST"
	va_set	{}	Adjective dictionary information
		name	Name of the dictionary
		items_count	Dictionary size information
		type	"WORD_LIST"

Get a custom dictionary

Function: Get a custom dictionary
Path: /bareun/api/v1/customdict/{domain}
Method: GET

Request

Put the domain you are requesting in the {domain} position of the URL.
For example, http://localhost:5656/bareun/api/v1/customdict/__mydomain__

Response

Name	Sub1	Sub2	Sub3	Description
domain				Name of the response domain
dict	domain_name
	np_set	{}		Proper noun dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	cp_set	{}		Compound noun dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	cp_caret_set	{}		Compound noun splitting dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	vv_set	{}		Verb dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	va_set	{}		Adjective dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer

Update a custom dictionary

Function: Update a custom dictionary
URL: /bareun/api/v1/customdict/{domain}
Method: POST

Request

Name	Sub1	Sub2	Sub3	Description
domain				Name of the response domain
dict	domain_name
	np_set	{}		Proper noun dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	cp_set	{}		Compound noun dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	cp_caret_set	{}		Compound noun splitting dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	vv_set	{}		Verb dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer
	va_set	{}		Adjective dictionary information
		name		Name of the dictionary
		type	"WORD_LIST"
		items	[]	Start of the actual dictionary contents
			KEY	Dictionary text
			VALUE	Non-zero integer

Response

Name	Sub	Description
updated_domain_name	-	Name of the updated domain.

Delete a custom dictionary

Function: Delete a custom dictionary
URL: /bareun/api/v1/customdict/delete
Method: POST

Request

Name	Sub	Description
domain_names	[]	Array of domains to delete.
	VALUE	Domain to delete
all		Whether to delete everything. If `true`, all custom dictionaries are deleted.

Response

Name	Sub	Description
deleted_domain_names	{}	Returned as an object
	KEY	-
	VALUE`	-

Spell check

Function: Checks and corrects grammar, word spacing, standard-language usage, and so on.
Path: /bareun/api/v1/correct-error
Method: POST

Request

Name	Sub	Description
document	{}	Input document
	content	Holds the document or sentences. For multiple sentences, you can separate them with line breaks. If you want automatic line splitting, turn on the `auto_split_sentence` option.
	language	Only Korean is supported at present, so you do not need to specify it. An ISO or BCP-47 language code is used. Enter a value such as ko_KR.
encoding_type	-	Choose from `UTF8`, `UTF16`, and `UTF32`. The usual choice differs by development language. Use `UTF32` for Python 3, `UTF16` for Java, and `UTF8` for C or Go.
custom_dict_names	-	Specifies the names of the custom dictionaries to use. The dictionary names must be registered beforehand through a separate API. If the dictionary name you want does not exist, it is ignored.
config	{}	Detailed call options.
	disable_split_sentence	Disables sentence splitting. Splitting is the default, so it is best not to use this option.
	disable_caret_spacing	Does not apply the compound noun splitting dictionary. It is applied by default. When it meets the solid-written word "인공지능", the original dictionary form is "인공^지능", so it splits it into "인공 지능".
	disable_vx_spacing	Minimizes spacing of auxiliary verbs. By default, auxiliary verbs are spaced apart as much as possible. This is the basic rule of the word spacing check.
	treat_as_title	Treats the sentence as a title. Some processing, including punctuation, differs for sentences used as titles.
	enable_cleanup_whitespace	Removes unnecessary whitespace in the sentence. In particular, it can remove unnecessary whitespace at the start or end of a sentence.
	enable_sentence_check	Also analyzes agreement relationships within a sentence.

Response

Variable	Sub	Description
origin		The full original text of the request document
revised		The full revised document
revised_blocks[]		Presents revision blocks so that various revision actions can be carried out.
	origin	Original text that includes the position of the revision target
	revised	The revised result, the most representative one among several
	revisions	Various revision examples, including the revision category and help ID information
	nested	When several blocks were merged into one, the original blocks were probably not wrong, so they are kept inside as nested blocks. However, each nested block contains only its own individual fix, so they cannot hold every block completely. It is provided so that advanced users can apply only that content to a fix.
	lemma	Basic unit for adding to the custom dictionary. Not available when nested exists.
	pos	Part of speech to add to the custom dictionary
whitespace_cleanup_ranges[]		List of whitespace to remove from the revision target
	offset	Position
	length	Length
	position	Takes one of three values: `START`, `END`, `MIDDLE`.
revised_sentences[]		Revision for each whole sentence. Sentences are split automatically and shown separately.
	origin	Sentence to revise
	revised	Revised sentence
helps{}
	id	Help ID. Some help is fixed and some is generated dynamically.
	category	Revision category
	comment	Explanation of why the text should change
	examples[]	Sentences it can be changed to
	rule_article	Related rule
language		Language of the text. If no language was specified, it is detected automatically and returned. If a language was specified, the same language is returned. Use values such as ko_KR.