Back to Top

语言云API使用文档

API介绍及使用说明


语言云新版API是REST风格的WEB API调用服务,REST API服务有诸多优点,这使得它越来越流行。应用于语言云服务中,主要有如下特点:

  • 免SDK安装:REST API的调用无须用户下载SDK,使得语言分析更为便捷。
  • 结果表示格式丰富:API提供了包括PLAIN/XML/JSON/CONLL等多种格式的结果表示。且返回结果容易扩展,便于进行二次开发。
  • 支持JavaScript调用:语言云支持JavaScript以JSON-P回调的方式调用API,使得返回结果可以嵌入到Web页面或者宿主Web应用中。
  • 请求方式多样:语言云提供了HTTP GET和HTTP POST两种方式的调用接口。
  • 用户认证简洁:API_KEY取代了旧版email:token的认证方式,作为用户的统一授权方式。
注意! 以下说明若没有特殊强调均指新版API的特性,旧版API将在一段时间内保留。


已经在语言云注册的用户请留意您注册的邮箱以及您在语言云网站上的控制面板,我们将把您使用语言云API的API_KEY通过以上方式提示给您。

新用户请先在语言云上注册一个帐号。相关信息审核通过后,系统会向您的注册邮箱发送API_KEY和您本月的流量额度,后者将在控制面板实时更新,便于用户进行查看。

email:token作为旧版API的调用认证将在一段时间内保留,APK_KEY作为新版API的调用认证方式。新注册用户将获得每月20G的免费流量。


用户通过指定API参数来获取对应的结果,语言云服务的API参数集如下表所示:

参数名 含义 说明
api_key 用户注册语言云服务后获得的认证标识
text 待分析的文本。 请以UTF-8格式编码,GET方式最大10K,POST方式最大20K
pattern 用以指定分析模式,可选值包括ws(分词),pos(词性标注),ner(命名实体识别),dp(依存句法分析),sdp(语义依存(树)分析),sdb_graph(语义依存图分析)srl(语义角色标注),all(全部任务) plain格式中不允许指定全部任务
format 用以指定结果格式类型,可选值包括xml(XML格式),json(JSON格式),conll(CONLL格式),plain(简洁文本格式) 在指定pattern为all条件下,指定format为xml或json,返回结果将包含sdp结果,但conll格式不会包含sdp结果;
xml_input 用以指定输入text是否是xml格式,可选值为false(默认值),true 仅限POST方式, 详见重要说明-自定义分词
has_key 用以指定json结果中是否含有键值,可选值包括true(含有键值,默认),false(不含有键值) 配合format=json使用
only_ner 用以指定plain格式中是否只需要ner列表,可选值包括false(默认值)和true 配合pattern=ner&format=plain使用
callback 用以指定JavaScript调用中所使用的回调函数名称 配合format=json使用

参数名及对应的参数值区分大小写且不支持缩略形式。

以上参数同时支持且只支持GET和POST两种方式的提交。


用户可以用两种方式来调用API

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

REST

REST,或者叫做Representational State Transfer,在语言云API中并不等同于传统的REST。传统的REST提供对于资源的访问,而语言云REST API提供对于服务的访问。因此,在语言云API中,一个单独的URI就是一个服务端点。

在语言云中,所有的API访问都是通过HTTP请求的方式。并且需要从api.ltp-cloud.com域进行访问。语言云只支持GET和POST方式的HTTP请求。用户通过在HTTP请求中指定参数来获取对应的结果。

举个例子,对“我是中国人。”这句话做依存句法分析,并且返回plain格式的结果。

GET请求及返回结果示例:

$ curl -i -G --data-urlencode text="我是中国人。" -d "api_key=YourApiKey&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 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
。_4 是_1 WP

POST请求及返回结果示例:

$ curl -i --data-urlencode text="我是中国人。" -d "api_key=YourApiKey&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
。_4 是_1 WP

使用Python语言以POST方式调用REST API代码示例如下:

