Requirements

The Bareun API is built on connectrpc by default. This approach unifies traditional REST, gRPC, and grpc-web into a single way of serving. It is based on gRPC, which uses Protocol Buffers, and takes that approach further. As a result, it is faster than plain REST and also very stable.

The new approach unifies REST, gRPC, and gRPC-Web into one service.

REST API port

Every service is on port 5656

One service port handles 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

Applies from v3.0.rc4

From v3.0.rc4, every Bareun service port is 5656. Earlier versions used several different ports.

The cloud service uses HTTPS

When you call through api.bareun.ai, the service port is 443. When you use the examples below, replace http://localhost:5656/ with https://api.bareun.ai/.

Try it out

Click Authorize to register your ApiKey, then use Try it out.

API URLs and features

Feature	URL	HTTP/1.1 METHOD
Morphological analysis	`/bareun.LanguageService/AnalyzeSyntax`	POST
Morphological analysis (no sentence splitting)	`/bareun.LanguageService/AnalyzeSyntaxList`	POST
Word tokenization	`/bareun.LanguageService/Tokenize`	POST
List custom dictionaries	`/bareun.CustomDictionaryService/GetCustomDictionaryList`	POST
Get a custom dictionary	`/bareun.CustomDictionaryService/GetCustomDictionary`	POST
Update a custom dictionary	`/bareun.CustomDictionaryService/UpdateCustomDictionary`	POST
Delete a custom dictionary	`/bareun.CustomDictionaryService/RemoveCustomDictionaries`	POST
Check custom dictionary conflicts	`/bareun.CustomDictionaryService/CheckConflict`	POST
Spell check	`/bareun.RevisionService/CorrectError`	POST

All methods are POST

All APIs use the "POST" method.

Content-Type

Various Content-Type values are accepted, but please use "application/json" by default.

Full URL

The API as actually served is called like this.

http://localhost:5656/bareun.LanguageService/AnalyzeSyntax

For the cloud API, the URL is different.

https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax

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

App identification header

An app that calls with an end user's key (BYOK) can send the X-Bareun-App-Id header along with api-key, and usage is then counted per app. See BYOK app registration and header conventions.

Examples

Morphological analysis

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'

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

Morphological analysis + homonym sense disambiguation (beta)

When you turn on with_sense, each morpheme comes with a sense number (the dictionary's meaning number) and a definition. This is a beta feature available since Bareun 3.1.0. For details, see the homonym sense disambiguation API.

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
  -d '{"document": {"content": "다리를 건넜다.","language": "ko-KR"}, "encoding_type": "UTF32", "with_sense": true}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.LanguageService/AnalyzeSyntax \
  -d '{"document": {"content": "다리를 건넜다.","language": "ko-KR"}, "encoding_type": "UTF32", "with_sense": true}'

In the response, sense is attached only to morphemes that were assigned a sense (it is not attached to particles or endings).

{
  "text": { "content": "다리", "beginOffset": 0, "length": 2 },
  "tag": "NNG",
  "probability": 0.9917928,
  "outOfVocab": "IN_WORD_EMBEDDING",
  "sense": {
    "senseNo": 5,
    "meaning": "물을 건너거나 또는 한편의 높은 곳에서 다른 편의 높은 곳으로 건너다닐 수 있도록 만든 시설물.",
    "urimalTargetId": 836,
    "probability": 0.935963
  }
}

Morphological analysis (no sentence splitting)

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

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

Word tokenization

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.LanguageService/Tokenize \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8"}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.LanguageService/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. When you get the list of custom dictionaries, you must send an empty value as the data.

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.CustomDictionaryService/GetCustomDictionaryList \
  -d '{}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.CustomDictionaryService/GetCustomDictionaryList \
  -d '{}'

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" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.CustomDictionaryService/GetCustomDictionary \
  -d '{ "domain_name": "mydomain"}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.CustomDictionaryService/GetCustomDictionary \
  -d '{ "domain_name": "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" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.CustomDictionaryService/UpdateCustomDictionary \
  -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"}}}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.CustomDictionaryService/UpdateCustomDictionary \
  -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" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.CustomDictionaryService/RemoveCustomDictionaries \
  -d '{"domain_names": ["mydomain"],"all": true}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.CustomDictionaryService/RemoveCustomDictionaries \
  -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" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.CustomDictionaryService/CheckConflict \
  -d '{"domain_names": ["compare1", "compare2"]}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.CustomDictionaryService/CheckConflict \
  -d '{"domain_names": ["compare1", "compare2"]}'

