接口文档

Appearance

一、查询历史数据接口 ​

概述 ​

本接口用于查询历史数据，不提供实时数据查询操作。数据不永久保存，定时删除，因此每次查询接口后需保存数据到自己平台再利用。

建议一天或一小时调用一次接口，每次调用接口时将 start_time 设置为上次成功获取数据的时间。

数据保留策略 ​

  • 系统保留每个设备每天至少一条抄表数据。
  • 完整抄表数据保存一个月左右后，超出时间不定期删除，接入方应及时保存，超出一个月的数据，可以到系统中查询，系统保留每个设备每天至少一条抄表数据。
  • 所有数据来源于本站手动操作或定时抄表，存放于本站数据库。

接口地址：

http://api1.tqdianbiao.com/Api/DataRequest

接口调用频率： ​

- 根据后台定时抄表的配置来设计  ```推荐一小时一次```

定时抄表 ​

  • 后台有定时任务抄表功能，如果后台没有设置，请手动设置。
  • 接口的历史抄表数据，依赖于后台定时任务。
  • 参数都对，没有数据？
    • 确认系统中有没有数据，检查是否设置好了定时抄表，或许是系统没有抄表导致没有数据产生。
    • 检查参数，检查过了？ 请再检查一遍（）90%的情况接口传参错误）。
  • 历史抄表数据不对? ---- 检查接口参数、是否有删除表、检查下接口参数 接口文档
  • 数据有延迟？ ----- 一般是信号不好导致、属于正常情况。
  • 电表是抄表，水表部分是抄表，部分是主动上报
    • 4G、NB 水表是设置上报周期 其余通过系统抄表
  • 是否可以关闭水表的上报限制？ ---- 不可以,主要考虑电池续航，
  • 接入方是否需要定时调用 异步抄表接口？ （不需要，抄表历史数据接口即可）
  • 可不可以取消后台的定时抄表？只通过异步接口抄表 ---- 不可以（这是愚蠢的），后台定时任务是必须的。系统数据更新，报表计算都依赖于定时抄表。

参数说明： ​

字段名变量名类型描述
授权码auth是String(32)
返回类型type否String
功能idfunctionids否String
起始时间start_time否String(19)
结束时间end_time否String(19)
偏移位置offset否int
返回数据量limit否int

带全部参数的请求样例： ​

json
/Api/DataRequest?type=json&auth=123456789&offset=100&functionids=3,4,5&limit=500&start_time=2017-01-01%2000:00:00&end_time=2018-01-01%2000:00:00

功能分类(ID 对应功能(type字段))： ​

功能ID描述备注
3正向有功总电能,对应时间的总用电量。获取每日用电量未计算倍率 获取倍率
253电表状态详情(新)
4反向有功总电能无特殊需求一般不需要（不要纠结）
5组合无功1总电能无特殊需求一般不需要（不要纠结）
6组合无功2总电能无特殊需求一般不需要（不要纠结）
15ABC三相电压
16ABC三相电流
17ABC三相有功功率
18ABC三相无功功率
22剩余金额
27A相电流
28B相电流
29C相电流
30A相电压
31B相电压
32C相电压
33瞬时有功功率
34瞬时无功功率
42水表数据
98水表剩余金额一般在水表数据中 有提供，水表数据更详细

失败返回（以json为例）： ​

json
{
    "status": 0,
    "msg": "授权码为空",
    "err_code": 100
}

成功返回： ​

MBus有线水表 水表数据示例
json
[
    {
        "fid": 42,
        "value": [
            "0.0",
            "0.0",
            "0.0"
        ],
        "dsp": "总用量：0.0 m³ 剩余量：0.0 m³ 总购量：0.0 m³ 阀门状态：Off"
    }
]
19500 ： NS-Lora普通预付费水表
json

