Search API
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 not free
- has no limits
- allows to get search database snapshot
- is suitable for making server-to-server API calls
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.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
{ "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 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)
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.0&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.0 ↵ &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.0 ↵ &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 }