Spell check

Send the sentences whose grammar, word spacing, standard-language usage, and so on you want corrected, and you receive the corrections. Send input one paragraph at a time; you may also send several paragraphs at once.

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST https://api.bareun.ai/bareun.RevisionService/CorrectError \
  -d '{"document": {"content": "밥이 떡처럼 되서 못먹었어요","language": "ko-KR"}, "encoding_type": "UTF32", "custom_dict_names": ["testDomain"]}'

curl \
  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:5656/bareun.RevisionService/CorrectError \
  -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.LanguageService/AnalyzeSyntax
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 sentences split automatically, 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.
with_sense	-	Whether to also perform homonym sense disambiguation (WSD, beta). The default is `false`. When turned on, the response morphemes carry `sense` (sense number, definition, Urimalsaem number, selection probability).
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.LanguageService/AnalyzeSyntaxList
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	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.

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.
			sense		Result of homonym sense disambiguation (WSD, beta). Present only when `with_sense` is on and a sense was assigned to that morpheme. `senseNo`: sense number (Urimalsaem meaning number) `meaning`: definition (may be empty) `urimalTargetId`: Urimalsaem headword number `probability`: probability of choosing this sense among the candidate senses
language					Language of this response. ko_KR is the default.

List custom dictionaries

Function: List custom dictionaries
Path: /bareun.CustomDictionaryService/GetCustomDictionaryList
Method: POST

Request

There is nothing to send in the request.
Instead, you must send an empty JSON value: {}

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.CustomDictionaryService/GetCustomDictionary
Method: POST

Request

Variable	Description
domain_name	Enter the name of the custom dictionary to get.

Response

Name	Sub1	Sub2	Sub3	Description
domain				Name of the response domain
dict	domain_name			Name of the dictionary
	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.CustomDictionaryService/UpdateCustomDictionary
Method: POST

Request

Name	Sub1	Sub2	Sub3	Description
domain				Domain name
dict	domain_name			Name of the dictionary
	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.CustomDictionaryService/RemoveCustomDictionaries
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	The object's key is the name of the deleted domain
	VALUE	`true` or `false`

Spell check

Function: Checks and corrects grammar, word spacing, standard-language usage, and so on.
Path: /bareun.RevisionService/CorrectError
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 sentences split automatically, 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	Does not split text into sentences. This is the default, so it is best not to use it.
	disable_caret_spacing	Does not apply the compound noun splitting dictionary. It is applied by default. When it meets "인공지능" written without a space, the original dictionary entry 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	Enables sentence-level checks. Corrects an object marker that does not fit the predicate into a subject marker, and suggests, as a confirmation block, an active-voice rewrite of translationese passives (`~에 의해 ~되다`). The default is `false`.
	enable_public_term_refine	Enables public-term refinement suggestions. Suggests easier words, as confirmation blocks, for administrative terms refined by the National Institute of Korean Language and for Japanese-style terms, without changing the text. The default is `false`.
	enable_contested_fix	Enables contested fixes. Suggests, as confirmation blocks, expressions that the guidelines recommend against but that are common (`좋은 하루 되세요`, `회의에 있어서`, and so on), and removes the plural `-들` after a quantity expression from the text. The default is `false`.
	disable_bias_check	Turns off the confirmation blocks that suggest neutral wording for belittling or discriminatory expressions. The default is `false` (on).

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.