[
    {
        "fid": 42,
        "value": [
            "7.740|7.740|192.56"
        ],
        "dsp": "总用量:7.740m³ 阀门状态:On 电压:3.7V 当前单价:1.00元\/m³ 余额:192.56元 结算周期用量:0.310m³\/192.56元 累计充值:200.00元 信号强度:-62 "
    }
]
NS-无线普通预付费水表
json
[
    {
        "fid": 42,
        "value": [
            "8953.600|0.000|0.00"
        ],
        "dsp": "后付费模式 总用量:8953.600m³ 累计正向流量:8922.490m³ 日最大流量:8.000m³\/h 最大流量发生时间:2025\/1\/3 2:40:55 电压:3.59V rsrp:0,snr:0,ecl:0,csq:25 结算周期用量:0.000m³ 剩余金额:0.00元 总充值:0.00元 阀门状态:On "
    }
]
多费率电表正向有功总电能
json
{
    "status": 1,
    "total": "5503",
    "data": [
        {
            "id": "3911",
            "mid": "1190263",
            "fid": 3,
            "data": [
                "000067.56",
                "000010.60",
                "000015.53",
                "000022.28",
                "000019.15"
            ],
            "dsp": "总 : 67.56 kWh,尖 : 10.6 kWh,峰 : 15.53 kWh,平 : 22.28 kWh,谷 : 19.15 kWh",
            "add_time": "2017-03-27 22:37:17",
            "consume": "3.61",
            "cid": "20170208051",
            "address": "201688889253",
            "uid": "234",
            "name": "某某某",
            "idnum": "147258369147258369"
        }
    ]
}
json
[
    {
        "fid": 3,
        "value": [
            "000067.56"
        ],
        "dsp": "67.56 kWh",
        ...
    }
]

返回字段说明： ​

数组每一列数据： ​

字段名变量名类型描述
唯一标识idString3911
采集时间add_timeString(19)2017-07-23 22:22:31
采集耗时consumeString3.61
采集器标识cidString20170208051
电表档案idmidString1190263
表地址addressString201688889253
用户标识uidString234
用户名字nameString某某某
用户身份证号idnumString147258369147258369
功能类型fidint3
数据dataList[ "000067.56", "000010.60", "000015.53", "000022.28", "000019.15"]
数据data_v2stringdata_v2字段
解释数据dspString总 : 67.56 kWh,尖 : 10.6 kWh,峰 : 15.53 kWh,平 : 22.28 kWh,谷 : 19.15 kWh

data_v2/value_v2字段 ​

何时会出现 data_v2/value_v2? ​

  • 支持数据块抄表的情况下，后台抄电量或者剩余金额会被替换成数据块抄表 ，接口抄表不替换，为了不影响原来客户使用，与原来保持一致。但是接口新增了一个功能码用于支持数据块抄表
  • 部分会出现 同一个表突然出现 data_v2/value_v2 ，原因是：系统检测到表支持 data_v2/value_v2,后续这个表会一直读取 data_v2/value_v2
  • data_v2/value_v2 中dsp字段用量数据未计算变比

data_v2/value_v2 字段解释 ​

data_v2/value_v2 字段解释
字段名值描述单位
jsfstrue结算方式：表示是否为预付费电表。通常，如果值为true，则表示为预付费；如果为false，则表示后付费。-
fls1费率数-
xs4线数 1=相数:单相,3=相数:三相三线,其他=相数:三相四线-
zyje120.68总有功电量：表示总的有功电量，通常以千瓦时（kWh）为单位。kWh
ye2397.32余额元
count2充值次数次
dqdj0.8202当前电价：表示当前时刻的电价，通常以元/千瓦时（元/kWh）为单位。元/kWh
zhygzdl147.14组合有功总电量kWh
zqyl147.14周期用量kWh
axdl28.293A相电流A
bxdl1.425B相电流A
cxdl1.425C相电流A
cxdy232.7C相电压V
axdy231.2A相电压V
bxdy234.4B相电压V
zyggl6.4604总有功功率：表示总的有功功率，通常以千瓦（kW）为单位。kW
axyggl5.0419A相有功功率：表示A相的有功功率，通常以千瓦（kW）为单位。kW
bxyggl0.1725B相有功功率：表示B相的有功功率，通常以千瓦（kW）为单位。kW
cxyggl1.2459C相有功功率：表示C相的有功功率，通常以千瓦（kW）为单位。kW
zwggl-0.8579总无功功率：表示总的无功功率，通常以千乏（kvar）为单位。负值可能表示功率因数的调整或反向无功。kvar
axwggl-0.4924A相无功功率：表示A相的无功功率，通常以千乏（kvar）为单位。负值可能表示功率因数的调整或反向无功。kvar
bxwggl-0.1789B相无功功率：表示B相的无功功率，通常以千乏（kvar）为单位。负值可能表示功率因数的调整或反向无功。kvar
cxwggl-0.1865C相无功功率：表示C相的无功功率，通常以千乏（kvar）为单位。负值可能表示功率因数的调整或反向无功。kvar
zszgl8.698总视在功率kVA
axszgl6.5404A相视在功率kVA
bxszgl0.3352B相视在功率kVA
cxszgl1.8223C相视在功率kVA
zglys0.742总功率因数：表示电表的总功率因数，是有功功率与视在功率的比值，通常用于评估电能质量和电费计算。-
axglys0.77A相功率因数：表示A相的功率因数，是有功功率与视在功率的比值，通常用于评估电能质量和电费计算。-
bxglys0.516B相功率因数：表示B相的功率因数，是有功功率与视在功率的比值，通常用于评估电能质量和电费计算。-
cxglys0.683C相功率因数：表示C相的功率因数，是有功功率与视在功率的比值，通常用于评估电能质量和电费计算。-
pl50.02频率Hz
wd20温度°C
ddyy无断电原因
dbzt无功功率反向,A相无功功率反向,B相无功功率反向,C相无功功率反向,通电电表状态

