Search API

From Ace Stream Wiki
Jump to: navigation, search

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
}