語言云新版API是REST風(fēng)格的WEB API調(diào)用服務(wù)，REST API服務(wù)有諸多優(yōu)點(diǎn)，這使得它越來越流行。應(yīng)用于語言云服務(wù)中，主要有如下特點(diǎn)：

• 免SDK安裝：REST API的調(diào)用無須用戶下載SDK，使得語言分析更為便捷。
• 結(jié)果表示格式豐富：API提供了包括PLAIN/XML/JSON/CONLL等多種格式的結(jié)果表示。且返回結(jié)果容易擴(kuò)展，便于進(jìn)行二次開發(fā)。
• 支持JavaScript調(diào)用：語言云支持JavaScript以JSON-P回調(diào)的方式調(diào)用API，使得返回結(jié)果可以嵌入到Web頁面或者宿主Web應(yīng)用中。
• 請求方式多樣：語言云提供了HTTP GET和HTTP POST兩種方式的調(diào)用接口。
• 用戶認(rèn)證簡潔：API_KEY取代了舊版email:token的認(rèn)證方式，作為用戶的統(tǒng)一授權(quán)方式。

已經(jīng)在語言云注冊的用戶請留意您注冊的郵箱以及您在語言云網(wǎng)站上的控制面板，我們將把您使用語言云API的API_KEY通過以上方式提示給您。

新用戶請先在語言云上注冊一個賬號。相關(guān)信息審核通過后，系統(tǒng)會向您的注冊郵箱發(fā)送API_KEY和您本月的流量額度，后者將在控制面板實(shí)時更新，便于用戶進(jìn)行查看。

email:token作為舊版API的調(diào)用認(rèn)證將在一段時間內(nèi)保留，APK_KEY作為新版API的調(diào)用認(rèn)證方式。新注冊用戶將獲得每月20G的免費(fèi)流量。

參數(shù)名及對應(yīng)的參數(shù)值區(qū)分大小寫且不支持縮略形式。

以上參數(shù)同時支持且只支持GET和POST兩種方式的提交。

用戶可以用兩種方式來調(diào)用API

• 直接使用REST
• 在JavaScript中使用REST

REST

REST,或者叫做Representational State Transfer，在語言云API中并不等同于傳統(tǒng)的REST。傳統(tǒng)的REST提供對于資源的訪問，而語言云REST API提供對于服務(wù)的訪問。因此，在語言云API中，一個單獨(dú)的URI就是一個服務(wù)端點(diǎn)。

在語言云中，所有的API訪問都是通過HTTP請求的方式。并且需要從api.ltp-cloud.com域進(jìn)行訪問。語言云只支持GET和POST方式的HTTP請求。用戶通過在HTTP請求中指定參數(shù)來獲取對應(yīng)的結(jié)果。

舉個例子，對“我是中國人?！边@句話做依存句法分析，并且返回plain格式的結(jié)果。

GET請求及返回結(jié)果示例：

$ curl -i "http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=dp&format=plain"
HTTP/1.1 200 OK
Server: nginx/1.1.19
Date: Fri, 03 Jan 2014 04:24:32 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

我_0 是_1 SBV
是_1 -1 HED
中國_2 人_3 ATT
人_3 是_1 VOB

POST請求及返回結(jié)果示例：

$ curl -i -d "api_key=YourApiKey&text=我是中國人。&pattern=dp&format=plain" "http://api.ltp-cloud.com/analysis/"
HTTP/1.1 200 OK
Server: nginx/1.1.19
Date: Fri, 03 Jan 2014 05:58:55 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

我_0 是_1 SBV
是_1 -1 HED
中國_2 人_3 ATT
人_3 是_1 VOB

使用Python語言以GET方式調(diào)用REST API代碼示例如下：

# -*- coding:utf8 -*-
import urllib2
if __name__ == '__main__':
    url_get_base = "http://api.ltp-cloud.com/analysis/?"
    api_key = ''
    text = ''
    format = ''
    pattern = ''
    result = urllib2.urlopen("%sapi_key=%s&text=%s&format=%s&pattern=%s" % (url_get_base,api_key,text,format,pattern))
    content = result.read().strip()
    print content

更多使用其他編程語言以GET和POST方式調(diào)用REST API代碼示例以及注意事項(xiàng)請參考API編程調(diào)用示例。

JavaScript調(diào)用REST

語言云支持用戶使用JavaScript以JSON-P回調(diào)的方式調(diào)用API，用戶需要以GET方式進(jìn)行調(diào)用并且只支持json的返回格式。