费率数>= 4特有属性 ​

字段名值描述单位
zhygjdl0.01组合有功尖电量kwh
zhygfdl0.01组合有功峰电量kwh
zhygpdl0.01组合有功平电量kwh
zhyggdl0.01组合有功谷电量kwh
zhygsgdl (费率数>5)0.01组合有功深谷电量kwh
zqyl0.01周期用量kwh
dbzt 可能值 ​
状态值描述
掉电设备掉电或电源故障
需量超限当前用电量超过了预定的限制
总功率因数超下限总功率因数低于预设的下限值
开表盖电表的表盖被打开
断电报警设备因某种原因被断电，并触发了报警
远程拉闸远程控制系统触发了断电操作
C相失压C 相失去电压，可能是电源故障或连接问题
C相欠压C 相电压低于正常工作范围
C相过压C 相电压高于正常工作范围
C相过流C 相电流超过正常工作范围
C相过载C 相负载过大，可能导致设备损坏
C相潮流反向C 相的电流方向与预期方向相反
B相失压B 相失去电压，可能是电源故障或连接问题
B相欠压B 相电压低于正常工作范围
B相过压B 相电压高于正常工作范围
B相过流B 相电流超过正常工作范围
B相过载B 相负载过大，可能导致设备损坏
B相潮流反向B 相的电流方向与预期方向相反
A相失压A 相失去电压，可能是电源故障或连接问题
A相欠压A 相电压低于正常工作范围
A相过压A 相电压高于正常工作范围
A相过流A 相电流超过正常工作范围
A相过载A 相负载过大，可能导致设备损坏
A相潮流反向A 相的电流方向与预期方向相反
有功功率反向有功功率方向与预期相反
无功功率反向无功功率方向与预期相反
控制回路出错控制回路发生错误
运行数据错误运行数据不正确或异常
存储器错误1存储器发生第一类错误
存储器错误2存储器发生第二类错误
已透支设备或系统已透支，可能超出限制
时钟错误系统时钟发生错误
A相有功功率反向A相的有功功率方向与预期相反
B相有功功率反向B相的有功功率方向与预期相反
C相有功功率反向C相的有功功率方向与预期相反
A相无功功率反向A相的无功功率方向与预期相反
B相无功功率反向B相的无功功率方向与预期相反
C相无功功率反向C相的无功功率方向与预期相反
通电设备处于通电状态
当前时段:第二套当前使用的时段费率表是第二套
辅助电源供电设备由辅助电源供电
电池供电设备由电池供电
断电设备已断电
当前时区表:第二套当前使用的时区表是第二套
当前费率电价:第二套当前使用的费率电价表是第二套
当前阶梯电价:第二套当前使用的阶梯电价表是第二套
保电设备处于保电模式

接口测试工具 ​