2018-07-16

作者: 被技术耽误的marketing | 来源:发表于2018-07-17 13:50 被阅读0次

智能硬件服务端API文档

[TOC]

基本约定

所有参数命名统一采用下划线方式

设计说明

本文档api为服务端调用。

使用说明

调用api不会获取到音频播放地址，即url字段为空
api地址访问前缀：https://api.ximalaya.com/iot/openapi-smart-device-api

鉴权参数

每次访问需要签名sig，生成算法描述和示例如下:

将所有请求参数的原始值按照参数名字的字典序排序：

app_key:123
os_type:linux
server_info:abc
nonce:12345678
timestamp:1504771988000

将排序后的参数键值对用&号拼接，即拼接成如下这样的形式：

app_key=123&nonce=12345678&os_type=linux&server_info=abc&timestamp=1504771988000

将2中得到的字符串拼上app_secret和server_auth_key, 则现在得到的拼接结果为：

app_key=123&nonce=12345678&os_type=linux&server_info=abc&timestamp=1504771988000
&app_secret=abc&server_auth_key=cde

对3中得到的字符串进行MD5运算得到32位小写字符串，即为sig的值

b40442a1eadc8961705a16dfb1f76741

接口索引

接口名	Method	简介
/albums/{id}	GET	获取指定id的album
/albums	GET	获取指定id集合的album列表
/albums/{id}/tracks	GET	获取指定id专辑的音频列表
/announcers/{id}	GET	获取指定id的主播
/announcers	GET	获取指定id的主播列表
/announcers/{id}/albums	GET	获取指定id的主播的专辑列表
/announcers/{id}/top-tracks	GET	获取指定id的主播的畅销专辑列表
/announcers/{id}/related-announcers	GET	获取指定id主播相关的主播列表
/tracks/{id}	GET	获取指定id的音频
/tracks	GET	获取指定id的音频列表
/tracks/track-seq	GET	获取指定id和后续的音频列表
/browse/hot-words	GET	获取 top n 热搜词
/browse/relative-albums	GET	根据参数获取专辑或音频的相关专辑的列表信息
/browse/album-categories	GET	获取喜马拉雅专辑的分类列表
/browse/announcer-categories	GET	获取喜马拉雅主播的分类列表
/browse/radio-categories	GET	获取喜马拉雅广播电台的分类列表
/album-categories/{id}	GET	根据喜马拉雅专辑分类ID获取分类信息
/announcer-categories/{id}	GET	根据喜马拉雅主播分类ID获取分类信息
/radio-categories/{id}	GET	根据喜马拉雅广播电台分类ID获取分类信息
/album-categories/{id}/tags	GET	获取某个喜马拉雅点播分类下的标签列表
/album-categories/{id}/albums	GET	获取某个喜马拉雅点播分类下，对应标签下的热门/最新/最多播放专辑列表
/radio-categories/{id}/radios	GET	获取指定广播分类下的广播电台列表
/recommendations	GET	获取推荐专辑列表
/ranks	GET	获取榜单列表信息
/ranks/{id}	GET	获取指定榜单下的专辑或音频列表信息
/search/albums	GET	搜索专辑信息
/search/announcers	GET	搜索主播信息
/search/radios	GET	搜索广播信息
/search/tracks	GET	搜索音频信息
/play-records	POST	批量上传点播播放记录
/browse/aera-radios	GET	获取国家和省市电台列表
/browse/network-radios	GET	获取网络电台列表
/radios/{id}	GET	获取指定id的电台
/radios	GET	获取指定ids的电台列表
/radios/{id}/schedules	GET	获取指定id的电台某一天的节目排期表
/radios/{id}/playing-program	GET	获取指定id的电台正在播放的节目
/browse/local-radios	GET	通过地理位置获取电台列表
/browse/area-fm-radio	GET	通过地区代码和频点获取电台
/albums/rich/{id}	GET	获取专辑的富文本信息

数据相关接口

1、/albums/{id}

功能

获取指定id的album

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	要获取专辑的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
market	string	否	划分市场区域的代码
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Album_full对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/albums/72281?app_key=53ba3200998d1cd3f4952fbb58ed50ae&
nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 72281,
    "title": "Secret Garden",
    "tracks_natural_ordered": false,
    "category_id": 2,
    "tags": "",
    "updated_at": 1421769600000,
    "created_at": 1366992000000,
    "play_count": 0,
    "favorite_count": 0,
    "share_count": 0,
    "include_track_count": 16,
    "is_finished": 0,
    "can_download": false,
    "cover": {
        "small": {
            "height": 86,
            "width": 86,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_small.jpg"
        },
        "middle": {
            "height": 140,
            "width": 140,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_meduim.jpg"
        },
        "large": {
            "height": 290,
            "width": 290,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_large.jpg"
        }
    },
    "announcer": {
        "id": 1428,
        "nickname": "fred_me",
        "avatar_url": "group1/M01/33/24/wKgD3ldpBq6AGwB4AAC7BvHbd28868.jpg",
        "is_verified": true,
        "url": null,
        "popularity": 0,
        "tags": null
    },
    "last_update_track": {
        "id": 247238,
        "kind": "Track",
        "title": "后来",
        "intro": "",
        "tags": "",
        "created_at": 1421823051000,
        "updated_at": 1421823051000,
        "order_num": 0,
        "duration": 339,
        "play_count": 0,
        "favorite_count": 0,
        "comment_count": 0,
        "source": null,
        "cover": null,
        "announcer": null,
        "can_download": false,
        "album": null
    },
    "intro": "",
    "kind": "album"
}

2、/albums

功能

获取指定id集合的album列表

HTTP METHOD

GET

参数

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
ids	string	是	要获取专辑的id序列，用逗号分隔，数量限制50个以内
market	string	否	支持市场区域的代码
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/albums?ids=72281%2C72282&app_key=53ba3200998d1cd3f4952fbb58ed50ae&
nonce=abcdefgh&timestamp=123456&sig=5d09dba1ce1e807a17bf81b5101f448b

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "72281": {
        "id": 72281,
        "title": "Secret Garden",
        "tracks_natural_ordered": false,
        "category_id": 2,
        "tags": "",
        "updated_at": 1421769600000,
        "created_at": 1366992000000,
        "play_count": 0,
        "favorite_count": 0,
        "share_count": 0,
        "include_track_count": 16,
        "is_finished": 0,
        "can_download": false,
        "cover": {
            "small": {
                "height": 86,
                "width": 86,
                "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_small.jpg"
            },
            "middle": {
                "height": 140,
                "width": 140,
                "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_meduim.jpg"
            },
            "large": {
                "height": 290,
                "width": 290,
                "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_large.jpg"
            }
        },
        "announcer": {
            "id": 1428,
            "nickname": "fred_me",
            "avatar_url": "group1/M01/33/24/wKgD3ldpBq6AGwB4AAC7BvHbd28868.jpg",
            "is_verified": true,
            "url": null,
            "popularity": 0,
            "tags": null
        },
        "last_update_track": {
            "id": 247238,
            "kind": "Track",
            "title": "后来",
            "intro": "",
            "tags": "",
            "created_at": 1421823051000,
            "updated_at": 1421823051000,
            "order_num": 0,
            "duration": 339,
            "play_count": 0,
            "favorite_count": 0,
            "comment_count": 0,
            "source": null,
            "cover": null,
            "announcer": null,
            "can_download": false,
            "album": null
        },
        "intro": "",
        "kind": "album"
    }
}

3、/albums/{id}/tracks

功能

获取指定id专辑的音频列表

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	专辑的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回的数量，最小为1，最大为50，默认为20
sort	string	否	返回结果的排序方式： asc-喜马拉雅正序，desc-喜马拉雅逆序，time_asc-发布时间升序，time_desc-发布时间降序，默认为 asc
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Track_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/albums/72281/tracks?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

