欢迎使用AIPS3.0用户接口文档

除了您现在看到的这个在线版本，您还可以前往以下网址下载：

PDF格式AIPS3.0接口帮助文档

什么是 AIPS3.0

AIPS3.0 介绍

1. AIPS3.0接口特点

• 让用户快速搭建平台管理终端设备；
• 让用户快速便捷地投放多媒体广告；

AIPS3.0用户接口文档将帮助用户通过HTTPS协议实现如下功能：

• 获取指定GPS位置附近的终端设备
• 获取终端设备运行时长和运行里程
• 向指定终端设备投放公益和商业广告
• 获取所有终端设备播放记录

2. AIPS3.0接口访问方法

AIPS3.0接口使用HTTPS的POST方法获取数据，请求地址的一般格式为：
https://[WEBSITE]/p/taxi.TaxiPublisher/[API]
其中[WEBSITE]为服务器地址，[API]为需要请求的API接口名称，已开放的API接口目录如下：

WEBSITE地址需要通过如下方式获取：
发送邮件至sdk@xixunled.com
POST请求头需包含用户身份验证字符串，用户身份验证字符串在https://deerclick.com.cn网站注册登录成功后即可取得。
POST请求参数和返回参数均为JSON数据格式。

4. 接口访问举例

暂无

AIPS3.0接口详细说明

注意：

• HTTPS类型接口均为POST请求，请求地址格式为：
  https://[WEBSITE]/p/taxi.TaxiPublisher/[API]
• 所有POST请求的报文头中必须包含一个名为"Authorization"的头部字段，其对应的值为用户从AIPS3.0平台下载的授权身份凭证字符串。如何获取凭证请[参考这里]。
• 所有POST的请求参数使用JSON格式字符串放在BODY中。
• 所有POST的返回数据使用JSON格式字符串放在BODY中。

1. BindTaxiLicence

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/BindTaxiLicence；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "xixun_id":"设备序列号", //string类型
  "licence":"车辆牌照" //string类型
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口可以将指定设备与一个唯一的用户标识（如车牌号）关联。后面所有对设备的操作均使用licence作为操作对象的标识。

2. QueryTaxiRunningTime

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/QueryTaxiRunningTime；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "taxi_id":"licence" //string类型。taxi_id传入接口1中绑定的licence
  }
• 应答数据格式：
  {
  "runing_time":0 //double类型。
  }
• 接口功能说明：
  该接口通过传入设备唯一标识（接口1中绑定的licence），返回设备累计正常运行时长，单位秒。

3. QueryTaxiMileage

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/QueryTaxiMileage；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "taxi_id":"licence", //string类型
  "begin_at":0 //int64类型
  }
• 应答数据格式：
  {
  "mileage":0 //double类型
  }
• 接口功能说明：
  该接口通过传入设备唯一标识（接口1中绑定的licence）和起始查询时间，begin_at为int64类型的时间戳，单位毫秒。返回设备从指定时间开始的运行里程，单位米。

4. QueryTaxiLocation

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/QueryTaxiLocation；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "list_taxi_id" :["licence1", "licence2", ...] //string类型数组
  }
• 应答数据格式：
  {
  "list_location"：[{"taxi_id":"", "longitude":"", "latitude":"", "distance":""}]
  }
• 接口功能说明：
  该接口可以指定多个设备的唯一标识（如车牌号）作为查询条件，返回每个设备当前所处的GPS坐标。返回数据中的list_location是一个JSON字符串数组，taxi_id是设备唯一标识，longitude和latitude是经纬度（WGS84坐标系），类型均为string。distance无意义可忽略。

5. QueryNearbyTaxi

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/QueryNearbyTaxi；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "longitude":0.0, //double类型，经度
  "latitude":0.0, //double类型，维度
  "radius": 0, //int32类型，指定半径范围
  "limit":10 //int32类型，限定查询结果的数量
  }
• 应答数据格式：
  {
  "list_location":[{"taxi_id":"licence", "longitude":"0.0", "latitude":"0.0", "distance":"2000"}]
  }
• 接口功能说明：
  该接口可以传入longitude和latitude作为圆心的GPS坐标和radius指示的半径（单位米）作为查询条件，返回GPS坐标在这个范围内的设备。如果查询结果数量大于limit，则按distance从小到大排列返回limit个设备信息。
  返回数据中的list_location是一个JSON字符串数组，taxi_id是设备唯一标识，longitude和latitude是当前设备经纬度，distance为设备到圆心的距离，单位米。
  如无特别说明，接口中涉及的GPS坐标均为WGS84坐标系。