在此方式中，需要用戶在uri中添加callback參數(shù)并且在js中指定相同名稱的回調(diào)函數(shù)進(jìn)行結(jié)果的捕捉，這通常用于跨域訪問使得結(jié)果嵌入到Web頁面中。

$ curl -i "http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=dp&format=json&callback=foo"
HTTP/1.1 200 OK
Server: nginx/1.1.19
Date: Fri, 03 Jan 2014 08:08:56 GMT
Content-Type: application/javascript
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

foo(
//json data
)

在JavaScript中捕捉調(diào)用結(jié)果代碼示例如下：

var foo = function(data){
    json_str = JSON.stringify(data);
    document.getElementsByTagName("body")[0].innerHTML += json_str;
};
window.onload=function(){
    var base = "http://api.ltp-cloud.com/analysis/?";
    var api_key = "";
    var text = "";
    var pattern = "";
    var format = "json";
    var callback = "foo";
    var url = base + "api_key="+api_key+"&text="+text+"&pattern="+pattern+"&format="+format+"&callback="+callback;
    var script = document.createElement('script');
    script.setAttribute('src', url);
    document.getElementsByTagName('head')[0].appendChild(script);
}

語言云也提供了使用Jquery調(diào)用API的示例，請參考JavaScript調(diào)用API示例。

語言云API提供了較為豐富的分析結(jié)果表示格式，包括plain,xml,json和conll

PLAIN

分詞

對文本進(jìn)行分詞的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=ws&format=plain

返回結(jié)果為：

我 是 中國 人 。

在plain格式的分詞結(jié)果中，每句話占一行。詞與詞之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。

詞性標(biāo)注

對文本進(jìn)行詞性標(biāo)注的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=pos&format=plain

我_r 是_v 中國_ns 人_n 。_wp

在plain格式的詞性標(biāo)注結(jié)果中，每句話占一行。詞和詞的標(biāo)注信息之間用下劃線連接，項(xiàng)與項(xiàng)之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。

命名實(shí)體識別

對文本進(jìn)行命名實(shí)體識別的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=ner&format=plain

返回結(jié)果為：

我 是 [中國]Ns 人 。

在plain格式的命名實(shí)體識別結(jié)果中，每句話占一行。如果本句話含有實(shí)體，將會被[]包圍，并且在之后添加實(shí)體類型標(biāo)識。段落與段落之間有兩個換行符分割。

如果您只想獲得文本中的所有的命名實(shí)體列表，請用參數(shù)only_ner=true來指定。

其調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=ner&format=plain&only_ner=true

返回結(jié)果為：

中國 Ns

在plain格式的命名實(shí)體識別列表形式的返回結(jié)果中，每個實(shí)體信息占一行。每一行有兩列，第一列為實(shí)體本身，第二列為實(shí)體類型。

依存句法分析

對文本進(jìn)行依存句法分析的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=dp&format=plain

返回結(jié)果為：

我_0 是_1 SBV
是_1 -1 HED
中國_2 人_3 ATT
人_3 是_1 VOB
。_4 是_1 WP

在plain格式的依存句法分析返回結(jié)果中，文本中的每個詞的句法信息占一行。每一行獨(dú)占三列。第一列為依存句法分析的孩子結(jié)點(diǎn)信息，由結(jié)點(diǎn)名+下劃線+詞id組成；第二列為依存句法分析的父親節(jié)點(diǎn)信息，由結(jié)點(diǎn)名+下劃線+詞id組成，如果沒有父親結(jié)點(diǎn)，則由-1表示;第三列為具體的依存句法分析關(guān)系。文本句子級別的信息之間用兩個換行分割，文本段落級別的信息之間用三個換行分割。

語義依存分析

對文本進(jìn)行語義依存分析的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=sdp&format=plain

返回結(jié)果為：

我_0 是_1 Exp
是_1 -1 Root
中國_2 人_3 Nmod
人_3 是_1 Clas
。_4 是_1 mPunc
 

在plain格式下返回的語義依存分析結(jié)果的格式與依存句法分析格式相同。最后一列顯示了語義依存的關(guān)系。

語義角色標(biāo)注

對文本進(jìn)行語義角色標(biāo)注的調(diào)用示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=srl&format=plain

返回結(jié)果為：

[我]A0 [是]v [中國 人]A1 。