http://localhost:8080/albums/72281/tracks?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=53ba3200998d1cd3f4952fbb58ed50ae&timestamp=123456&device_id=abc&sig=5803350a506b30c6e7a6f85656ad99c0
{
    "total": 16,
    "offset": 0,
    "limit": 20,
    "sort": "asc",
    "items": [
        {
            "id": 247238,
            "kind": "Track",
            "title": "后来",
            "intro": "",
            "tags": "",
            "created_at": 1421823051000,
            "updated_at": 1421823051000,
            "order_num": 0,
            "duration": 339,
            "play_count": 0,
            "favorite_count": 0,
            "comment_count": 0,
            "source": null,
            "cover": null,
            "announcer": {
                "id": 1428,
                "nickname": "fred_me",
                "avatar_url": "group1/M01/33/24/wKgD3ldpBq6AGwB4AAC7BvHbd28868.jpg",
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "can_download": false,
            "album": {
                "id": 72281,
                "title": "Secret Garden",
                "tracks_natural_ordered": false,
                "category_id": 2,
                "tags": "",
                "updated_at": 1421769600000,
                "created_at": 1366992000000,
                "play_count": 0,
                "favorite_count": 0,
                "share_count": 0,
                "include_track_count": 16,
                "is_finished": 0,
                "can_download": false,
                "cover": null,
                "announcer": null,
                "last_update_track": null,
                "intro": "",
                "kind": "album"
            }
        },
        ......
    ]
 }

4、/announcers/{id}

功能

获取指定id的主播

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	指定主播的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Announcer对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/announcers/12463?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 12463,
    "nickname": "tiny133测试消息613dd",
    "avatar_url": null,
    "is_verified": true,
    "url": null,
    "popularity": 0,
    "tags": null
}

5、/announcers

功能

获取指定id的主播列表

HTTP METHOD

GET

参数

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
ids	string	是	要获取主播的id序列，用逗号分隔，数量50个以内

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Announcer类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/announcers?ids=12463%2C12464&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=9c609ade4b9f5a0ecf74e32f63f73f4f

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "12464": {
        "id": 12464,
        "nickname": "341324",
        "avatar_url": null,
        "is_verified": false,
        "url": null,
        "popularity": 0,
        "tags": null
    },
    "12463": {
        "id": 12463,
        "nickname": "tiny133测试消息613dd",
        "avatar_url": null,
        "is_verified": true,
        "url": null,
        "popularity": 0,
        "tags": null
    }
}

6、/announcers/{id}/albums

功能

获取指定id的主播的专辑列表

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	指定主播的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回的数量，最小为1，最大为50，默认为20
sort	string	否	返回结果的排序方式： asc-喜马拉雅正序，desc-喜马拉雅逆序，time_asc-发布时间升序，time_desc-发布时间降序，默认为 asc
market	string	否	划分市场区域的代码
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/announcers/12463/albums?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 11,
    "offset": 0,
    "limit": 20,
    "sort": "",
    "items": [
        {
            "id": 120298,
            "title": "下架",
            "tracks_natural_ordered": false,
            "category_id": 0,
            "tags": null,
            "updated_at": 1510559446000,
            "created_at": 1505724769000,
            "play_count": 0,
            "favorite_count": 0,
            "share_count": 0,
            "include_track_count": 0,
            "is_finished": 0,
            "can_download": false,
            "cover": {
                "small": null,
                "middle": null,
                "large": null
            },
            "announcer": {
                "id": 12463,
                "nickname": "tiny133测试消息613dd",
                "avatar_url": null,
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "last_update_track": null,
            "intro": "",
            "kind": "album"
        },
        ......
    ]
}

7、/announcers/{id}/top-tracks

功能

获取指定id的主播的热门音频列表

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	指定主播的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回的数量，最小为1，最大为50，默认为20
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Track_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl https://smart_api.ximalaya.com/announcers/111/top-tracks?token=Simple+mF_9.B5f-4.1JqM&fields=title%2Cintro&limit=2&market=cn

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{ 
  "items": [
   {
    "title": "title1",
    "intro": "intro1",
   },
   {
    "title": "title2",
    "intro": "intro2",
   }
  ],
  "total": 30,
  "sort": "",
  "offset": 0,
  "limit": 2
}

8、/announcers/{id}/related-announcers

功能

获取指定id主播相关的主播列表

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	指定主播的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回的数量，最小为1，最大为50，默认为20
sort	string	否	返回结果的排序方式： asc-喜马拉雅正序，desc-喜马拉雅逆序，time_asc-发布时间升序，time_desc-发布时间降序，默认为 asc

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Announcer类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl https://smart_api.ximalaya.com/announcers/111/related-announcers?token=Simple+mF_9.B5f-4.1JqM&sort=time_asc&limit=2&offset=0

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "items": [
    {
      "id": 111,
      "nickname": "nn1",
      "avatar_url": "http://ximalaya.com/avatar/c3",
      "is_verified": true,
      "url": "http://ximalaya.com/urls/c3",
      "popularity": 0,
      "tags": [
        "finance"
      ]
    },
    {
      "id": 112,
      "nickname": "nn2",
      "avatar_url": "http://ximalaya.com/avatar/c3",
      "is_verified": true,
      "url": "http://ximalaya.com/urls/c3",
      "popularity": 0,
      "tags": [
        "finance"
      ]
    }
  ],
  "total": 12,
  "sort": "time_asc",
  "offset": 0,
  "limit": 2
}

9、/tracks/{id}

功能

获取指定id的音频

HTTP METHOD

GET

参数

PATH 参数	类型	必填	描述
id	long	是	指定音频的id

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
market	string	否	划分市场区域的代码
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Track_full对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/tracks/358558?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 358558,
    "kind": "Track",
    "title": "张学友-用余生去爱",
    "intro": "",
    "tags": "",
    "created_at": 1506063721000,
    "updated_at": 1509075422000,
    "order_num": 0,
    "duration": 254,
    "play_count": 68,
    "favorite_count": 0,
    "comment_count": 2,
    "source": null,
    "cover": null,
    "announcer": {
        "id": 59181,
        "nickname": "奇葩公社啦_007",
        "avatar_url": "group1/M01/4E/52/wKgD3lmndjWAA-3lAAD1E7taeF0293.jpg",
        "is_verified": true,
        "url": null,
        "popularity": 0,
        "tags": null
    },
    "can_download": false,
    "album": {
        "id": 120382,
        "title": "讲不出再见",
        "tracks_natural_ordered": false,
        "category_id": 4,
        "tags": "",
        "updated_at": 1509075422000,
        "created_at": 1506063715000,
        "play_count": 233,
        "favorite_count": 0,
        "share_count": 0,
        "include_track_count": 4,
        "is_finished": 0,
        "can_download": false,
        "cover": null,
        "announcer": null,
        "last_update_track": null,
        "intro": "",
        "kind": "album"
    }
}

10、/tracks

功能

根据一批音频ID批量获取音频列表

HTTP METHOD

GET

参数

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
ids	string	是	要获取音频的id数组，数量限制50个以内
market	string	否	划分市场区域的代码
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Track_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/tracks?ids=358558%2C358558&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=94e6894233a566dd0a91d214e338e2b4

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "358558": {
        "id": 358558,
        "kind": "Track",
        "title": "张学友-用余生去爱",
        "intro": "",
        "tags": "",
        "created_at": 1506063721000,
        "updated_at": 1509075422000,
        "order_num": 0,
        "duration": 254,
        "play_count": 68,
        "favorite_count": 0,
        "comment_count": 2,
        "source": null,
        "cover": null,
        "announcer": {
            "id": 59181,
            "nickname": "奇葩公社啦_007",
            "avatar_url": "group1/M01/4E/52/wKgD3lmndjWAA-3lAAD1E7taeF0293.jpg",
            "is_verified": true,
            "url": null,
            "popularity": 0,
            "tags": null
        },
        "can_download": false,
        "album": {
            "id": 120382,
            "title": "讲不出再见",
            "tracks_natural_ordered": false,
            "category_id": 4,
            "tags": "",
            "updated_at": 1509075422000,
            "created_at": 1506063715000,
            "play_count": 233,
            "favorite_count": 0,
            "share_count": 0,
            "include_track_count": 4,
            "is_finished": 0,
            "can_download": false,
            "cover": null,
            "announcer": null,
            "last_update_track": null,
            "intro": "",
            "kind": "album"
        }
    }
}

11、/tracks/track-seq

功能

获取指定音频的所在专辑的后续音频序列

HTTP METHOD

GET

参数

QUERY 参数	类型	必填	描述
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
id	long	是	指定音频的id
album_id	long	是	专辑的id
limit	integer	否	返回的数量，最小为1，最大为50，默认为20
sort	string	否	返回结果的排序方式： asc-喜马拉雅正序，desc-喜马拉雅逆序，time_asc-发布时间升序，time_desc-发布时间降序，默认为 asc
market	string	否	划分市场区域的代码
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Track_full类型的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error。