6. UpsertPeriodPrice

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/UpsertPeriodPrice；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "price_list":[{"period":"00:00-11:59", "price":1.0}, {"period":"12:00-23:59", "price":2.0}]
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口可以设置各个时段的广告投放价格，price_list是时段定价的数组，period指定开始和结束时间，price为定价。
  结合接口7中用户的广告投放预算平衡用户广告每日播放次数和总投放量。如果不是用接口7，则可以忽略该接口。

7. Advertising

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/Advertising；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "ad_id" :"123", //string类型，广告ID；
  "meta" :"iamge", //string类型，image为图片，video为视频，text为文本；
  "resource" :"http://download_url.com", //string类型，如果meta为text，resource为文字内容，\n换行，\r分页；meta不为text则resource为文件下载url；
  "template" :"", //string类型，meta为text时，template为文字显示背景，暂时忽略不用；
  "longitude" :0.0, //double类型，广告允许显示区域的经度；
  "latitude" :0.0, //double类型，广告允许显示区域的纬度；
  "radius" :0, //int32类型，广告允许显示区域的半径；
  "total_budget" :100.0,//double类型，广告投放总预算；
  "daily_budget" :10.0,//double类型，广告投放每日预算；
  "view_type" :1,//int32类型，meta为text时，1，2，3分别表示单页，滚动和两页显示；
  "list_period" :["01:00-03:00","18:00-19:00"]//string类型数组，指定允许播放的时段。
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口可以将商业广告投放到用户所属的设备上。广告类型可以是文字、图片和视频中任一种。
  该接口未指定具体播放的设备，只要和服务器正常通信的设备都有可能收到该播放任务，设备根据限定的longitude，latitude和radius判断是否应播放该广告。
  服务器根据设备回传的播放记录、广告投放预算来通知设备继续播放或停止播放。
  接口调用成功后投放状态为发布（状态码1），调用接口9可以变更已投放广告的状态。

8. CustomizedShow

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/CustomizedShow；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "ad_id" :"123",//string类型，广告ID；
  "meta" :"image",//string类型，image图片，video视频，text文本；
  "resource" :"http://download_url.com", //string类型； //string类型，如果meta为text，resource为文字内容，\n换行，\r分页；meta不为text则resource为文件下载url；
  "template" :"", //string类型，暂时忽略不用；；
  "view_type" :1, //int32类型，meta为text时，1，2，3分别表示单页，滚动和两页显示；
  "funny" :true, //boolean类型，true则为插播信息，只显示一次。否则为公益广告，永久播放；
  "list_licence" :["licence1","licence2",...]//字符串数组，指定播放该内容的设备标识；
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口可以将普通广告或插播信息投放到list_licence指定的设备上。广告类型可以是文字、图片和视频中任一种。
  当Advertising和当CustomizedShow同时存在于同一设备中，funny=true的CustomizedShow优先级最高，其次是Advertising，当没有其他内容可播放时才播放funny=false的CustomizedShow；
  接口调用成功后投放状态为发布（状态码1），调用接口9可以变更已投放广告的状态。

9. UpdateAdStatus

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/UpdateAdStatus；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "ad_id":"123", //string类型，广告ID；
  "ad_status":1 //int32类型，变更后的状态：1发布，2暂停，3终止
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口变更指定广告的投放状态，Advertising和当CustomizedShow两种类型的广告均适用。

10. SetAddressToSaveAdLog

• 接口地址：https://[WEBSITE]/p/taxi.TaxiPublisher/SetAddressToSaveAdLog；
• 请求头格式："Authorization":"用户从AIPS3平台下载的授权身份凭证字符串"；
• 请求参数格式：
  {
  "address":"http://userserver.com/upload_record //string类型
  }
• 应答数据格式：
  {
  "result":0/1 //int类型。0表示失败，1表示成功
  }
• 接口功能说明：
  该接口可以给AIPS3平台设定一个http POST方法，从AIPS3平台获取用户设备的播放记录。
  回传日志数据为JSON格式：
  {
  "records":
  [{
  "fadid":"123", //string类型
  "fplaycaridnum":"licence", //string类型
  "ffee":2, //float64类型
  "fplaydatetime":1542178020, //int64类型，单位秒
  "fequipid":"device_SN" //string类型，设备序列号
  }]
  }
  用户端收到数据成功后需要在应答的body中包含SUCCESS字符串，否则AIPS3会尝试再次发送数据直到成功为止。

上海熙讯电子科技有限公司 研发部
2018-11-29