开发 云图服务API 参考手册 云存储API

云存储API 最后更新时间: 2021年05月08日

云存储API,即HTTP型请求API,适用服务端、Web端、移动端实现数据存储。实现步骤如下:

第一步: 创建表,即您创建了一个地图(返回参数tableid,即创建的地图的唯一标识); 第二步:创建单条数据或批量创建数据。 其他更多操作,如删除、更新数据详见如下参考手册。

特别说明: 

Web端(网站或H5页面)、移动端开发(APP): 

数据存储需使用云存储API或者云图数据管理台手工操作;JavaScript API、Android/iOS地图SDK中的云图功能仅提供数据检索功能以及数据的展现。

创建表 

创建一个存储用户数据的表,等同于在数据管理台手工创建一个地图(一张云图)。

  • 创建表请求

请求地址:

https://yuntuapi.amap.com/datamanage/table/create

服务协议:HTTP/HTTPS  POST。

  • Content-Type

application/x-www-form-urlencoded

  • 请求参数

名称

含义

规则说明

参数类型

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

string(32)

必填

name

表的名称

支持任意中英文字符、数字、下划线

string(50)

必填

sig

数字签名

数字签名获取和使用方法

string(280)

可选,选择数字签名认证的用户必填

  •  返回结果参数说明

名称

说明

是否必须返回

status

返回状态

取值规则:

1:成功;

0:失败,未知原因;

-11:失败,已存在相同名称表

-21:失败,已创建表达到最大数据

必须

info

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明。

必须

tableid

生成的数据表的唯一标识(该参数是发起数据存储API以及检索API的必填参数)

该参数,您还通过登录云图数据管理台,手工创建地图获得, 获取table id方法说明

必须

  •  请求示例
  •  示例返回结果
{ 
"info":"OK", 
"status":1, 
"tableid":"53a4093fe4b0a4a84f9b66cf" 
}

创建数据(单条) 

向指定tableid的数据表中插入一条新数据。

请求地址:

https://yuntuapi.amap.com/datamanage/data/create

服务协议:HTTP/HTTPS  POST.

  • Content-Type

application/x-www-form-urlencoded

  • 请求参数

名称

含义

规则说明

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

必填

tableid

数据表唯一标识

获取tableid方法说明

必填

loctype

定位方式

设置是以请求中的经纬度参数(_location)还是地址参数(_address)

来计算最终的坐标值。

可选值:

1:经纬度;格式示例:104.394729,31.125698

2:地址;标准格式示例:北京市朝阳区望京阜通东大街6号院3号楼

可选

1

data

新增的数据

创建的数据

规则:json

必填


_name

数据名称

类型:string

必填

_location

坐标

类型:string

支持点数据

规则:经度,纬度,经纬度支持到小数点后6位               格式示例:104.394729,31.125698

当loctype=1时,必填

coordtype

坐标类型

类型:string

可选值:

1: gps

2: autonavi

3: baidu

您可输入coordtype=1,或者autonavi

可选

autonavi

_address

地址

类型:string

当loctype=2时,必填

<customfield1>

用户自定义字段1



<customfield…>

用户自定义字段…



sig

数字签名

数字签名获取和使用方法

选择数字签名认证的用户必填

  • 返回结果参数说明

名称

说明

是否必须返回

status

返回状态

取值规则:1:成功;0:失败

必须

info

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明

必须

_id

成功创建的数据id

必须

  • 请求示例
  • 示例返回结果
{ 
"info":"OK", 
"status":1, 
"_id":"283" 
}

创建数据(批量) 

向指定tableid的数据表中通过上传文件的方式创建多条数据。该接口为异步接口,请求后立即返回后台进程batchid,通过批量创建数据进度查询接口查看任务执行进度和结果。

  • 批量创建数据请求

请求地址:

https://yuntuapi.amap.com/datamanage/data/batchcreate

服务协议:HTTP/HTTPS  POST.

  • Content-Type

multipart/form-data

  • 请求参数

名称

含义

规则说明

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

必填

tableid

数据表唯一标识

获取table id方法说明

必填

file

新增的数据文件

规则:

文件格式:csv文件的二进制流,使用UTF8、GBK编码,字段总数不超过40个;