示例

curl http://localhost:8080/tracks/track-seq?id=358558&album_id=100000&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=cad2854e70d5511385753a6f6263913d

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 4,
    "offset": 0,
    "limit": 20,
    "sort": "",
    "items": [
        {
            "id": 358555,
            "kind": "Track",
            "title": "叶铮 - 把悲伤留给自己(live版)",
            "intro": "",
            "tags": "",
            "created_at": 1506063720000,
            "updated_at": 1506063783000,
            "order_num": 0,
            "duration": 82,
            "play_count": 40,
            "favorite_count": 0,
            "comment_count": 0,
            "source": null,
            "cover": null,
            "announcer": {
                "id": 59181,
                "nickname": "奇葩公社啦_007",
                "avatar_url": "group1/M01/4E/52/wKgD3lmndjWAA-3lAAD1E7taeF0293.jpg",
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "can_download": false,
            "album": {
                "id": 120382,
                "title": "讲不出再见",
                "tracks_natural_ordered": false,
                "category_id": 4,
                "tags": "",
                "updated_at": 1509075422000,
                "created_at": 1506063715000,
                "play_count": 233,
                "favorite_count": 0,
                "share_count": 0,
                "include_track_count": 4,
                "is_finished": 0,
                "can_download": false,
                "cover": null,
                "announcer": null,
                "last_update_track": null,
                "intro": "",
                "kind": "album"
            }
        },
        ...
     ]     
}

12、/browse/hot-words

功能

获取 top n 热搜词

HTTP Method

GET

参数

QUERY 参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
top_n	string	是	返回的热词个数
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page类型对象，对象中items数组的元素为HotWord；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/hot-words?top_n=50&offset=10&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=e61ba9e39fe94aa42b3b78e75989e930

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 19,
    "offset": 10,
    "limit": 20,
    "sort": null,
    "items": [
        {
            "hot_word": "鬼藏人",
            "degree": 0,
            "count": 276
        },
        {
            "hot_word": "高中英语",
            "degree": 0,
            "count": 267
        },
        {
            "hot_word": "骆驼",
            "degree": 0,
            "count": 255
        },
        {
            "hot_word": "魔兽",
            "degree": 0,
            "count": 242
        },
        {
            "hot_word": "鬼医郡王妃",
            "degree": 0,
            "count": 224
        },
        {
            "hot_word": "鲍鹏山",
            "degree": 0,
            "count": 139
        },
        {
            "hot_word": "游客",
            "degree": 0,
            "count": 1
        },
        {
            "hot_word": "郭富城",
            "degree": 0,
            "count": 1
        },
        {
            "hot_word": "测试",
            "degree": 0,
            "count": 0
        }
    ]
}

13、/browse/relative-albums

功能

获取专辑或音频的相关专辑的列表信息

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
kind	string	是	限定参数id的类型，album 表示id为专辑ID，track 表示id为音频ID
id	integer	是	根据kind 不同分别表示 album ID 和 track ID
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
sort	string	否	返回结果的排序方式： asc-喜马拉雅正序，desc-喜马拉雅逆序，time_asc-发布时间升序，time_desc-发布时间降序，默认为 asc
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/relative-albums?id=120382&kind=album&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=62acc649da0bcb931515acc6f027632d

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 0,
    "offset": 0,
    "limit": 20,
    "sort": "asc",
    "items":  [
        {
            "id": 120298,
            "title": "下架",
            "tracks_natural_ordered": false,
            "category_id": 0,
            "tags": null,
            "updated_at": 1510559446000,
            "created_at": 1505724769000,
            "play_count": 0,
            "favorite_count": 0,
            "share_count": 0,
            "include_track_count": 0,
            "is_finished": 0,
            "can_download": false,
            "cover": {
                "small": null,
                "middle": null,
                "large": null
            },
            "announcer": {
                "id": 12463,
                "nickname": "tiny133测试消息613dd",
                "avatar_url": null,
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "last_update_track": null,
            "intro": "",
            "kind": "album"
        },
        ......
    ]
}

14、/browse/album-categories

功能

获取喜马拉雅专辑的分类列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/album-categories?offset=10&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=ec00ad4447ca146f4606d49cae3db5bc

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 33,
    "offset": 10,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 12,
            "kind": "ALBUM_CATEGORY",
            "category_name": "相声评书",
            "order_num": 5,
            "cover": {
                "small": {
                    "height": 86,
                    "width": 86,
                    "url": "group12/M07/17/A4/wKgDW1VxNCrzTwWVAAAJnAUfyR8545.png"
                },
                "middle": {
                    "height": 140,
                    "width": 140,
                    "url": "group12/M07/17/A1/wKgDXFVxNB6wGFwmAAAJnAUfyR8949.png"
                },
                "large": {
                    "height": 290,
                    "width": 290,
                    "url": ""
                }
            }
        },
        ...
     ]
 }

15、/browse/announcer-categories

功能

获取喜马拉雅主播的分类列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/announcer-categories?offset=5&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=e4cfcbc3ca5d2e3b1e7748bed438e793

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 30,
    "offset": 5,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 1,
            "kind": "ANNOUNCER_CATEGORY",
            "category_name": "最新资讯",
            "order_num": 5,
            "cover": null
        },
        {
            "id": 9,
            "kind": "ANNOUNCER_CATEGORY",
            "category_name": "历史人文",
            "order_num": 6,
            "cover": null
        },
        {
            "id": 5,
            "kind": "ANNOUNCER_CATEGORY",
            "category_name": "外语",
            "order_num": 7,
            "cover": null
        },
        {
            "id": 8,
            "kind": "ANNOUNCER_CATEGORY",
            "category_name": "商业财经",
            "order_num": 8,
            "cover": null
        },
        {
            "id": 7,
            "kind": "ANNOUNCER_CATEGORY",
            "category_name": "健康养生",
            "order_num": 9,
            "cover": null
        }
    ]
}

16、/browse/radio-categories

功能

获取喜马拉雅广播电台的分类列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/radio-categories?limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=53ba3200998d1cd3f4952fbb58ed50ae&timestamp=123456&device_id=abc&sig=cbd4d2b7db1750affd96865cc1fdad53

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 4,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 1,
            "kind": "RADIO_CATEGORY",
            "category_name": "资讯",
            "order_num": 10,
            "cover": null
        },
        {
            "id": 2,
            "kind": "RADIO_CATEGORY",
            "category_name": "music",
            "order_num": 5,
            "cover": null
        },
        {
            "id": 3,
            "kind": "RADIO_CATEGORY",
            "category_name": "交通台",
            "order_num": 1003,
            "cover": null
        },
        {
            "id": 1002,
            "kind": "RADIO_CATEGORY",
            "category_name": "broadcasttest",
            "order_num": 0,
            "cover": null
        }
    ]
}

17、/album-categories/{id}

功能

根据喜马拉雅专辑分类ID获取分类信息

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	分类id，对应Category中的id字段

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/album-categories/12?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=53ba3200998d1cd3f4952fbb58ed50ae&timestamp=123456&device_id=abc&sig=5803350a506b30c6e7a6f85656ad99c0

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 12,
    "kind": "ALBUM_CATEGORY",
    "category_name": "相声评书",
    "order_num": 5,
    "cover": {
        "small": {
            "height": 86,
            "width": 86,
            "url": "group12/M07/17/A4/wKgDW1VxNCrzTwWVAAAJnAUfyR8545.png"
        },
        "middle": {
            "height": 140,
            "width": 140,
            "url": "group12/M07/17/A1/wKgDXFVxNB6wGFwmAAAJnAUfyR8949.png"
        },
        "large": {
            "height": 290,
            "width": 290,
            "url": ""
        }
    }
}

18、/announcer-categories/{id}

功能

根据喜马拉雅主播分类ID获取分类信息

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	分类id，对应Category中的id字段

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/announcer-categories/111?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": 111,
  "kind": "announcer-categories",
  "category_name": "科技",
  "order_num":1
}

19、/radio-categories/{id}

功能