# -*- coding:utf8 -*-
if __name__ == '__main__':
    url_get_base = "http://api.ltp-cloud.com/analysis/"
    args = { 
        'api_key' : 'YourApiKey',
        'text' : '我是中国人。',
        'pattern' : 'dp',
        'format' : 'plain'
    }
    result = urllib.urlopen(url_get_base, urllib.urlencode(args)) # POST method
    content = result.read().strip()
    print content

更多使用其他编程语言以GET和POST方式调用REST API代码示例以及注意事项请参考API编程调用示例

JavaScript调用REST

语言云支持用户使用JavaScript以JSON-P回调的方式调用API,用户需要以GET方式进行调用并且只支持json的返回格式。

在此方式中,需要用户在uri中添加callback参数并且在js中指定相同名称的回调函数进行结果的捕捉,这通常用于跨域访问使得结果嵌入到Web页面中。

$ curl -i -G --data-urlencode text="我是中国人。" -d "api_key=YourApiKey&pattern=dp&format=json&callback=foo" http://api.ltp-cloud.com/analysis/
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中捕捉调用结果代码示例如下:

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 = "YourApiKey";
    var text = "我是中国人。";
    var pattern = "dp";
    var format = "json";
    var callback = "foo";
    var args = "api_key="+api_key+"&text="+text+"&pattern="+pattern+"&format="+format+"&callback="+callback;
    var url = base + encodeURIComponent(args);
    var script = document.createElement('script');
    script.setAttribute('src', url);
    document.getElementsByTagName('head')[0].appendChild(script);
}

语言云也提供了使用Jquery调用API的示例,请参考JavaScript调用API示例


语言云API提供了较为丰富的分析结果表示格式,包括plain,xml,json和conll

注意! 语言云结果表示格式并不等同于HTTP响应头部的Content-Type

PLAIN

分词

对文本进行分词的调用示例如下:

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

返回结果为:

我 是 中国 人 。

在plain格式的分词结果中,每句话占一行。词与词之间用空格分割,句与句之间用换行分割。段落与段落之间用两个换行分割。

词性标注

对文本进行词性标注的调用示例如下:

GET http://api.ltp-cloud.com/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=pos&format=plain
我_r 是_v 中国_ns 人_n 。_wp

在plain格式的词性标注结果中,每句话占一行。词和词的标注信息之间用下划线连接,项与项之间用空格分割,句与句之间用换行分割。段落与段落之间用两个换行分割。

命名实体识别

对文本进行命名实体识别的调用示例如下:

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

返回结果为:

我 是 [中国]Ns 人 。

在plain格式的命名实体识别结果中,每句话占一行。如果本句话含有实体,将会被[]包围,并且在之后添加实体类型标识。段落与段落之间有两个换行符分割。

如果您只想获得文本中的所有的命名实体列表,请用参数only_ner=true来指定。

其调用示例如下:

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

返回结果为:

中国 Ns

在plain格式的命名实体识别列表形式的返回结果中,每个实体信息占一行。每一行有两列,第一列为实体本身,第二列为实体类型。

依存句法分析

对文本进行依存句法分析的调用示例如下:

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

返回结果为:

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

在plain格式的依存句法分析返回结果中,文本中的每个词的句法信息占一行。每一行独占三列。第一列为依存句法分析的孩子结点信息,由结点名+下划线+词id组成;第二列为依存句法分析的父亲节点信息,由结点名+下划线+词id组成,如果没有父亲结点,则由-1表示;第三列为具体的依存句法分析关系。文本句子级别的信息之间用两个换行分割,文本段落级别的信息之间用三个换行分割。

语义依存分析

对文本进行语义依存分析的调用示例如下:

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

返回结果为:


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

在plain格式下返回的语义依存分析结果的格式与依存句法分析格式相同。最后一列显示了语义依存的关系。

语义角色标注

对文本进行语义角色标注的调用示例如下:

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

返回结果为:

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

在plain格式的语义角色标注返回结果中,每个谓词的语义角色信息独占一行,如果一个句子有多个谓词,那么占多行。行与行之间用换行分割,文本句子级别的信息之间用两个换行分割,文本段落级别的信息之间用三个换行分割。