在plain格式的語義角色標(biāo)注返回結(jié)果中，每個謂詞的語義角色信息獨(dú)占一行，如果一個句子有多個謂詞，那么占多行。行與行之間用換行分割，文本句子級別的信息之間用兩個換行分割，文本段落級別的信息之間用三個換行分割。

XML

XML

對文本進(jìn)行全部任務(wù)的分析示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我們都是中國人。&pattern=all&format=xml

返回結(jié)果為：

<xml4nlp>
    <note sent="y" word="y" pos="y" ne="y" parser="y" semparser="y" wsd="n" srl="y"/>
    <doc>
        <para id="0">
            <sent id="0" cont="我是中國人。">
                <word id="0" cont="我" pos="r" ne="O" parent="1" relate="SBV" semparent="1" semrelate="Exp"/>
                <word id="1" cont="是" pos="v" ne="O" parent="-1" relate="HED" semparent="-1" semrelate="Root">
                    <arg id="0" type="A0" beg="0" end="0"/>
                    <arg id="1" type="A1" beg="2" end="3"/>
                </word>
                <word id="2" cont="中國" pos="ns" ne="S-Ns" parent="3" relate="ATT" semparent="3" semrelate="Nmod"/>
                <word id="3" cont="人" pos="n" ne="O" parent="1" relate="VOB" semparent="1" semrelate="Clas"/>
                <word id="4" cont="。" pos="wp" ne="O" parent="1" relate="WP" semparent="1" semrelate="mPunc"/>
            </sent>
        </para>
    </doc>
</xml4nlp>

XML標(biāo)準(zhǔn)結(jié)果如下：結(jié)點(diǎn)標(biāo)簽分別為 xml4nlp, note, doc, para, sent, word, arg 共七種結(jié)點(diǎn)標(biāo)簽：

1. xml4nlp 為根結(jié)點(diǎn)，無任何屬性值；
2. note 為標(biāo)記結(jié)點(diǎn)，具有的屬性分別為：sent, word, pos, ne, parser, srl；分別代表分句，分詞，詞性標(biāo)注，命名實(shí)體識別，依存句法分析，詞義消歧，語義角色標(biāo)注；值為"n"，表明未做，值為"y"則表示完成，如pos="y"，表示已經(jīng)完成了詞性標(biāo)注；
3. doc 為篇章結(jié)點(diǎn)，以段落為單位包含文本內(nèi)容；無任何屬性值；
4. para 為段落結(jié)點(diǎn)，需含id 屬性，其值從0 開始；
5. sent 為句子結(jié)點(diǎn)，需含屬性為id，cont；id 為段落中句子序號，其值從0 開始；cont 為句子內(nèi)容；
6. word 為分詞結(jié)點(diǎn)，需含屬性為id, cont；id 為句子中的詞的序號，其值從0 開始，cont為分詞內(nèi)容；可選屬性為 pos, ne, parent, relate , semparent,semrelate；pos 的內(nèi)容為詞性標(biāo)注內(nèi)容；ne 為命名實(shí)體內(nèi)容；parent 與 relate 成對出現(xiàn)，parent 為依存句法分析的父親結(jié)點(diǎn)id 號，relate 為相對應(yīng)的關(guān)系；semparent 與 semrelate 成對出現(xiàn)，semparent 為語義依存分析的父親結(jié)點(diǎn)id 號，semrelate 為相對應(yīng)的關(guān)系；
7. arg 為語義角色信息結(jié)點(diǎn)，任何一個謂詞都會帶有若干個該結(jié)點(diǎn)；其屬性為id, type, beg，end；id 為序號，從0 開始；type 代表角色名稱；beg 為開始的詞序號，end 為結(jié)束的序號；

各結(jié)點(diǎn)及屬性的邏輯關(guān)系說明如下：

1. 各結(jié)點(diǎn)層次關(guān)系可以從圖中清楚獲得，凡帶有id 屬性的結(jié)點(diǎn)是可以包含多個；
2. 如果sent="n"即未完成分句，則不應(yīng)包含sent 及其下結(jié)點(diǎn)；
3. 如果sent="y" word="n"即完成分句，未完成分詞，則不應(yīng)包含word 及其下結(jié)點(diǎn)；
4. 其它情況均是在sent="y" word="y"的情況下：
   1. 如果 pos="y" 則分詞結(jié)點(diǎn)中必須包含pos 屬性；
   2. 如果 ne="y" 則分詞結(jié)點(diǎn)中必須包含ne 屬性；
   3. 如果 parser="y" 則分詞結(jié)點(diǎn)中必須包含parent 及relate 屬性；
   4. 如果 semparser="y" 則分詞結(jié)點(diǎn)中必須包含semparent 及semrelate 屬性；
   5. 如果 srl="y" 則凡是謂詞(predicate)的分詞會包含若干個arg 結(jié)點(diǎn)；