数据量不超过10000条且文件大小不超过10M;

3)字段命名规则:以英文字母开头,仅由英文字母、数字、下划线组成,总长度不超过20位;

必填

_name

文件中代表”名称”的字段


必填

loctype

定位方式

设置是以文件中的经纬度字段还是地址字段来计算最终的坐标。

可选值:

1:经纬度;格式示例:104.394729,31.125698

2:地址

可选

1

_address

文件中代表”地址”的字段


当loctype=2时,必填

longitude

文件中代表”经度”(格式示例:104.394729)的字段


当loctype=1时,必填

latitude

文件中代表”纬度”(格式示例:31.125698)的字段


当loctype=1时,必填

coordtype

坐标类型

类型:string

可选值:

1: gps

2: autonavi

3: baidu

您可输入coordtype=1,或者autonavi

可选,

仅当定位方式loctype=1时,该字段有效

autonavi

sig

数字签名

数字签名获取和使用方法

选择数字签名认证的用户必填

  • 返回结果参数说明

名称

说明

是否必须返回

status

返回状态。

值为0或1。

1:成功;

0:失败

必须

info

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明

必须

batchid

本次批处理任务的唯一标识。

若批量处理任务创建成功,则返回该任务的唯一标识batchid。

用户使用批量处理进度查询接口可查询该batchid对应的任务处理进度和结果。

每个batchid的有效期为:处理结束后1小时内。

可选

  • 请求示例

上传文件sample.csv示例:

  • 示例返回结果
{ 
"info":"OK", 
"status":1, 
"batchid":52b2ba09e4b0490b86c07ba7
}

更新数据(单条) 

更新指定tableid,指定一条数据序列号_id的数据信息。

  • 更新数据请求

请求地址:

https://yuntuapi.amap.com/datamanage/data/update

服务协议:HTTP/HTTPS  POST.

  • Content-Type

application/x-www-form-urlencoded

  • 请求参数

名称

含义

规则说明

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

必填

tableid

数据表唯一标识

获取table id方法说明

必填

loctype

定位方式

设置是以请求中的经纬度参数(_location)还是地址参数(_address)来计算最终的坐标值。

可选值:

1:经纬度;格式示例:104.394729,31.125698

2:地址

可选

1

data

新增的数据

1. 格式:json

2. 更新规则:

1)更新字段值:只更新请求中上传的字段值,未上传的字段保留原值,且系统字段中_id,_createtime,_updatetime三个字段不能被更新。

data={"_id":"3","_location":"113.484733,37.837432"},则本次请求仅更新_location字段值,其他字段如_name,_address等其他用户自定义字段将保持原值。

2)清空字段值:赋值null实现,仅能对用户自定义字段值进行清空操作,云图系统字段(_id,_name,_address,_location,_createtime,_updatetime)不能执行清空。

data={"_id":"3","Ctype":null}  //Ctype字段为用户的自定义字段

必填


_id

数据id

类型:string

必填

_name

数据名称

类型:string

可选

_location

坐标

类型:string

支持点数据

规则:经度,纬度,经纬度支持到小数点后6位

格式示例:104.394729,31.125698

可选

coordtype

坐标类型

类型:string

可选值:

1: gps

2: autonavi

3: baidu

您可输入coordtype=1,或者autonavi

可选

autonavi

_address

地址

类型:string

可选

<customfield1>

用户自定义字段1



<customfield…>

用户自定义字段…



sig

数字签名

数字签名获取和使用方法

选择数字签名认证的用户必填

  • 返回结果参数说明

名称

含义

规则说明

是否必须返回

status

返回状态

值为0或1

1:成功;

0:失败

必填

info

返回的状态信息

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明

必填

  • 请求示例
  • 示例返回结果
{ 
"info":"OK", 
"status":1
}

删除数据(单条/批量) 

删除指定tableid的数据表中的数据,一次请求限制删除1-50条数据。

  • 删除数据请求

请求地址:

https://yuntuapi.amap.com/datamanage/data/delete

服务协议:HTTP/HTTPS  POST.

  • Content-Type

application/x-www-form-urlencoded

  • 请求参数

名称

含义

规则说明

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

必填

tableid

数据表唯一标识

获取table id方法说明

必填

ids