XML

对文本进行全部任务的分析示例如下:

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

返回结果为:


<?xml version="1.0" encoding="utf-8" ?>
<xml4nlp>
    <note sent="y" word="y" pos="y" ne="y" parser="y" semparser="y" lstmsemparser="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">
                    <sem id="0" parent="1" relate="Exp" />
                </word>
                <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" />
                    <sem id="0" parent="-1" relate="Root" />
                </word>
                <word id="2" cont="中国" pos="ns" ne="S-Ns" parent="3" relate="ATT" semparent="3" semrelate="Nmod">
                    <sem id="0" parent="3" relate="Nmod" />
                </word>
                <word id="3" cont="人" pos="n" ne="O" parent="1" relate="VOB" semparent="1" semrelate="Clas">
                    <sem id="0" parent="1" relate="Clas" />
                </word>
            </sent>
        </para>
    </doc>
</xml4nlp>

XML标准结果如下:结点标签分别为 xml4nlp, note, doc, para, sent, word, arg 共七种结点标签:

  1. xml4nlp 为根结点,无任何属性值;
  2. note 为标记结点,具有的属性分别为:sent, word, pos, ne, parser, semparser, lstmsemparser, wsd, srl;分别代表分句,分词,词性标注,命名实体识别,依存句法分析,语义依存(树)分析,语义依存(图)分析,词义消歧,语义角色标注;值为"n",表明未做,值为"y"则表示完成,如pos="y",表示已经完成了词性标注;(注: wsd已不提供支持,该标签将在后续维护中消除)
  3. doc 为篇章结点,以段落为单位包含文本内容;无任何属性值;
  4. para 为段落结点,需含id 属性,其值从0 开始;
  5. sent 为句子结点,需含属性为id,cont;id 为段落中句子序号,其值从0 开始;cont 为句子内容;
  6. word 为分词结点,需含属性为id, cont;id 为句子中的词的序号,其值从0 开始,cont为分词内容;可选属性为 pos, ne, parent, relate , semparent,semrelatepos 的内容为词性标注内容;ne 为命名实体内容;parentrelate 成对出现,parent 为依存句法分析的父亲结点id 号,relate 为相对应的关系;semparentsemrelate 成对出现,semparent 为语义依存树分析的父亲结点id 号,semrelate 为相对应的关系;
  7. arg 为语义角色信息结点,任何一个谓词都会带有若干个该结点;其属性为id, type, begendid 为序号,从0 开始;type 代表角色名称;beg 为开始的词序号,end 为结束的序号;
  8. sem 为语义依存图分析节点,每个节点代表了当前节点的一个父亲节点信息。id, parent, type分别表示序号、父亲节点id、关系类型。

各结点及属性的逻辑关系说明如下:

  1. 各结点层次关系可以从图中清楚获得,凡带有id 属性的结点是可以包含多个;
  2. 如果sent="n"即未完成分句,则不应包含sent 及其下结点;
  3. 如果sent="y" word="n"即完成分句,未完成分词,则不应包含word 及其下结点;
  4. 其它情况均是在sent="y" word="y"的情况下:
    1. 如果 pos="y" 则分词结点中必须包含pos 属性;
    2. 如果 ne="y" 则分词结点中必须包含ne 属性;
    3. 如果 parser="y" 则分词结点中必须包含parent 及relate 属性;
    4. 如果 semparser="y" 则分词结点中必须包含semparent 及semrelate 属性;
    5. 如果 lstmsemparser="y" 则分词结点中必须包含若干个sem节点;
    6. 如果 srl="y" 则凡是谓词(predicate)的分词会包含若干个arg 结点;

在XML格式的分析中,用户可以通过指定参数pattern=ws | pos | ner | dp | sdp | sdp_graph | srl | all 来指名分析任务并获取对应的XML结果。

JSON

对文本进行全部任务的分析示例如下:

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

返回结果为:


[
  [
    [
      {
        "id": 0,
        "cont": "我",
        "pos": "r",
        "ne": "O",
        "parent": 1,
        "relate": "SBV",
        "semparent": 1,
        "semrelate": "Exp",
        "arg": []
      },
      {
        "id": 1,
        "cont": "是",
        "pos": "v",
        "ne": "O",
        "parent": -1,
        "relate": "HED",
        "semparent": -1,
        "semrelate": "Root",
        "arg": [
          {
            "id": 0,
            "type": "A0",
            "beg": 0,
            "end": 0
          },
          {
            "id": 1,
            "type": "A1",
            "beg": 2,
            "end": 3
          }
        ]
      },
      {
        "id": 2,
        "cont": "中国",
        "pos": "ns",
        "ne": "S-Ns",
        "parent": 3,
        "relate": "ATT",
        "semparent": 3,
        "semrelate": "Nmod",
        "arg": []
      },
      {
        "id": 3,
        "cont": "人",
        "pos": "n",
        "ne": "O",
        "parent": 1,
        "relate": "VOB",
        "semparent": 1,
        "semrelate": "Clas",
        "arg": []
      },
      {
        "id": 4,
        "cont": "。",
        "pos": "wp",
        "ne": "O",
        "parent": 1,
        "relate": "WP",
        "semparent": 1,
        "semrelate": "mPunc",
        "arg": []
      }
    ]
  ]
]

JSON (JavaScript Object Notation) 是一种常见的,与语言无关的数据格式,提供任意数据结构的简单表示。

在json格式的返回结果中,采用段落级、句子级、单词级的递进层次关系,且段落与句子并没有进行键值名标识,因而须采用数组下标方式获取信息。

比如说,p代表json结果,获取第一段第二句第三个单词的词性信息,获取方式类似于p[0][1][2]["pos"]。

json格式是语言云重点推荐给用户的语言分析结果格式,有关更多使用方法,请参考语言云提供的JSON格式的重要说明

在json格式的单词对象{}中,需含键值名为id, cont;id 为句子中的词的序号,其值从0 开始,cont为分词内容;可选键值名为 pos, ne, parent, relate;pos 的内容为词性标注内容;ne 为命名实体内容;parent 与 relate 成对出现,parent 为依存句法分析的父亲结点id 号,relate 为相对应的关系;semparent 与 semrelate 成对出现,semparent 为语义依存分析的父亲结点id 号,semrelate 为相对应的关系;

如果用户做了srl级别的分析,json结果中还会有键值名arg所标识的数组。数组中的每个对象是一项语义角色,任何一个谓词都会带有若干个该对象;其键值名为id, type, beg,end;id 为序号,从0 开始;type 代表角色名称;beg 为开始的词序号,end 为结束的序号;如果单词没有语义角色信息,arg所标识的数组为空。

用户也可以通过指定参数has_key=false来去掉键值名,示例如下:

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

返回结果为:


[[[[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格式的无键值名的返回结果中,数组信息排序与有键值名的情况相同。即按照:"id","cont","pos","ne","parent","relate","semparent","semrelate","arg"的顺序。

arg中信息的顺序为"id","type","beg","end"。

注意!依存句法分析结果中并不具有ne信息。同样,语义依存分析也不具有ne信息。

CONLL

对文本进行全部任务的分析示例如下:

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

返回结果为:

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是一种表示语言分析结果的通用格式。在语言云的conll格式中,分析结果的每一行代表句子中每个词的信息,词标号从0开始。分析结果的基础列有10列,之后的每一列代表文本中的语义信息,每列之间用Tab分割。此列值为空用"_"占位。conll每列的含义请见下表:

列号 含义
1 单词在句子中的标号,从0开始
2 单词本身
3
4
5 单词词性标注信息
6 依存句法关系中的父亲节点标号
7 依存句法关系类型
8
9
10 如果单词是语义角色标注中的谓词,则为单词本身,否则为空
11及以后 每个谓词占一列,每一列为该谓词的语义角色标注信息

注意!CONLL格式中不包含语义依存分析结果


正常情况下,用户将得到正确的结果,此时HTTP状态为200 OK

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

但如果用户调用API的方式不当,服务器将会返回对应的错误,错误信息如下表所示:

HTTP状态码 错误信息 说明
400 Bad Request URI PARAMETER ERROR API参数错误。请确保参数符合API参数集规范并且text中含有的特殊字符已经进行了调整。
EMPTY SENTENCE text参数不允许为空。
ENCODING NOT IN UTF8 text编码错误。请确保使用UTF8编码。
BAD XML FORMAT 输入的XML格式不正确,请参考XML格式进行调整。
SENTENCE TOO LONG 输入某句子超过300字或分词结果超过70词。
401 Unauthorized UNAUTHORIZED USER API_KEY不合法,用户认证不被通过。
403 Forbidden ACCOUNT OUT OF QUOTA 本月流量使用超过该帐号配额,请联系管理员进行扩充。
405 Method Not Allowed HTTP METHOD ERROR 该HTTP动作不被允许,系统只允许GET和POST方式的HTTP请求。
414 Request-URI Too Long TEXT TOO LARGE ERROR 文本大小超过服务器限制,GET方式最大10K,POST方式最大20K。
500 Internal Server Error SERVER ERROR 服务器内部错误。若稍候尝试仍然有此错误,请将URI用例报告给管理员
503 Service Unavailable API RATE LIMIT EXCEEDED API请求频率超过了语言云的限制。请参考频率限制

举个例子,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"}

为保障系统稳定,语言云API的使用频率默认限制为每个IP 200次/秒

超过此限制,将会被返回503 Service Unavailable错误。


1.关于如何自定义分词

语言云允许用户自定义分词,并在此基础上进行更深层次的语言分析。用户需指定参数xml_input=true,分词结果需要以XML的表示方式指定在text参数中,特别地,注意note标签内各个属性的值,必须与输入的xml内容想一致。用户必须使用POST方式开展此项功能。由于xml手工构造不是很方便,建议通过编程语言来完成该调用。Python语言的方法可见Python-自定义分词输入

2.关于如何一次性分析大量文本以及文本中含有特殊字符的处理

语言云支持一次性分析较大规模的文本。但也做了一些限制。GET方式每次最多携带10K大小文本,POST方式每次最多携带20K大小文本,且只支持UTF-8格式。超出限制,系统将会向您返回错误信息并提示您进行缩减。

在语言云默认的设定中,依靠换行符对文本进行划分段落,表现的结果是含有多个para对象。在GET方式中,由于URL对特殊字符的限制,将换行符直接放在URL中可能会有错误。所以强烈建议用户不要在文本中携带换行符,推荐只输入一段话,并且依靠结尾标点来划分句子。如果您确实需要分段,语言云提供给您三种途径:第一,使用POST方式;第二,使用%0A替代换行符作为分割段落的标志;第三,GET方式中,事先对文本进行url encode再发送请求。

同样,请尽量不要在GET方式的参数text中携带其他特殊字符。如果必须携带且该字符可进行url encode,请使用%加字符的ASCII码替代或者直接进行url encode。譬如:'&'字符使用'%26'替代。否则,请删除该特殊字符以获得正确结果。

3.关于使用JSON格式进行二次开发的重要说明

Json格式是语言云着重推荐使用的返回格式。如果以上结果表示依然不能满足您的需要,您需要从中提取出对自己有用的分析信息,json无疑是您的首选。在各编程语言中,几乎都有提供json格式的解析库。

在语言云返回的json格式中,是以段落级、句子级、单词级的递进层次关系标识的,段落级别和句子级别并没有进行键值名标识,因而须采用数组下标方式获取信息。 比如说,p代表json结果,在python中,获取第一段第二句第三个单词的词性信息,获取方式类似于p[0][1][2]["pos"]。如果您的文本中没有明显的划分段落的标志,默认只有一个段落,句子依靠标点符号进行划分。