Difference between revisions of "Search API"
(→search) |
(→Grouped by channel name results) |
||
(6 intermediate revisions by 2 users not shown) | |||
Line 15: | Line 15: | ||
Server-side search API: | Server-side search API: | ||
− | *is | + | *is paid |
+ | Server-side search API provides 1000 search queries for free. If you need more, you may sign up for billing in the the admin-panel. Additional requests cost $1 per 10000 queries. | ||
*has no limits | *has no limits | ||
*allows to get search database snapshot | *allows to get search database snapshot | ||
Line 54: | Line 55: | ||
Mandatory parameters: | Mandatory parameters: | ||
*'''method''' - API method name | *'''method''' - API method name | ||
− | *'''api_version''' - API version (currently it must be set to 1 | + | *'''api_version''' - API version (currently it must be set to 1) |
*'''api_key''' - API key (your personal key) | *'''api_key''' - API key (your personal key) | ||
− | To obtain | + | To obtain your 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". | + | Currently, server-side API works in beta-testing mode and is available with API key "test_api_key". |
==Response format== | ==Response format== | ||
Line 84: | Line 85: | ||
*'''category''' (string) - filter by category (list of categories [[Channel Category|here]]) | *'''category''' (string) - filter by category (list of categories [[Channel Category|here]]) | ||
*'''page''' (integer) - page number (starting from 0, default is 0) | *'''page''' (integer) - page number (starting from 0, default is 0) | ||
− | *'''page_size''' (integer) - page size (default is 10, maximum value is | + | *'''page_size''' (integer) - page size (default is 10, maximum value is 200) |
*'''group_by_channels''' (boolean, 0 or 1) - group output results by channel name (see examples) | *'''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) | *'''show_epg''' (boolean, 0 or 1) - include EPG in the response (this works only when group_by_channels=1) | ||
Line 100: | Line 101: | ||
*'''availability_updated_at''' (integer) - unix timestamp when channel availability was last updated at | *'''availability_updated_at''' (integer) - unix timestamp when channel availability was last updated at | ||
*'''availability''' (float) - channel availability (number between 0-1) | *'''availability''' (float) - channel availability (number between 0-1) | ||
− | *'''status''' (integer) - channel status based on its availability; 2 means "green" status - channel is available; 1 means "yellow" status - there is no guaranty that channel is working | + | *'''status''' (integer) - channel status based on its availability; 2 means "green" status - channel is available; 1 means "yellow" status - there is no guaranty that channel is working. Can be used in query as additional filter. |
*'''in_playlist''' (boolean) - true if the channel is included in user's playlist (available only on engine endpoint) | *'''in_playlist''' (boolean) - true if the channel is included in user's playlist (available only on engine endpoint) | ||
Line 111: | Line 112: | ||
Example: | Example: | ||
− | <tt><nowiki>https://search.acestream.net/all?api_version=1 | + | <tt><nowiki>https://search.acestream.net/all?api_version=1&api_key=test_api_key</nowiki></tt> |
==Examples== | ==Examples== | ||
Line 122: | Line 123: | ||
*server-side endpoint | *server-side endpoint | ||
<tt><nowiki>https://search.acestream.net/?method=search ↵ | <tt><nowiki>https://search.acestream.net/?method=search ↵ | ||
− | &api_version=1 | + | &api_version=1 ↵ |
&api_key=test_api_key ↵ | &api_key=test_api_key ↵ | ||
&query=discovery</nowiki></tt> | &query=discovery</nowiki></tt> | ||
Line 167: | Line 168: | ||
*server-side endpoint: | *server-side endpoint: | ||
<tt><nowiki>https://search.acestream.net/?method=search ↵ | <tt><nowiki>https://search.acestream.net/?method=search ↵ | ||
− | &api_version=1 | + | &api_version=1 ↵ |
&api_key=test_api_key ↵ | &api_key=test_api_key ↵ | ||
&query=discovery ↵ | &query=discovery ↵ |
Latest revision as of 01:39, 15 November 2019
Contents
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 paid
Server-side search API provides 1000 search queries for free. If you need more, you may sign up for billing in the the admin-panel. Additional requests cost $1 per 10000 queries.
- has no limits
- allows to get search database snapshot
- is suitable for making server-to-server API calls
Beta testing period
Server-side Search API is currently in beta testing and is free to use.
You can get personal API keys in the admin-panel at www.acestream.org after the end of the beta testing period of Ace Stream Search API.
Engine Search API
Endpoint:
http://localhost:6878/server/api
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:
http://localhost:6878/server/api?method=get_api_access_token
Token is sent in the response:
{ "result": { "token": "9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57" }, "error": null }
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:
https://search.acestream.net
Mandatory parameters:
- method - API method name
- api_version - API version (currently it must be set to 1)
- api_key - API key (your personal key)
To obtain your 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
{ "result": <object>, "error": null }
- error
{ "result": null, "error": "error description" }
API methods
search
Makes a search request
Parameters:
- query (string) - search query
- category (string) - filter by category (list of categories here)
- page (integer) - page number (starting from 0, default is 0)
- page_size (integer) - page size (default is 10, maximum value is 200)
- 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)
- status (integer) - channel status based on its availability; 2 means "green" status - channel is available; 1 means "yellow" status - there is no guaranty that channel is working. Can be used in query as additional filter.
- in_playlist (boolean) - true if the channel is included in user's playlist (available only on engine endpoint)
all
This method retrieves search database snapshot.
Data is returned "as-is": there is no filtering, sorting or pagination.
IMPORTANT: this method is available on server-side endpoint only.
Example:
https://search.acestream.net/all?api_version=1&api_key=test_api_key
Examples
Simple output
- engine endpoint
http://localhost:6878/server/api?method=search ↵ &token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵ &query=discovery
- server-side endpoint
https://search.acestream.net/?method=search ↵ &api_version=1 ↵ &api_key=test_api_key ↵ &query=discovery
Response:
{ "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 }
Grouped by channel name results
- engine endpoint:
http://localhost:6878/server/api?method=search ↵ &token=9d324ef909c50629ca3d23faddaa7358236b0bbe62dfd049416dc4d570b60b57 ↵ &query=discovery ↵ &group_by_channels=1 ↵ &show_epg=1
- server-side endpoint:
https://search.acestream.net/?method=search ↵ &api_version=1 ↵ &api_key=test_api_key ↵ &query=discovery ↵ &group_by_channels=1 ↵ &show_epg=1
Response:
{ "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 }