删除的数据_id

一次请求限制1-50条数据,多个_id用逗号隔开

必填

sig

数字签名

数字签名获取和使用方法

选择数字签名认证的用户必填

  • 返回结果参数说明

名称

含义

规则说明

是否必须返回

status

返回状态

值为0或1

1:成功;

0:失败

必填

info

返回的状态信息

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明

必填

success

删除成功数目

非负整数

必填

fail

删除失败数目

非负整数

必填

  • 请求示例
  • 示例返回结果
{ 
"info":"OK", 
"status":1, 
"success":1, 
"fail":1
}

批量创建进度查询 

批量处理管理接口为用户提供查看批处理的进度和结果信息。

  • 批量创建数据进度查询

查询指定batchid的批量创建数据后台进程的进度和结果。

  • 进度查询请求

请求地址:

https://yuntuapi.amap.com/datamanage/batch/importstatus?parameters

服务协议:HTTP/GET. parameters代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。

  • 请求参数

名称

含义

规则说明

是否必须

缺省值

key

客户唯一标识

用户申请,由高德地图API后台自动分配

必填

tableid

数据表唯一标识

获取table id方法说明

必填

batchid

批量处理任务唯一标识


必填

sig

数字签名

数字签名获取和使用方法

选择数字签名认证的用户必填

  • 返回结果参数说明

名称

含义

规则说明

是否必须返回

status

返回状态

值为0或1

1:成功;

0:失败

必填

info

返回的状态信息

status = 1,info返回“ok”,详细信息请参考本页最下方的错误码说明

必填

progress

处理进度

取值范围[0,100]

可选

imported

已导入的数据数目

非负整数

可选

locaccurate

定位准确数目

取值范围:非负整数

-  当loctype=1时,只要用户传入合规的经纬度,系统都将认为是准确定位。

-  当loctype=2时,当系统能够根据传入地址精确定位坐标到以下4类结果上时,系统认为是准确定位:

可选

locinaccurate

定位可能偏差数目

取值范围:非负整数

当loctype=2,即用地址进行定位时,会因为地址不够精确或系统地址库缺失,造成系统计算出的坐标可能不在用户所期望的位置,系统将此情形认为“定位可能偏差”。如,当地址为“XX省”或“XX省XX市XX区XX街道”等范围较大的区域时。

此参数主要作为提醒使用,并不影响该条数据的任何操作。

可选

locfail

定位失败数目

取值范围:非负整数

可选

  • 请求示例
https://yuntuapi.amap.com/datamanage/batch/importstatus?tableid=52b155b6e4b0bc61deeb76
29&batchid=52b2ba09e4b0490b86c07ba7&key=<用户key>
  • 示例返回结果
{ 
"info":"OK", 
"progress ":87, 
"imported ":269, 
"locaccurate ":230, 
"locinaccurate ":27 
"locfail ":12, 
}

错误码说明 

stauts(请求状态码)

info(状态码对应说明)

0(请求失败)

info值枚举如下:

table id不存在

_id不存在

服务器维护中

参数缺失或格式非法

账号未激活或已被冻结

UNKNOWN_ERROR:code (code =  -101~-404之间,表示云图服务内部错误;code = -41,表示Key和table id不在同一高德用户账户下,无权访问)

SERVICE_NOT_EXIST (表示:请求的服务不存在)

IN VALID_USER_KEY(表示:key无效)

USER_VISIT_TOO_FREQUENTLY (表示:用户访问过于频繁,服务不响应)

NOT_SUPPORT_HTTPS (表示:不支持HTTPS请求)

INVALID_USER_IP (表示:用户IP无效)

INVALID_USER_SIGNATURE (表示:该服务响应错误)

INVALID_USER_SCode (表示:用户安全码未通过)

未知错误 (以上错误之外的未定义的错误)

注意事项

  • API服务密钥:高德云图存储API使用API密钥来标识用户的应用。服务请求url中的 key 参数为必填参数,需要填入此密钥。所以,使用接口前请 获取Key ,若无高德地图API账号需要先申请账号
  • 编码格式:如无特殊声明,接口的输入参数和输出数据编码全部统一为UTF-8。
返回顶部 示例中心 常见问题 智能客服 公众号
二维码