根据喜马拉雅广播电台分类ID获取分类信息

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	分类id，对应Category中的id字段

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Category类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radio-categories/2?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 2,
    "kind": "RADIO_CATEGORY",
    "category_name": "music",
    "order_num": 5,
    "cover": null
}

20、/album-categories/{id}/tags

功能

获取某个喜马拉雅数据分类下的标签列表（可看做二级分类）

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	分类id，对应Categroy中的id字段

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Tag类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/album-categories/1/tags?limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=a4e71b3a2e07140714c29282dfd768bc

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 7,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "name": "财经资讯",
            "kind": "tag"
        },
        {
            "name": "时政热点",
            "kind": "tag"
        },
        {
            "name": "热点话题",
            "kind": "tag"
        },
        {
            "name": "娱乐播报",
            "kind": "tag"
        },
        {
            "name": "汽车",
            "kind": "tag"
        }
    ]
}

21、/album-categories/{id}/albums

功能

获取某个喜马拉雅专辑分类下，对应标签下的专辑列表

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	分类id，对应Categroy中的id字段

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
tag	string	否	对应 album 分类下获取到的专辑标签
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
sort	string	是	返回结果的排序维度：hottest-最火，newest-最新，most_played-最多播放
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含JSONObject对象，对象中包含以下列表中的字段；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应的常规错误对象Error

示例

curl http://localhost:8080/album-categories/1/albums?limit=2&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=f90f66fd37aee2e733d2780dd2318178

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 159,
    "offset": 0,
    "limit": 2,
    "sort": "hottest",
    "items": [
        {
            "id": 84158,
            "title": "私密001",
            "tracks_natural_ordered": false,
            "category_id": 1,
            "tags": "查查,排行榜,脱口秀,新歌,老哥",
            "updated_at": 1467715595000,
            "created_at": 1425398400000,
            "play_count": 2,
            "favorite_count": 0,
            "share_count": 0,
            "include_track_count": 3,
            "is_finished": 0,
            "can_download": false,
            "cover": {
                "small": {
                    "height": 86,
                    "width": 86,
                    "url": "http://fdfs.test.ximalaya.com/group1/M00/1C/1D/wKgD3lT2siaAfs03AAFtGIQq1co364_mobile_small.jpg"
                },
                "middle": {
                    "height": 140,
                    "width": 140,
                    "url": "http://fdfs.test.ximalaya.com/group1/M00/1C/1D/wKgD3lT2siaAfs03AAFtGIQq1co364_mobile_meduim.jpg"
                },
                "large": {
                    "height": 290,
                    "width": 290,
                    "url": "http://fdfs.test.ximalaya.com/group1/M00/1C/1D/wKgD3lT2siaAfs03AAFtGIQq1co364_mobile_large.jpg"
                }
            },
            "announcer": {
                "id": 2221,
                "nickname": "古韵风流_",
                "avatar_url": "group1/M00/4E/12/wKgD3lmc6kyAGdQKAAEG1c4opX4746.jpg",
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "last_update_track": {
                "id": 250727,
                "kind": "Track",
                "title": "私密001",
                "intro": "撒浮士德士大夫诉讼费是收到是非得失",
                "tags": "查查,排行榜,脱口秀,新歌,老哥",
                "created_at": 1425453485000,
                "updated_at": 1467715593000,
                "order_num": 0,
                "duration": 250,
                "play_count": 5,
                "favorite_count": 0,
                "comment_count": 0,
                "source": null,
                "cover": null,
                "announcer": null,
                "can_download": true,
                "album": null
            },
            "intro": "撒浮士德士大夫诉讼费是收到是非得失",
            "kind": "album"
        },
        ...
    ]
}

22、/radio-categories/{id}/radios

功能

获取指定广播分类下的广播电台列表

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	广播分类ID

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Radio类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radio-categories/1/radios?limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=a4e71b3a2e07140714c29282dfd768bc

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 631,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 14,
            "name": "CNR中华之声",
            "intro": null,
            "area": null,
            "playing_program_id": 45879,
            "playing_program_name": "",
            "support_bitrates": null,
            "play_count": 71,
            "small_cover_url": "http://fdfs.test.ximalaya.com/group1/M01/26/2D/wKgDplZxJY2AKtCGAABWZ5OYNHk400_mobile_small.jpg",
            "large_cover_url": "http://fdfs.test.ximalaya.com/group1/M01/26/2D/wKgDplZxJY2AKtCGAABWZ5OYNHk400_mobile_large.jpg",
            "updated_at": 1500660687000,
            "kind": "radio"
        },
        ...
    ]
}

23、/recommendations

功能

基于历史播放记录，根据系统类型和设备ID等获取个性化的专辑推荐列表。因为基于历史播放记录进行推荐,需要调用播放数据回传接口/play-records 回传播放数据。

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
kind	string	否	推荐的内容的类型 album-专辑（目前只有这一种），track-音频，announcer-主播，默认是album
device_type	string	是	ios、android、linux、web、ecos、qnix，默认是web
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，本接口默认为3，取值范围为[1-50]
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/recommendations?limit=5&device_type=web&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=e3d944ab87cb212f1613355c8c4f0930

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 0,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": []
}

24、/ranks

功能

获取专辑或音频榜单列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
kind	string	是	要获取的榜单类型，"album"、"track"
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，本接口默认为20，取值范围为[1-50]
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Rank类型的对象；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/ranks?limit=2&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=f90f66fd37aee2e733d2780dd2318178

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 18,
    "offset": 0,
    "limit": 2,
    "sort": null,
    "items": [
        {
            "id": 21,
            "key": "1_21_ranking:album:played:30:0",
            "title": "经典必听榜",
            "sub_title": "真相来了！榜单出炉，不服来辩！",
            "period": 30,
            "period_type": "PERIOD_MONTH",
            "item_num": 0,
            "order_num": 0,
            "cover_url": "http://fdfs.xmcdn.com/group11/M0B/17/D9/wKgDbVVxRmPRLf9JAABdZjkfM4Y496.png",
            "category_id": 0,
            "content_type": "album",
            "rank_items": [
                {
                    "type": null,
                    "id": 203355,
                    "title": "album"
                },
                {
                    "type": null,
                    "id": 10925666,
                    "title": "album"
                }
            ],
            "kind": "rank"
        },
        ...
    ]
}

25、/ranks/{id}

功能

获取指定id的榜单内的条目信息

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	string	是	榜单ID 可从接口/ranks的返回值中获取

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象或Track类型的对象 (根据参数id对应的榜单信息中的content_type的值返回对应的类型，album返回Album_full，track返回Track )；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/ranks/21?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "id": 21,
    "key": "1_21_ranking:album:played:30:0",
    "title": "经典必听榜",
    "sub_title": "真相来了！榜单出炉，不服来辩！",
    "period": 30,
    "period_type": "PERIOD_MONTH",
    "item_num": 0,
    "order_num": 0,
    "cover_url": "http://fdfs.xmcdn.com/group11/M0B/17/D9/wKgDbVVxRmPRLf9JAABdZjkfM4Y496.png",
    "category_id": 0,
    "content_type": "album",
    "rank_items": [
        {
            "type": "album",
            "id": 203355,
            "title": "段子来了"
        },
        {
            "type": "album",
            "id": 10925666,
            "title": "《安利全集》FC成冠超凡环宇卓越冠宇贝瑞德福呗增付后坚周志坚郭洪斌孙东微信12983200"
        }
    ],
    "kind": "rank"
}

26、/search/albums

功能

