379
edits
Changes
Новая страница: «==Description== Search API allows to search content in the Ace Stream P2P Network. It can be accessed by two ways: *using Ace Stream Engine endpoint *using serve…»
==Description==
Search API allows to search content in the Ace Stream P2P Network.
It can be accessed by two ways:
*using Ace Stream Engine endpoint
*using server-side endpoint
There are several differences between these two methods.
Engine search API:
*is free to use
*has a limit of total requests coming from certain engine instance per day
*has a limit on requests frequency
*is suitable for making search requests from installed applications
Server-side search API:
*is not free
*has no limits
*allows to get search database snapshot
*is suitable for making server-to-server API calls
==Engine Search API==
Endpoint:
<tt><nowiki>http://localhost:6878/server/api</nowiki></tt>
Ace Stream Engine must be running on the localhost.
Mandatory parameters:
*'''method''' - API method name
*'''token''' - Engine API access token (see below)
Each request must contain Engine API access token which must be retrieved by this request:
<tt><nowiki>http://localhost:6878/server/api?method=get_api_access_token</nowiki></tt>
Token is sent in the response:
<tt><nowiki>{
"result": {
"token": "9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57"
},
"error": null
}</nowiki></tt>
Method "get_api_access_token" does not allow cross-domain requests so it cannot be called from regular javascript on the web page.
==Server-side Search API==
Endpoint:
<tt><nowiki>https://search.acestream.net</nowiki></tt>
Mandatory parameters:
*'''method''' - API method name
*'''api_version''' - API version (currently it must be set to 1.0)
*'''api_key''' - API key (your personal key)
To obtain you personal API key you must register and request it.
Currently server-side API works in beta-testing mode and is available with API key "test_api_key".
==Response format==
All responses are in JSON format.
General response format is:
*success
<tt><nowiki>{
"result": <object>,
"error": null
}</nowiki></tt>
*error
<tt><nowiki>{
"result": null,
"error": "error description"
}</nowiki></tt>
==API methods==
===search===
Makes a search request
Parameters:
*'''query''' (string) - search query
*'''category''' (string) - filter by category (list of categories [[Channel Category|here]])
*'''page''' (integer) - page number (starting from 0, default is 0)
*'''page_size''' (integer) - page size (default is 10, maximum value is 50)
*'''group_by_channels''' (boolean, 0 or 1) - group output results by channel name (see examples)
*'''show_epg''' (boolean, 0 or 1) - include EPG in the response (this works only when group_by_channels=1)
Response fields:
*'''total''' (integer) - total number of found items
*'''results''' (array of objects) - array of results (each result is an object, see below)
*'''time''' (float) - query execution time
Single item fields:
*'''infohash''' (string) - channel infohash (unique identifier); it should be used to start channel playback
*'''name''' (string) - channel name
*'''bitrate''' (integer) - channel estimated bitrate (bytes per second)
*'''categories''' (array of strings) - channel categories
*'''availability_updated_at''' (integer) - unix timestamp when channel availability was last updated at
*'''availability''' (float) - channel availability (number between 0-1)
*'''in_playlist''' (boolean) - true if the channel is included in user's playlist (available only on engine endpoint)
==Examples==
===Simple output===
*engine endpoint
<tt><nowiki>http://localhost:6878/server/api?method=search ↵
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵
&query=discovery</nowiki></tt>
*server-side endpoint
<tt><nowiki>https://search.acestream.net/?method=search ↵
&api_version=1.0 ↵
&api_key=test_api_key ↵
&query=discovery</nowiki></tt>
Response:
<tt><nowiki>{
"result": {
"total": 28,
"results": [
{
"name": "Discovery HD",
"bitrate": 506347,
"availability_updated_at": 1494970802,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
},
{
"name": "Discovery HD Showcase",
"bitrate": 504510,
"availability_updated_at": 1494970802,
"infohash": "948e1b51363cc07ec4ac20ef10dc099f8c7e20b8",
"availability": 1,
"categories": [
"educational"
]
},
... # some results are omitted
],
"time": "0.0237"
},
"error": null
}</nowiki></tt>
===Grouped by channel name results===
*engine endpoint:
<tt><nowiki>http://localhost:6878/server/api?method=search ↵
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵
&query=discovery ↵
&group_by_channels=1 ↵
&show_epg=1</nowiki></tt>
*server-side endpoint:
<tt><nowiki>https://search.acestream.net/?method=search ↵
&api_version=1.0 ↵
&api_key=test_api_key ↵
&query=discovery ↵
&group_by_channels=1 ↵
&show_epg=1</nowiki></tt>
Response:
<tt><nowiki>{
"result": {
"total": 11,
"results": [
{
"items": [
{
"status": 2,
"name": "Discovery HD",
"bitrate": 506347,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
}
],
"name": "Discovery HD"
},
{
"items": [
{
"status": 2,
"name": "Discovery Channel",
"bitrate": 215035,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "6651feec9de120abf362c380841150cdc2742df2",
"availability": 0.99282296650718,
"categories": [
"educational"
]
},
{
"status": 1,
"name": "Discovery Channel",
"infohash": "e97bbddc4febc01f649c30013fd221e9adf43622",
"channel_id": 845,
"availability_updated_at": 1494964321,
"availability": 1,
"categories": [
"tv"
]
}
],
"name": "Discovery Channel"
},
{
"items": [
{
"status": 2,
"in_playlist": false,
"name": "Discovery Science",
"bitrate": 350000,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "dacdcf48e9238d23d7bd687c8e00cac0d16dc177",
"availability": 1,
"categories": [
"educational"
]
},
{
"status": 2,
"name": "Discovery Science",
"bitrate": 215035,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "c2c2c2bfda8440ae0781df0e06ccf13dda529737",
"availability": 0.98648648648649,
"categories": [
"educational"
]
}
],
"icon": "http://c1.torrentstream.info/epg/icons/3349.png",
"name": "Discovery Science",
"epg": {
"start": "1494970200",
"stop": "1494971700",
"name": "Как это сделано? (20-я серия) (12+)"
}
},
... # some results are omitted
],
"time": "0.0421"
},
"error": null
}</nowiki></tt>
Search API allows to search content in the Ace Stream P2P Network.
It can be accessed by two ways:
*using Ace Stream Engine endpoint
*using server-side endpoint
There are several differences between these two methods.
Engine search API:
*is free to use
*has a limit of total requests coming from certain engine instance per day
*has a limit on requests frequency
*is suitable for making search requests from installed applications
Server-side search API:
*is not free
*has no limits
*allows to get search database snapshot
*is suitable for making server-to-server API calls
==Engine Search API==
Endpoint:
<tt><nowiki>http://localhost:6878/server/api</nowiki></tt>
Ace Stream Engine must be running on the localhost.
Mandatory parameters:
*'''method''' - API method name
*'''token''' - Engine API access token (see below)
Each request must contain Engine API access token which must be retrieved by this request:
<tt><nowiki>http://localhost:6878/server/api?method=get_api_access_token</nowiki></tt>
Token is sent in the response:
<tt><nowiki>{
"result": {
"token": "9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57"
},
"error": null
}</nowiki></tt>
Method "get_api_access_token" does not allow cross-domain requests so it cannot be called from regular javascript on the web page.
==Server-side Search API==
Endpoint:
<tt><nowiki>https://search.acestream.net</nowiki></tt>
Mandatory parameters:
*'''method''' - API method name
*'''api_version''' - API version (currently it must be set to 1.0)
*'''api_key''' - API key (your personal key)
To obtain you personal API key you must register and request it.
Currently server-side API works in beta-testing mode and is available with API key "test_api_key".
==Response format==
All responses are in JSON format.
General response format is:
*success
<tt><nowiki>{
"result": <object>,
"error": null
}</nowiki></tt>
*error
<tt><nowiki>{
"result": null,
"error": "error description"
}</nowiki></tt>
==API methods==
===search===
Makes a search request
Parameters:
*'''query''' (string) - search query
*'''category''' (string) - filter by category (list of categories [[Channel Category|here]])
*'''page''' (integer) - page number (starting from 0, default is 0)
*'''page_size''' (integer) - page size (default is 10, maximum value is 50)
*'''group_by_channels''' (boolean, 0 or 1) - group output results by channel name (see examples)
*'''show_epg''' (boolean, 0 or 1) - include EPG in the response (this works only when group_by_channels=1)
Response fields:
*'''total''' (integer) - total number of found items
*'''results''' (array of objects) - array of results (each result is an object, see below)
*'''time''' (float) - query execution time
Single item fields:
*'''infohash''' (string) - channel infohash (unique identifier); it should be used to start channel playback
*'''name''' (string) - channel name
*'''bitrate''' (integer) - channel estimated bitrate (bytes per second)
*'''categories''' (array of strings) - channel categories
*'''availability_updated_at''' (integer) - unix timestamp when channel availability was last updated at
*'''availability''' (float) - channel availability (number between 0-1)
*'''in_playlist''' (boolean) - true if the channel is included in user's playlist (available only on engine endpoint)
==Examples==
===Simple output===
*engine endpoint
<tt><nowiki>http://localhost:6878/server/api?method=search ↵
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵
&query=discovery</nowiki></tt>
*server-side endpoint
<tt><nowiki>https://search.acestream.net/?method=search ↵
&api_version=1.0 ↵
&api_key=test_api_key ↵
&query=discovery</nowiki></tt>
Response:
<tt><nowiki>{
"result": {
"total": 28,
"results": [
{
"name": "Discovery HD",
"bitrate": 506347,
"availability_updated_at": 1494970802,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
},
{
"name": "Discovery HD Showcase",
"bitrate": 504510,
"availability_updated_at": 1494970802,
"infohash": "948e1b51363cc07ec4ac20ef10dc099f8c7e20b8",
"availability": 1,
"categories": [
"educational"
]
},
... # some results are omitted
],
"time": "0.0237"
},
"error": null
}</nowiki></tt>
===Grouped by channel name results===
*engine endpoint:
<tt><nowiki>http://localhost:6878/server/api?method=search ↵
&token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵
&query=discovery ↵
&group_by_channels=1 ↵
&show_epg=1</nowiki></tt>
*server-side endpoint:
<tt><nowiki>https://search.acestream.net/?method=search ↵
&api_version=1.0 ↵
&api_key=test_api_key ↵
&query=discovery ↵
&group_by_channels=1 ↵
&show_epg=1</nowiki></tt>
Response:
<tt><nowiki>{
"result": {
"total": 11,
"results": [
{
"items": [
{
"status": 2,
"name": "Discovery HD",
"bitrate": 506347,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "09f1511aa2a596162bfb4f4d1146c2be545733f4",
"availability": 1,
"categories": [
"educational"
]
}
],
"name": "Discovery HD"
},
{
"items": [
{
"status": 2,
"name": "Discovery Channel",
"bitrate": 215035,
"channel_id": 845,
"availability_updated_at": 1494971282,
"infohash": "6651feec9de120abf362c380841150cdc2742df2",
"availability": 0.99282296650718,
"categories": [
"educational"
]
},
{
"status": 1,
"name": "Discovery Channel",
"infohash": "e97bbddc4febc01f649c30013fd221e9adf43622",
"channel_id": 845,
"availability_updated_at": 1494964321,
"availability": 1,
"categories": [
"tv"
]
}
],
"name": "Discovery Channel"
},
{
"items": [
{
"status": 2,
"in_playlist": false,
"name": "Discovery Science",
"bitrate": 350000,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "dacdcf48e9238d23d7bd687c8e00cac0d16dc177",
"availability": 1,
"categories": [
"educational"
]
},
{
"status": 2,
"name": "Discovery Science",
"bitrate": 215035,
"channel_id": 851,
"availability_updated_at": 1494971282,
"infohash": "c2c2c2bfda8440ae0781df0e06ccf13dda529737",
"availability": 0.98648648648649,
"categories": [
"educational"
]
}
],
"icon": "http://c1.torrentstream.info/epg/icons/3349.png",
"name": "Discovery Science",
"epg": {
"start": "1494970200",
"stop": "1494971700",
"name": "Как это сделано? (20-я серия) (12+)"
}
},
... # some results are omitted
],
"time": "0.0421"
},
"error": null
}</nowiki></tt>