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 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
}