根据类型搜索专辑信息

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
q	string	是	指定要搜索的关键字
category_id	integer	否	限定搜索范围的专辑分类的ID，通过接口/browse/album-categories
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
sort	string	否	返回结果的排序维度：hottest-最火，newest-最新，playedmost-最多播放
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Album_full类型的对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/search/albums?q=%E9%83%AD%E5%BE%B7%E7%BA%B2&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=8f2a8e3e37ce80a3d239adedba6777a5

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 50,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 88450,
            "title": "马三立经典相声集",
            "tracks_natural_ordered": false,
            "category_id": 9,
            "tags": "郭德纲,赵本山,单田芳,袁阔成,田连元",
            "updated_at": 1459080228000,
            "created_at": 1444293024000,
            "play_count": 0,
            "favorite_count": 0,
            "share_count": 0,
            "include_track_count": 166,
            "is_finished": 0,
            "can_download": false,
            "cover": {
                "small": {
                    "height": 86,
                    "width": 86,
                    "url": "http://fdfs.test.ximalaya.com/group1/M01/24/7E/wKgD3lYWKraAWJtAAAA3yUhqHkc263_mobile_small.jpg"
                },
                "middle": {
                    "height": 140,
                    "width": 140,
                    "url": "http://fdfs.test.ximalaya.com/group1/M01/24/7E/wKgD3lYWKraAWJtAAAA3yUhqHkc263_mobile_meduim.jpg"
                },
                "large": {
                    "height": 290,
                    "width": 290,
                    "url": "http://fdfs.test.ximalaya.com/group1/M01/24/7E/wKgD3lYWKraAWJtAAAA3yUhqHkc263_mobile_large.jpg"
                }
            },
            "announcer": {
                "id": 13949,
                "nickname": "tiny478",
                "avatar_url": "group1/M00/24/DA/wKgDplX411aAUgqcAAGzsTRGZz8744.jpg",
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "last_update_track": {
                "id": 270322,
                "kind": "Track",
                "title": "复件 品冠 - 门没锁",
                "intro": "",
                "tags": "百家讲坛,历史,传奇,人物",
                "created_at": 1446183396000,
                "updated_at": 1446183418000,
                "order_num": 0,
                "duration": 238,
                "play_count": 0,
                "favorite_count": 0,
                "comment_count": 0,
                "source": null,
                "cover": null,
                "announcer": null,
                "can_download": true,
                "album": null
            },
            "intro": "我的 马三立经典相声集",
            "kind": "album"
        },
        ...
    ]
}

27、/search/announcers

功能

根据类型搜索主播信息

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
q	string	是	指定要搜索的关键字
category_id	integer	否	限定搜索范围的主播分类的ID，通过接口/browse/announcer-categories
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
sort	integer	否	返回结果的排序维度：hottest-最火，newest-最新，playedmost-最多播放, 搜索 track 和 album 时有效。
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Announcer类型的对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/search/announcers?q=%E9%83%AD%E5%BE%B7%E7%BA%B2&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=8f2a8e3e37ce80a3d239adedba6777a5

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 3,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 3455,
            "nickname": "郭德纲",
            "avatar_url": "group1/M00/12/F2/wKgD3lMxHmyAISu7AAGORGb-X60139.jpg",
            "is_verified": true,
            "url": null,
            "popularity": 0,
            "tags": null
        },
        ...
    ]
}

28、/search/radios

功能

根据类型搜索广播等信息

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
q	string	是	指定要搜索的关键字
category_id	integer	否	限定搜索范围的广播分类的ID，通过接口/browse/radio-categories
area	string	否	参照国家统计局的行政区划代码行政区划代码中的省、城市名字
lon	long	否	经度参数
lat	long	否	维度参数
outer_ip	string	否	IP参数，此参数需传公网IP。如果需要根据地理位置查询，则经纬度和IP参数至少传一个。
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素Radio类型的对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/search/radios?q=%E9%83%AD%E5%BE%B7%E7%BA%B2&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=8f2a8e3e37ce80a3d239adedba6777a5

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 4,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 1092,
            "name": "锡林郭勒交通广播",
            "intro": null,
            "area": null,
            "playing_program_id": 0,
            "playing_program_name": null,
            "support_bitrates": null,
            "play_count": 0,
            "small_cover_url": "http://fdfs.test.ximalaya.com/img_mobile_small",
            "large_cover_url": "http://fdfs.test.ximalaya.com/img_mobile_large",
            "updated_at": 0,
            "kind": "radio"
        },
        ...
    ]
}

29、/search/tracks

功能

根据类型搜索音频信息

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
q	string	是	指定要搜索的关键字
category_id	integer	否	限定搜索范围的专辑分类的ID，通过接口/browse/album-categories
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
sort	integer	否	返回结果的排序维度：hottest-最火，newest-最新，playedmost-最多播放
fields	string	否	返回的字段列表，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为Track类型对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/search/tracks?q=%E9%83%AD%E5%BE%B7%E7%BA%B2&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=8f2a8e3e37ce80a3d239adedba6777a5

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 586,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 319402,
            "kind": "Track",
            "title": "【直播回听】tiny125的直播-2016.12.28 01:23",
            "intro": "A、初始词库的来源\r\n \r\n \r\n 全站用户历史查询的记录\r\n \r\n \r\n 运营维护的站内专有名词\r\n \r\n \r\n 站外抓取的特定行业名词\r\n \r\n \r\n 专辑标签的词汇挖掘\r\n \r\n \r\n 机器学习的扩展词\r\n \r\n \r\n B、可用的查询词库（清洗、词特征、计算词质量分等）\r\n \r\n \r\n 利用召回数（高质量专辑）来对每个初始词库中的词进行过滤，可定查询词对应高质量专辑的召回数阈值为1，低于这个阈值的词不进查询词库。\r\n \r\n \r\n 进入查询词库的词，离线计算的总召回数、高质量专辑的召回数做为该查询词的填写字段。\r\n \r\n \r\n 进入查询词库的词，离线进行拼音的转化（包括全拼、简写、多音、注音、简拼、形近），做为该查询词的填写字段。\r\n \r\n \r\n 查询词先按照高质量专辑召回数排序，再按照总召回数进行重排序。人工设置的热词排着前面。\r\n \r\n \r\n \r\n \r\n \r\n 2、纠错类型\r\n \r\n \r\n 拼音纠错\r\n \r\n \r\n 注音纠错－由于发音不规范导致的错误，比如：“nanqiu”与“lanqiu”\r\n \r\n \r\n 多音字纠错－多音字造成的拼音输入错误，比如：“chongqing”与“zhongqing”\r\n \r\n \r\n 同音字纠错－拼音输入正确但选字错误，比如：“篮球”与“蓝球”\r\n \r\n \r\n 拼音缩写纠错－拼音简写输入，比如：“gdg”与“郭德纲”\r\n \r\n \r\n 字形纠...",
            "tags": "",
            "created_at": 1482889243000,
            "updated_at": 1508311739000,
            "order_num": 0,
            "duration": 128,
            "play_count": 0,
            "favorite_count": 0,
            "comment_count": 7,
            "source": null,
            "cover": null,
            "announcer": {
                "id": 12423,
                "nickname": "tiny125",
                "avatar_url": "group1/M00/42/BB/wKgDpljQjHOAXRnzAAB2KxDNXhY379.jpg",
                "is_verified": true,
                "url": null,
                "popularity": 0,
                "tags": null
            },
            "can_download": true,
            "album": {
                "id": 86564,
                "kind": "album",
                "title": "cntv1",
                "intro": null,
                "tracks_natural_ordered": false,
                "category_id": 8,
                "tags": "",
                "updated_at": 1508311740000,
                "created_at": 1432287803000,
                "play_count": 34,
                "favorite_count": 0,
                "share_count": 0,
                "include_track_count": 9,
                "is_finished": 0,
                "can_download": false,
                "cover": null,
                "announcer": null,
                "last_update_track": null
            }
        },
        ...
    ]
}

30、/play-records

功能

批量上传点播播放记录（每次上传的记录不能超过200条）

HTTP Method

POST

参数

BODY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
track_records	string	是	点播播放记录TrackPlayRecord的列表（JSONArray)的序列化结果

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含JSON对象，其中字段见如下列表；

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

字段名	类型	说明
err_code	integer	接口调用成功或失败的状态码，同response status code，200表示成功
errmsg	string	接口调用成功或失败的描述信息

示例

{
  "err_code":200,
  "errmsg":"ok"
}

31、/browse/area-radios

功能

获取国家和省市电台列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
area_code	string	否	行政区划代码参照国家统计局的行政区划代码行政区划代码，不传或为空时返回国家台，不为空时返回区划代码指定区域的广播电台列表。例如： 110000 表示获取北京市的电台列表， 130000 表示获取河北省的电台列表，130100 表示获取石家庄市的电台列表，目前支持获取到省市级的电台列表，如果传入区县级的地区码则返回其所属市的电台列表。
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为[Radio]的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/area-radios?area_code=110000&limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=b9c560fd0b5aafad9ae291364e3b2a9e

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "total": 32,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 13,
            "name": "CNR都市之声",
            "intro": null,
            "area": null,
            "playing_program_id": 172401,
            "playing_program_name": "音乐早餐",
            "support_bitrates": null,
            "play_count": 43,
            "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M00/84/BD/wKgDhFT_oeSy57E-AACkBBj_E4M474_mobile_small.jpg",
            "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M00/84/BD/wKgDhFT_oeSy57E-AACkBBj_E4M474_mobile_large.jpg",
            "updated_at": 1494261583000,
            "kind": "radio"
        },
        ...
    ]
}