在XML格式的分析中，用戶可以通過指定參數(shù)pattern=ws | pos | ner | dp | sdp | srl | all 來指名分析任務(wù)并獲取對應(yīng)的XML結(jié)果。

JSON

對文本進(jìn)行全部任務(wù)的分析示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=all&format=json

返回結(jié)果為：

[
 [
  [
   {
    "id": 0, 
    "cont": "我", 
    "pos": "r", 
    "semparent": 1, 
    "semrelate": "Exp"
   }, 
   {
    "id": 1, 
    "cont": "是", 
    "pos": "v", 
    "semparent": -1, 
    "semrelate": "Root"
   }, 
   {
    "id": 2, 
    "cont": "中國", 
    "pos": "ns", 
    "semparent": 3, 
    "semrelate": "Nmod"
   }, 
   {
    "id": 3, 
    "cont": "人", 
    "pos": "n", 
    "semparent": 1, 
    "semrelate": "Clas"
   }, 
   {
    "id": 4, 
    "cont": "。", 
    "pos": "wp", 
    "semparent": 1, 
    "semrelate": "mPunc"
   }
  ]
 ]
]

JSON (JavaScript Object Notation) 是一種常見的，與語言無關(guān)的數(shù)據(jù)格式，提供任意數(shù)據(jù)結(jié)構(gòu)的簡單表示。

在json格式的返回結(jié)果中，采用段落級、句子級、單詞級的遞進(jìn)層次關(guān)系，且段落與句子并沒有進(jìn)行鍵值名標(biāo)識，因而須采用數(shù)組下標(biāo)方式獲取信息。

比如說，p代表json結(jié)果，獲取第一段第二句第三個單詞的詞性信息，獲取方式類似于p[0][1][2]["pos"]。

json格式是語言云重點(diǎn)推薦給用戶的語言分析結(jié)果格式，有關(guān)更多使用方法，請參考語言云提供的JSON格式的重要說明。

在json格式的單詞對象{}中，需含鍵值名為id, cont；id 為句子中的詞的序號，其值從0 開始，cont為分詞內(nèi)容；可選鍵值名為 pos, ne, parent, relate；pos 的內(nèi)容為詞性標(biāo)注內(nèi)容；ne 為命名實(shí)體內(nèi)容；parent 與 relate 成對出現(xiàn)，parent 為依存句法分析的父親結(jié)點(diǎn)id 號，relate 為相對應(yīng)的關(guān)系；semparent 與 semrelate 成對出現(xiàn)，semparent 為語義依存分析的父親結(jié)點(diǎn)id 號，semrelate 為相對應(yīng)的關(guān)系；

如果用戶做了srl級別的分析，json結(jié)果中還會有鍵值名arg所標(biāo)識的數(shù)組。數(shù)組中的每個對象是一項(xiàng)語義角色，任何一個謂詞都會帶有若干個該對象；其鍵值名為id, type, beg，end；id 為序號，從0 開始；type 代表角色名稱；beg 為開始的詞序號，end 為結(jié)束的序號；如果單詞沒有語義角色信息，arg所標(biāo)識的數(shù)組為空。

用戶也可以通過指定參數(shù)has_key=false來去掉鍵值名，示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=all&format=json&has_key=false

返回結(jié)果為：

[[[[0, "我", "r", "O", 1, "SBV", 1, "Exp", []], [1, "是", "v", "O", -1, "HED", -1, "Root", [[0, "A0", 0, 0], [1, "A1", 2, 3]]], [2, "中國", "ns", "S-Ns", 3, "ATT", 3, "Nmod", []], [3, "人", "n", "O", 1, "VOB", 1, "Clas", []], [4, "。", "wp", "O", 1, "WP", 1, "mPunc", []]]]]

在json格式的無鍵值名的返回結(jié)果中，數(shù)組信息排序與有鍵值名的情況相同。即按照："id","cont","pos","ne","parent","relate","semparent","semrelate","arg"的順序。

arg中信息的順序?yàn)?id","type","beg","end"。

注意！依存句法分析結(jié)果中并不具有ne信息。同樣，語義依存分析也不具有ne信息。

