简介

语言云新版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参数集如下表所示：

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

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

调用方式

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

• 直接使用REST

• 在JavaScript中使用REST

REST

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

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

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

GET请求及返回结果示例：

$ curl -i "http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=dp&format=plain"HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 04:24:32 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encoding我_0 是_1 SBV是_1 -1 HED中国_2 人_3 ATT人_3 是_1 VOB

POST请求及返回结果示例：

$ curl -i -d "api_key=YourApiKey&text=我是中国人。&pattern=dp&format=plain" "http://ltpapi.voicecloud.cn/analysis/"HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 05:58:55 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encoding我_0 是_1 SBV是_1 -1 HED中国_2 人_3 ATT人_3 是_1 VOB

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

# -*- coding:utf8 -*-import urllib2if __name__ == ‘__main__‘:    url_get_base = "http://ltpapi.voicecloud.cn/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方式调用REST API代码示例以及注意事项请参考API编程调用示例。

JavaScript调用REST

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

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

$ curl -i "http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=dp&format=json&callback=foo"HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 08:08:56 GMTContent-Type: application/javascriptTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encodingfoo(//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://ltpapi.voicecloud.cn/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调用API的示例，请参考JavaScript调用API示例。

结果表示

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

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

PLAIN

分词

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

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ws&format=plain

返回结果为：

我 是 中国 人 。

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

词性标注

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

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=pos&format=plain

我_r 是_v 中国_ns 人_n 。_wp

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

命名实体识别

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

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ner&format=plain

返回结果为：

我 是 [中国]Ns 人 。

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

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

其调用示例如下：

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ner&format=plain&only_ner=true

返回结果为：

中国 Ns

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

依存句法分析

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

GET http://ltpapi.voicecloud.cn/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://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=srl&format=plain

返回结果为：

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

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

XML

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

GET http://ltpapi.voicecloud.cn/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" wsd="y" srl="y" />    <doc>        <para id="0">            <sent id="0" cont="我们都是中国人">                <word id="0" cont="我们" pos="r" ne="O" parent="2" relate="SBV" />                <word id="1" cont="都" pos="d" ne="O" parent="2" relate="ADV" />                <word id="2" cont="是" pos="v" ne="O" parent="-1" relate="HED">                    <arg id="0" type="A0" beg="0" end="0" />                    <arg id="1" type="AM-ADV" beg="1" end="1" />                </word>                <word id="3" cont="中国" pos="ns" ne="S-Ns" parent="4" relate="ATT" />                <word id="4" cont="人" pos="n" ne="O" parent="2" relate="VOB" />            </sent>        </para>    </doc></xml4nlp>

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

1. xml4nlp 为根结点，无任何属性值；

2. note 为标记结点，具有的属性分别为：sent, word, pos, ne, parser, srl；分别代表分句，分词，词性标注，命名实体识别，依存句法分析，词义消歧，语义角色标注；值为"n"，表明未做，值为"y"则表示完成，如pos="y"，表示已经完成了词性标注；

3. doc 为篇章结点，以段落为单位包含文本内容；无任何属性值；

4. para 为段落结点，需含id 属性，其值从0 开始；

5. sent 为句子结点，需含属性为id，cont；id 为段落中句子序号，其值从0 开始；cont 为句子内容；

6. word 为分词结点，需含属性为id, cont；id 为句子中的词的序号，其值从0 开始，cont为分词内容；可选属性为 pos, ne,parent, relate；pos 的内容为词性标注内容；ne 为命名实体内容；parent 与 relate 成对出现，parent 为依存句法分析的父亲结点id 号，relate 为相对应的关系；

7. arg 为语义角色信息结点，任何一个谓词都会带有若干个该结点；其属性为id, type, beg，end；id 为序号，从0 开始；type 代表角色名称；beg 为开始的词序号，end 为结束的序号；

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

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. 如果 srl="y" 则凡是谓词(predicate)的分词会包含若干个arg 结点；

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

JSON

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

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=all&format=json

返回结果为：

[
 [
  [
   {
    "id": 0, 
    "cont": "我", 
    "pos": "r", 
    "ne": "O", 
    "parent": 1, 
    "relate": "SBV", 
    "arg": []
   }, 
   {
    "id": 1, 
    "cont": "是", 
    "pos": "v", 
    "ne": "O", 
    "parent": -1, 
    "relate": "HED", 
    "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", 
    "arg": []
   }, 
   {
    "id": 3, 
    "cont": "人", 
    "pos": "n", 
    "ne": "O", 
    "parent": 1, 
    "relate": "VOB", 
    "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 为相对应的关系；

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

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

GET http://ltpapi.voicecloud.cn/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=all&format=json&has_key=false

返回结果为：

[[[[0, "我", "r", "O", 1, "SBV", []], [1, "是", "v", "O", -1, "HED", [[0, "A0", 0, 0], [1, "A1", 2, 3]]], [2, "中国", "ns", "S-Ns", 3, "ATT", []], [3, "人", "n", "O", 1, "VOB", []]]]]

在json格式的无键值名的返回结果中，数组信息排序与有键值名的情况相同。即按照："id","cont","pos","ne","parent","relate","arg"的顺序。

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

注意！依存句法分析结果中并不具有ne信息。

CONLL

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

GET http://ltpapi.voicecloud.cn/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每列的含义请见下表：

错误响应

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

$ curl -i "http://ltpapi.voicecloud.cn/analysis/?{ValidParameters}"HTTP/1.1 200 OK...

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

举个例子，401 Unauthorized错误的返回示例如下：

$  curl -i "http://ltpapi.voicecloud.cn/analysis/?api_key=InvalidApiKey"HTTP/1.1 401 UNAUTHORIZEDContent-Type: application/json...{"error_message": "UNAUTHORIZED USER"}

频率限制

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

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

重要说明

1.关于如何自定义分词

语言云允许用户自定义分词，并在此基础上进行更深层次的语言分析。用户需指定参数xml_input=true，分词结果需要以XML的表示方式指定在text参数中。用户必须使用POST方式开展此项功能。

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"]。如果您的文本中没有明显的划分段落的标志，默认只有一个段落，句子依靠标点符号进行划分。

LTP语言云API使用文档

原文：http://my.oschina.net/airship/blog/380593