32、/browse/network-radios

功能

获取网络电台列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Page对象，对象中Items数组元素为[Radio]的对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/browse/network-radios?limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=a4e71b3a2e07140714c29282dfd768bc

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "total": 78,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 1024,
            "name": "iting网络电台",
            "intro": null,
            "area": null,
            "playing_program_id": 129785,
            "playing_program_name": "音乐无人驾驶",
            "support_bitrates": null,
            "play_count": 0,
            "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_small.jpg",
            "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_large.jpg",
            "updated_at": 0,
            "kind": "radio"
        },
        ...
    ]
}

33、/radios/{id}

功能

获取指定id的电台信息

HTTP Method

GET

参数

PATH 参数	类型	必填	说明
id	integer	是	电台id

QUERY 参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含元素为Radio的JSONObject对象。

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radios/1024?app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=373d3d5d80a5cde2c8bc52d893be6368

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "id": 1024,
    "name": "iting网络电台",
    "intro": null,
    "area": null,
    "playing_program_id": 129785,
    "playing_program_name": "音乐无人驾驶",
    "support_bitrates": null,
    "play_count": 0,
    "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_small.jpg",
    "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_large.jpg",
    "updated_at": 0,
    "kind": "radio"
}

34、/radios

功能

获取指定ids的电台列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机数
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
ids	integer	是	电台id列表，用逗号分隔
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含组元素为Radio类型的JSONArray对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radios?ids=1024%2C1025&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=2b2b57653f5ac229d7ea62df5d02e1f1

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "1024": {
        "id": 1024,
        "name": "iting网络电台",
        "intro": null,
        "area": null,
        "playing_program_id": 129785,
        "playing_program_name": "音乐无人驾驶",
        "support_bitrates": null,
        "play_count": 0,
        "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_small.jpg",
        "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_large.jpg",
        "updated_at": 0,
        "kind": "radio"
    },
    "1025": {
        "id": 1025,
        "name": "珊瑚虫之声",
        "intro": null,
        "area": null,
        "playing_program_id": 0,
        "playing_program_name": null,
        "support_bitrates": null,
        "play_count": 0,
        "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M00/BD/45/wKgDg1UP5lnBCHhNAAAmyLs5c58293_mobile_small.jpg",
        "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M00/BD/45/wKgDg1UP5lnBCHhNAAAmyLs5c58293_mobile_large.jpg",
        "updated_at": 0,
        "kind": "radio"
    }
}

35、/radios/{id}/schedules

功能

获取指定id的电台某一天的节目排期表

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	广播电台的ID

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
weekday	string	是	Mon-星期一，Tues-星期二，Wed-星期三，Thur-星期四，Fri-星期五，Sat-星期六，Sun-星期天
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

注：电台一周的节目单是相对稳定的，如果没有变动，每周的节目单都是一样的。

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含数组元素为Schedule类型的JSONArray对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radios/1024/schedules?weekday=Tues&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=c4006056e5a0793ce428d31de9713486

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

[
    {
        "id": 3353,
        "radio_id": 1024,
        "start_time": "00:00",
        "end_time": "19:00",
        "update_at": 1431939568000,
        "related_program": {
            "id": 129785,
            "program_name": "音乐无人驾驶",
            "back_pic_url": null,
            "support_bitrates": [
                24,
                64
            ],
            "live_announcers": [],
            "updated_at": 0,
            "kind": "program"
        },
        "kind": "schedule"
    },
    ...
]

36、/radios/{id}/playing-program

功能

获取指定id的电台正在播放的节目

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	广播电台的ID

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Program类型的对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/radios/1024/playing-program?weekday=Tues&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=c4006056e5a0793ce428d31de9713486

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "id": 129785,
    "program_name": "音乐无人驾驶",
    "back_pic_url": null,
    "support_bitrates": [
        24,
        64
    ],
    "live_announcers": [
        {
            "id": 11485,
            "nickname": "qqtester325",
            "avatar_url": null,
            "is_verified": false,
            "url": null,
            "popularity": 0,
            "tags": null
        }
    ],
    "updated_at": 0,
    "kind": "program"
}

37、/browse/local-radios

功能

通过地理位置获取电台列表

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
longitude	double	否	经度
latitude	double	否	纬度
ip	string	否	客户端ip地址，经纬度获取不准确时辅助定位
area_code	string	否	行政区划代码参照国家统计局的行政区划代码行政区划代码，不为空时返回区划代码指定区域的广播电台列表。例如： 110000 表示获取北京市的电台列表， 130000 表示获取河北省的电台列表，130100 表示获取石家庄市的电台列表，目前支持获取到省市级的电台列表，如果传入区县级的地区码则返回其所属市的电台列表。(目前仅支持到省级代码)
offset	integer	否	首条记录的索引位置，默认为0
limit	integer	否	返回结果中的最大条目数量，默认为20，最大200

注：行政区划代码和经纬度提供两种获取位置的模式，用户选择其一即可。

返回值

请求成功时，http status在header中的状态码是200，http response body中包含Page对象，对象中Items数组元素为[Radio]的对象。

若请求出错，header中的状态码参考为500，并且response body中包含了相应错误对象ErrorResponse

示例

http://api.ximalaya.com/iot/openapi-smart-device-api/browse/local-radios?limit=5&app_key=53ba3200998d1cd3f4952fbb58ed50ae&access_token=53ba3200998d1cd3f4952fbb58ed50ae&device_id=abc&area_code=310000&sig=cbd4d2b7db1750affd96865cc1fdad53

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "total": 78,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": [
        {
            "id": 1024,
            "name": "iting网络电台",
            "intro": null,
            "area": null,
            "playing_program_id": 129785,
            "playing_program_name": "音乐无人驾驶",
            "support_bitrates": null,
            "play_count": 0,
            "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_small.jpg",
            "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_large.jpg",
            "updated_at": 0,
            "kind": "radio"
            "fm": "90.9"
        },
        ...
    ]
}

38、/browse/area-fm-radio

功能

通过地区代码和频点获取电台

HTTP Method

GET

参数

QUERY参数	类型	必填	说明
fm	string	是	电台频点
area_code	string	是	行政区划代码参照国家统计局的行政区划代码行政区划代码，不传或为空时返回国家台，不为空时返回区划代码指定区域的广播电台列表。例如： 110000 表示获取北京市的电台列表， 130000 表示获取河北省的电台列表，130100 表示获取石家庄市的电台列表，目前支持获取到省市级的电台列表，如果传入区县级的地区码则返回其所属市的电台列表。(目前仅支持到省级代码)

返回值

请求成功时，http status在header中的状态码是200，http response body中包含数组元素为[Radio]的对象。

若请求出错，header中的状态码参考为500，并且response body中包含了相应错误对象ErrorResponse

示例

http://api.ximalaya.com/iot/openapi-smart-device-api/browse/area-fm-radio?app_key=53ba3200998d1cd3f4952fbb58ed50ae&access_token=53ba3200998d1cd3f4952fbb58ed50ae&device_id=abc&fm=90.0&area_code=310000&sig=cbd4d2b7db1750affd96865cc1fdad53

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    [
        {
            "id": 1024,
            "name": "iting网络电台",
            "intro": null,
            "area": null,
            "playing_program_id": 129785,
            "playing_program_name": "音乐无人驾驶",
            "support_bitrates": null,
            "play_count": 0,
            "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_small.jpg",
            "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M05/67/FA/wKgDg1T1E5CwZ8SvAAkVVGMybN8793_mobile_large.jpg",
            "updated_at": 0,
            "kind": "radio"
            "fm": "90.9"
        }
    ]
}

39、/albums/rich/{id}

功能

获取专辑的富文本信息

HTTP Method

GET

参数

PATH参数	类型	必填	说明
id	integer	是	专辑的ID