CONLL

對文本進(jìn)行全部任務(wù)的分析示例如下：

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中國人。&pattern=all&format=conll

返回結(jié)果為：

0 我 _ _ r O 1 SBV _ _ _ (A0*)
1 是 _ _ v O -1  HED _ _ 是 (v*)
2 中國  _ _ ns  S-Ns  3 ATT _ _ _ (A1*
3 人 _ _ n O 1 VOB _ _ _ *)

conll是一種表示語言分析結(jié)果的通用格式。在語言云的conll格式中，分析結(jié)果的每一行代表句子中每個詞的信息，詞標(biāo)號從0開始。分析結(jié)果的基礎(chǔ)列有10列，之后的每一列代表文本中的語義信息，每列之間用Tab分割。此列值為空用"_"占位。conll每列的含義請見下表：

注意！CONLL格式中不包含語義依存分析結(jié)果

正常情況下，用戶將得到正確的結(jié)果，此時HTTP狀態(tài)為200 OK 。

$ curl -i "http://api.ltp-cloud.com/analysis/?{ValidParameters}"
HTTP/1.1 200 OK
...

但如果用戶調(diào)用API的方式不當(dāng)，服務(wù)器將會返回對應(yīng)的錯誤，錯誤信息如下表所示:

舉個例子，401 Unauthorized錯誤的返回示例如下：

$  curl -i "http://api.ltp-cloud.com/analysis/?api_key=InvalidApiKey"
HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
...
{"error_message": "UNAUTHORIZED USER"}

為保障系統(tǒng)穩(wěn)定，語言云API的使用頻率默認(rèn)限制為每個IP 200次/秒。

超過此限制，將會被返回503 Service Unavailable錯誤。

1.關(guān)于如何自定義分詞

語言云允許用戶自定義分詞，并在此基礎(chǔ)上進(jìn)行更深層次的語言分析。用戶需指定參數(shù)xml_input=true，分詞結(jié)果需要以XML的表示方式指定在text參數(shù)中。用戶必須使用POST方式開展此項(xiàng)功能。

2.關(guān)于如何一次性分析大量文本以及文本中含有特殊字符的處理

語言云支持一次性分析較大規(guī)模的文本。但也做了一些限制。GET方式每次最多攜帶10K大小文本，POST方式每次最多攜帶20K大小文本，且只支持UTF-8格式。超出限制，系統(tǒng)將會向您返回錯誤信息并提示您進(jìn)行縮減。

在語言云默認(rèn)的設(shè)定中，依靠換行符對文本進(jìn)行劃分段落，表現(xiàn)的結(jié)果是含有多個para對象。在GET方式中，由于URL對特殊字符的限制，將換行符直接放在URL中可能會有錯誤。所以強(qiáng)烈建議用戶不要在文本中攜帶換行符，推薦只輸入一段話，并且依靠結(jié)尾標(biāo)點(diǎn)來劃分句子。如果您確實(shí)需要分段，語言云提供給您三種途徑：第一，使用POST方式；第二，使用 替代換行符作為分割段落的標(biāo)志；第三，GET方式中，事先對文本進(jìn)行url encode再發(fā)送請求。

同樣，請盡量不要在GET方式的參數(shù)text中攜帶其他特殊字符。如果必須攜帶且該字符可進(jìn)行url encode，請使用%加字符的ASCII碼替代或者直接進(jìn)行url encode。譬如：'&'字符使用'&'替代。否則，請刪除該特殊字符以獲得正確結(jié)果。

3.關(guān)于使用JSON格式進(jìn)行二次開發(fā)的重要說明

Json格式是語言云著重推薦使用的返回格式。如果以上結(jié)果表示依然不能滿足您的需要，您 需要從中提取出對自己有用的分析信息，json無疑是您的首選。在各編程語言中，幾乎都有提供json格式的解析庫。

在語言云返回的json格式中，是以段落級、句子級、單詞級的遞進(jìn)層次關(guān)系標(biāo)識的，段落級別和句子級別并沒有進(jìn)行鍵值名標(biāo)識，因而須采用數(shù)組下標(biāo)方式獲取信息。 比如說，p代表json結(jié)果，在python中，獲取第一段第二句第三個單詞的詞性信息，獲取方式類似于p[0][1][2]["pos"]。如果您的文本中沒有明顯的劃分段落的標(biāo)志，默認(rèn)只有一個段落，句子依靠標(biāo)點(diǎn)符號進(jìn)行劃分。