QUERY参数	类型	必填	说明
app_key	string	是	鉴别app
nonce	string	是	随机字符串，长度限制8~64
timestamp	long	是	Unix毫秒时间戳
sig	string	是	鉴权参数，见签名sig
fields	string	否	返回的字段序列，用逗号分隔，默认表示全部

返回值

请求成功时，http status在header中的状态码是200 OK，http response body中包含Program类型的对象

若请求出错，http status在header中的状态码参考[status code](#status code) 并且response body中包含了相应错误对象Error

示例

curl http://localhost:8080/albums/rich/1024?weekday=Tues&app_key=53ba3200998d1cd3f4952fbb58ed50ae&nonce=abcdefgh&timestamp=123456&sig=c4006056e5a0793ce428d31de9713486

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

{
    "id": 129785,
    "rich_intro: "xxxx",
}

Models

Album_full

字段名	类型	描述
id	long	专辑ID
kind	string	固定值”album“
title	string	专辑标题
tracks_natural_ordered	boolean	专辑中的音频是否自然序，即按照上传的先后顺序排序，先上传的音频在前，后上传的音频在后面
category_id	integer	专辑所属点播分类的ID
tags	string	专辑标签列表，包含运营标签和主播个人打的标签
intro	string	专辑简介
short_intro	string 专辑缩略简介
updated_at	long	专辑更新时间，unix毫秒时间戳
created_at	long	专辑创建时间，unix毫秒时间戳
play_count	integer	专辑被播放总次数
favorite_count	integer	专辑被点赞总次数
subscribe_count	integer	专辑被订阅总次数
share_count	integer	专辑被分享总次数
subscribe_count	integer	专辑被订阅总次数
include_track_count	integer	专辑包含音频总数
is_finished	integer	专辑是否完结, 0-无此属性；1-未完结；2-完结
is_authorized	boolean	专辑是否购买，针对付费专辑, false 未购买免费专辑为false true购买
is_paid	boolean	专辑是否是付费专辑
is_subscribe	boolean	专辑是否被订阅
can_download	boolean	专辑能否被下载到用户终端本地，禁止下载/缓存到服务器端
cover	Cover	专辑封面图
announcer	Announcer	专辑所属主播
last_update_track	[Track simplified](#track simplified)	专辑内最新上传的音频

{
    "id": 72281,
    "kind": "album",
    "title": "Secret Garden",
    "intro": null,
    "short_intro": "xxx",
    "tracks_natural_ordered": false,
    "category_id": 2,
    "tags": "",
    "updated_at": 1421769600000,
    "created_at": 1366992000000,
    "play_count": 0,
    "favorite_count": 0,
    "share_count": 0,
    "include_track_count": 16,
    "is_finished": 0,
    "can_download": false,
    "subscribe_count": 213,
    "is_authorized": false,
    "is_paid": false,
    "is_subscribe": false,
    "cover": {
        "small": {
            "height": 86,
            "width": 86,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_small.jpg"
        },
        "middle": {
            "height": 140,
            "width": 140,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_meduim.jpg"
        },
        "large": {
            "height": 290,
            "width": 290,
            "url": "http://fdfs.test.ximalaya.com/group1/M01/04/60/wKgD3lGUfReAFnlFAAIE638b4Tw963_mobile_large.jpg"
        }
    },
    "announcer": {
        "id": 1428,
        "nickname": "fred_me",
        "avatar_url": "group1/M01/33/24/wKgD3ldpBq6AGwB4AAC7BvHbd28868.jpg",
        "is_verified": true,
        "url": null,
        "popularity": 0,
        "tags": null
    },
    "last_update_track": {
        "id": 247238,
        "kind": "Track",
        "title": "后来",
        "intro": "",
        "tags": "",
        "created_at": 1421823051000,
        "updated_at": 1421823051000,
        "order_num": 0,
        "duration": 339,
        "play_count": 0,
        "favorite_count": 0,
        "comment_count": 0,
        "source": null,
        "cover": null,
        "announcer": null,
        "can_download": false,
        "album": null
    }
}

Album_simplified

字段名	类型	描述
id	long	专辑ID
kind	string	固定值”album“
title	string	专辑标题
tracks_natural_ordered	boolean	专辑中的音频是否自然序，即按照上传的先后顺序排序，先上传的音频在前，后上传的音频在后面
category_id	integer	专辑所属点播分类的ID
tags	string	专辑标签列表
updated_at	long	专辑更新时间，unix毫秒时间戳
created_at	long	专辑创建时间，unix毫秒时间戳
play_count	integer	专辑被播放总次数
favorite_count	integer	专辑被点赞总次数
share_count	integer	专辑被分享总次数
include_track_count	integer	专辑包含音频总数
is_finished	integer	专辑是否完结, 0-无此属性；1-未完结；2-完结
can_download	boolean	专辑能否被下载到用户终端本地，禁止下载/缓存到服务器端

{
        "id": 120382,
        "kind": "album",
        "title": "讲不出再见",
        "intro": null,
        "tracks_natural_ordered": false,
        "category_id": 4,
        "tags": "",
        "updated_at": 1509075422000,
        "created_at": 1506063715000,
        "play_count": 233,
        "favorite_count": 0,
        "share_count": 0,
        "include_track_count": 4,
        "is_finished": 0,
        "can_download": false,
        "cover": null,
        "announcer": null,
        "last_update_track": null
 }

Announcer

字段名	类型	描述
id	integer	主播用户ID，即喜马拉雅账号ID
nickname	string	主播用户昵称
avatar_url	string	主播用户头像图片url
is_verified	boolean	主播是否加V
url	string	获取当前主播信息的URI
popularity	integer	主播受欢迎的程度0-100
tags	string	标签数组

{
    "id": 12463,
    "nickname": "tiny133测试消息613dd",
    "avatar_url": null,
    "is_verified": true,
    "url": null,
    "popularity": 0,
    "tags": null
}

Cover

字段名	类型	描述
small	Image	分类封面小图
middle	Image	分类封面小图
large	Image	分类封面小图

{
        "small": {
            "height": 86,
            "width": 86,
            "url": "group12/M07/17/A4/wKgDW1VxNCrzTwWVAAAJnAUfyR8545.png"
        },
        "middle": {
            "height": 140,
            "width": 140,
            "url": "group12/M07/17/A1/wKgDXFVxNB6wGFwmAAAJnAUfyR8949.png"
        },
        "large": {
            "height": 290,
            "width": 290,
            "url": ""
        }
}

Error

字段名	类型	描述
status	integer	Http status code 同时在返回头中返回
message	string	简要错误信息的描述

{
    "status": 401,
    "message": "没有权限"
}

HotWord

字段名	类型	描述
hot_word	string	热搜词
degree	string	热搜词热度（昨天的搜索次数减去前天的搜索次数再减去昨天的平均搜索次数）
count	integer	该热搜词昨日被搜素次数

{
  "hot_word": "游客",
  "degree": 0,
  "count": 1
}

Image

字段名	类型	描述
height	integer	高度值
width	integer	宽度值
url	string	url地址

{
    "height": 86,
    "width": 86,
    "url": "group12/M07/17/A4/wKgDW1VxNCrzTwWVAAAJnAUfyR8545.png"
}

Page

字段名	类型	描述
items	array of objects	根据请求不同，返回对应的的类型
limit	integer	一次响应返回的最大项数
offset	integer	从第几项开始返回数据
total	integer	可返回的数据的总项数
sort	string	排序类型名

{
    "total": 7,
    "offset": 0,
    "limit": 5,
    "sort": null,
    "items": []
}

Program

字段名	类型	描述
id	long	节目ID
kind	string	类别，固定值"program"
program_name	string	节目名称
back_pic_url	string	节目背景图
support_bitrates	array(integer)	支持的码率列表，如[24,64]
live_announcers	array(Announcer)	广播节目所属主播列表
updated_at	long	更新时间，Unix毫秒数时间戳

{
    "id": 129785,
    "program_name": "音乐无人驾驶",
    "back_pic_url": null,
    "support_bitrates": [
        24,
        64
    ],
    "live_announcers": [
        {
            "id": 11485,
            "nickname": "qqtester325",
            "avatar_url": null,
            "is_verified": false,
            "url": null,
            "popularity": 0,
            "tags": null
        }
    ],
    "updated_at": 0,
    "kind": "program"
}

Radio

字段名	类型	描述
id	integer	电台ID
kind	string	类别，固定值"radio"
name	string	电台名称
intro	string	电台简介
area	string	所处区域
playing_program_id	long	正在广播的节目id
playing_program_name	string	正在广播的节目名称
support_bitrates	array(integer)	Array类型，支持的码率列表，如[24,64]
play_count	long	电台累计收听次数
small_cover_url	string	电台封面小图
large_cover_url	string	电台封面大图
updated_at	long	电台更新时间，Unix毫秒数时间戳

{
    "id": 50,
    "name": "北京音乐广播",
    "intro": null,
    "area": null,
    "playing_program_id": 152129,
    "playing_program_name": "早安音乐秀",
    "support_bitrates": null,
    "play_count": 0,
    "small_cover_url": "http://fdfs.test.ximalaya.com/group6/M03/A9/12/wKgDhFUKl0Gjo2fwAABRqWHVL_g976_mobile_small.jpg",
    "large_cover_url": "http://fdfs.test.ximalaya.com/group6/M03/A9/12/wKgDhFUKl0Gjo2fwAABRqWHVL_g976_mobile_large.jpg",
    "updated_at": 1476463378000,
    "kind": "radio"
}

Rank

字段名	类型	描述
id	integer	榜单ID
key	string	标识榜单的字符串
kind	string	固定值”rank“
title	string	榜单标题
sub_title	string	榜单副标题
period	integer	榜单计算周期，单位为天
period_type	string	榜单计算周期类型，如：“日榜”，“周榜”
item_count	integer	榜单内条目总数
order_num	integer	该榜单相对其他榜单的排序值，越小越靠前
cover_url	string	榜单封面图URL
category_id	integer	榜单所属分类ID
content_type	string	榜单内容类型，album- 专辑类型， track- 音频类型
rank_items	array(RankItem)	榜单包含的条目

{
    "id": 21,
    "key": "1_21_ranking:album:played:30:0",
    "title": "经典必听榜",
    "sub_title": "真相来了！榜单出炉，不服来辩！",
    "period": 30,
    "period_type": "PERIOD_MONTH",
    "item_count": 0,
    "order_num": 0,
    "cover_url": "http://fdfs.xmcdn.com/group11/M0B/17/D9/wKgDbVVxRmPRLf9JAABdZjkfM4Y496.png",
    "category_id": 0,
    "content_type": "album",
    "rank_items": [
        {
            "type": "album",
            "id": 203355,
            "title": "段子来了"
        },
        {
            "type": "album",
            "id": 10925666,
            "title": "《安利全集》FC成冠超凡环宇卓越冠宇贝瑞德福呗增付后坚周志坚郭洪斌孙东微信12983200"
        }
    ],
    "kind": "rank"
}

RankItem

字段名	类型	描述
content_type	string	条目内容类型 track-音频类型条目，album-专辑类型条目
id	long	内容ID（音频ID/专辑ID）
title	string	内容的标题（音频标题/专辑标题）

{
    "type": "album",
    "id": 203355,
    "title": "段子来了"
}

Resources

字段名	类型	描述
url	string	资源地址
size	integer	资源占用存储空间的大小,以字节计算

{
    "url": "http://fdfs.cdn.com/12312/abc",
    "size": 1000
}

Schedule

字段名	类型	描述
id	integer	节目时间表ID，schedule id
radio_id	integer	所属广播电台ID
kind	string	固定值"schedule"
start_time	string	节目开始时间，例：09:00
end_time	string	节目结束时间，例：10:00
updated_at	long	更新时间，Unix毫秒数时间戳
related_program	Program	关联的广播节目

{
    "id": 156353,
    "radio_id": 1024,
    "start_time": "23:00",
    "end_time": "00:00",
    "update_at": 1431939568000,
    "related_program": null,
    "kind": "schedule"
}

Tag

字段名	类型	描述
name	string	标签名称
kind	string	固定值“tag”

{
    "name": "金融",
    "kind": "tag"
}

Track_full

字段名	类型	描述
id	long	音频id
kind	string	类型, 固定值“track”
title	string	标题
intro	string	简介
tags	string	标签列表
created_at	long	创建时间
updated_at	long	更新时间
order_num	integer	音频在专辑中的排序值，从0开始依次递增，值越小排序越前
duration	integer	音频时长，单位毫秒
play_count	long	音频被播放总次数
favorite_count	long	音频被点赞总次数
comment_count	long	音频被评论总次数
source	integer	音频来源，1-用户原创，2-转采自其它专辑
cover	Image	封面图片
announcer	Announcer	音频所属主播
can_download	boolean	能否被下载到用户终端本地，禁止下载/缓存到服务器端
album	Album_simplified	音频所属专辑

{
    "id": 358558,
    "kind": "Track",
    "title": "张学友-用余生去爱",
    "intro": "",
    "tags": "",
    "created_at": 1506063721000,
    "updated_at": 1509075422000,
    "order_num": 0,
    "duration": 254,
    "play_count": 68,
    "favorite_count": 0,
    "comment_count": 2,
    "source": null,
    "cover": null,
    "announcer": {
        "id": 59181,
        "nickname": "奇葩公社啦_007",
        "avatar_url": "group1/M01/4E/52/wKgD3lmndjWAA-3lAAD1E7taeF0293.jpg",
        "is_verified": true,
        "url": null,
        "popularity": 0,
        "tags": null
    },
    "can_download": false,
    "album": {
        "id": 120382,
        "kind": "album",
        "title": "讲不出再见",
        "intro": null,
        "tracks_natural_ordered": false,
        "category_id": 4,
        "tags": "",
        "updated_at": 1509075422000,
        "created_at": 1506063715000,
        "play_count": 233,
        "favorite_count": 0,
        "share_count": 0,
        "include_track_count": 4,
        "is_finished": 0,
        "can_download": false,
        "cover": null,
        "announcer": null,
        "last_update_track": null
    }
}

Track_simplified

字段名	类型	描述
id	long	音频id
kind	string	类型, 固定值“track”
title	string	标题
intro	string	简介
tags	string	标签列表
created_at	long	创建时间
updated_at	long	更新时间
order_num	integer	音频在专辑中的排序值，从0开始依次递增，值越小排序越前
duration	integer	音频时长，单位毫秒
play_count	long	音频被播放总次数
favorite_count	long	音频被点赞总次数
comment_count	long	音频被评论总次数
source	integer	音频来源，1-用户原创，2-转采自其它专辑

{
    "id": 247238,
    "kind": "Track",
    "title": "后来",
    "intro": "",
    "tags": "",
    "created_at": 1421823051000,
    "updated_at": 1421823051000,
    "order_num": 0,
    "duration": 339,
    "play_count": 0,
    "favorite_count": 0,
    "comment_count": 0,
    "source": null,
    "cover": null,
    "announcer": null,
    "can_download": false
}

TrackPlayRecord

字段名	类型	描述
track_id	long	音频id
duration	integer	播放时长，即本次一共播放了多长时间，单位为毫秒
played_at	integer	播放到多少毫秒或最后播放到的位置，相对于音频开始位置
started_at	integer	播放开始时刻，毫秒时间戳
play_type	integer	播放类型：0-在线播放，1-离线播放

{
    "track_id": 10347,
    "duration": 180,
    "played_secs": 300,
    "started_at": 1504695227000,
    "paly_type": 0
}

ErrorResponse

字段名	类型	描述
timestamp	long	毫秒时间错
status	integer	http 错误状态代码
error	string	业务错误代码
message	string	错误描述信息
path	string	访问路径

其中error取值描述信息如下：

错误码	描述信息
5000	其它错误
5001	thrift服务调用异常
5002	http服务调用异常
5003	权限验证错误
5004	某资源未发现引发的错误
5005	业务限制导致错误
5006	程序运行时产生的错误（比如操作数据有误导致出错）

{
    "timestamp": 1510649738100,
    "status": 500,
    "error": "5003",
    "message": "authentication error!",
    "path": "/ranks"
}

字段名	类型	描述
id	integer	分类ID
kind	string	固定值“album-category”表示声音或专辑的分类，“announcer-category"表示主播的分类，”radio-category"表示广播的分类
category_name	string	分类名称
order_num	integer	该分类在所有分类中的排序值，值越小排序越靠前
cover	Cover	分类封面图，只有album-categroy有值