# API Docs for audio streams

{% hint style="info" %}
The music recognition costs $45 per audio stream per month with our music DB. Or $25 per stream per month if you have your own content that you want to recognize instead of using our music DB. In the second case, contact us: <api@audd.io>.
{% endhint %}

We wanted to make the API as simple as possible: you send us the URLs of radio streams, we send you the recognition results in real-time.\
If you don't have a server to receive the results and just want to download reports as e.g. tables, contact us. You'll be able to use our service without interacting with the API.

## Here's how you use it:

### 1. Set the limit of audio streams and pay

Set the limit of audio streams and pay [using our Telegram bot](https://t.me/auddbot?start=streams).\
**Please note that all the API requests require the api\_token from the bot to be specified as either the query parameter or the POST field.** So just send it in all the requests as `api_token`.\
By the way, if you change the limit later, the unused amount will be applied as a discount.

## 2. Set the URL for callbacks

<mark style="color:green;">`POST`</mark> `https://api.audd.io/setCallbackUrl/`

Set the URL for callbacks using the `setCallbackUrl` API method.\
You can change the URL at any time using this method.\
Callbacks are the requests with recognition results our servers will send to your server.

#### Request Body

| Name       | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| api\_token | string | The token received from the bot |
| url        | string | The URL for the callbacks       |

{% tabs %}
{% tab title="200 The callback URL is successfully set" %}

```javascript
{
    "status": "success",
    "result": null
}
```

{% endtab %}
{% endtabs %}

## 3. Add the streams

<mark style="color:green;">`POST`</mark> `https://api.audd.io/addStream/`

Add the streams using the `addStream` API method.

#### Request Body

| Name       | Type    | Description                                                                                                                                                                                                                                                                                                        |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| api\_token | string  | The token received from the bot                                                                                                                                                                                                                                                                                    |
| url        | string  | The URL of the audio stream                                                                                                                                                                                                                                                                                        |
| radio\_id  | integer | Any integer that will identify this stream                                                                                                                                                                                                                                                                         |
| callbacks  | string  | By default, callbacks are sent after the song ended playing and contain the total streamed time of the song. Set this parameter to "before", if you want to receive the callbacks as soon as a song started playing (not when it ended). *In this case, you won't receive the total played time in the callbacks.* |

{% tabs %}
{% tab title="200 The stream is successfully added" %}

```javascript
{
    "status": "success",
    "result": null
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
As the URL of the audio stream, you can simply send the URL of a stream, like *<https://npr-ice.streamguys1.com/live.mp3>*.

We also natively support Twitch and YouTube live streams, and you can send *twitch:\[channel name]* and *youtube:\[video id]* as the URL - like *twitch:monstercat* or *youtube:5qap5aO4i9A*.
{% endhint %}

### 4. Receive the results

Receive the results in the callbacks.\
The callbacks will be sent to the specified URL as a JSON structure in the POST payload. The format is bellow.\
You'll receive callbacks with results and with notifications.

* The results contain the recognized songs.
* Notifications are information about problems with the streams. If something happens to an audio stream, we'll let you know by sending a notification so you can fix the stream or change its URL. There are 3 codes: `0` (which means that everything's fine), `650` (which means that we can't connect to the stream) and `651` (which means that we don't receive any music from the stream, only white noise). Notifications also contain the time of sending. <br>

{% tabs %}
{% tab title="Callback with a result" %}

```javascript
{
  "status": "success",
  "result": {
    "radio_id": 7,
    "timestamp": "2020-04-13 10:31:43",
    "play_length": 111,
    "results": [
      {
        "artist": "Alan Walker, A$AP Rocky",
        "title": "Live Fast (PUBGM)",
        "album": "Live Fast (PUBGM)",
        "release_date": "2019-07-25",
        "label": "MER Recordings",
        "score": 100,
        "song_link": "https://lis.tn/LiveFastPUBGM"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="Callback with a notification" %}

```javascript
{
  "status": "-",
  "notification": {
    "radio_id": 3,
    "stream_running": false,
    "notification_code": 650,
    "notification_message": "Recognition failed: can't connect to the audiostream"
  },
  "time":1587939136
}
```

{% endtab %}
{% endtabs %}

#### If you want additional metadata to be returned (e.g. Apple Music, Spotify, MusicBrainz metadata) with the callbacks, contact us.

If your server doesn't respond to the callbacks with the 200 OK status or we can't connect to your server, we'll put the callbacks to a queue. When your server is back online, we'll send all the backlog.

We have a rate limit for the requests we're sending: you'll not receive more than 3 callbacks per second (with a [burst size](http://en.wikipedia.org/wiki/Token_bucket) of 15).&#x20;

## What else can I do?

We have additional methods for the full management of the streams.

## Get the current callback URL

<mark style="color:green;">`POST`</mark> `https://api.audd.io/getCallbackUrl`

Use the `getCallbackUrl` method to get the current callback URL. You can always change it with the `setCallbackUrl` method.

#### Request Body

| Name       | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| api\_token | string | The token received from the bot |

{% tabs %}
{% tab title="200 The current callback URL is showed" %}

```javascript
{
    "status": "success",
    "result": "https://yourwebsite.com/callbacks_handler/"
}
```

{% endtab %}
{% endtabs %}

## Get all the streams

<mark style="color:green;">`POST`</mark> `https://api.audd.io/getStreams/`

Use the `getStreams` method to get all the streams the music is being recognized from.

#### Request Body

| Name       | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| api\_token | string | The token received from the bot |

{% tabs %}
{% tab title="200 Returns the array of all the streams you sent us " %}

```javascript
{
    "status": "success",
    "result": [
        {
            "radio_id": 3249,
            "url": "https://npr-ice.streamguys1.com/live.mp3",
            "stream_running": true
        },
        {
            "radio_id": 5512,
            "url": "youtube:5qap5aO4i9A",
            "stream_running": true
        },
        {
            "radio_id": 5513,
            "url": "twitch:monstercat",
            "stream_running": true
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

## Delete a stream

<mark style="color:green;">`POST`</mark> `https://api.audd.io/deleteStream/`

Use the `deleteStream` method to delete a stream. We'll stop to recognize music from it and forget about it's existence.

#### Request Body

| Name       | Type    | Description                     |
| ---------- | ------- | ------------------------------- |
| radio\_id  | integer |                                 |
| api\_token | string  | The token received from the bot |

{% tabs %}
{% tab title="200 The stream is successfully deleted" %}

```javascript
{
    "status": "success",
    "result": null
}
```

{% endtab %}
{% endtabs %}

## How to send API requests?

You can send all the fields as GET URL parameters or as POST form data parameters.

Here are examples of how to send a request by POST:

{% tabs %}
{% tab title="Curl" %}

```bash
curl https://api.audd.io/addStream/ \
    -F url='https://npr-ice.streamguys1.com/live.mp3' \
    -F radio_id='3249' \
    -F api_token='your api token'
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$data = [
    'url' => 'https://npr-ice.streamguys1.com/live.mp3',
    'radio_id' => '3249',
    'api_token' => 'your api token',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://api.audd.io/addStream/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
data = {
    'url': 'https://npr-ice.streamguys1.com/live.mp3',
    'radio_id': '3249',
    'api_token': 'your api token'
}
result = requests.post('https://api.audd.io/addStream/', data=data)
print(result.text)
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"fmt"
	"github.com/AudDMusic/audd-go"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	client := audd.NewClient("your api token")
	Url := "https://npr-ice.streamguys1.com/live.mp3"
	err := client.AddStream(Url, 3249, "", nil)
	if err != nil {
		panic(err)
	}
}
```

{% endtab %}

{% tab title="JS" %}

```javascript
//requires jQuery
var data = {
    'url': 'https://npr-ice.streamguys1.com/live.mp3',
    'radio_id': '3249',
    'api_token': 'your api token'}

$.getJSON('https://api.audd.io/addStream/?jsonp=?', data, function(result){
    console.log(result);
});
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
var request = require("request");

var data = {
    'url': 'https://npr-ice.streamguys1.com/live.mp3',
    'radio_id': '3249',
    'api_token': 'your api token'
};

request({
    uri: 'https://api.audd.io/addStream/',
    form: data,
    method: 'POST'
  }, function (err, res, body) {
    console.log(body);
});
```

{% endtab %}

{% tab title="Java" %}

```java
// requires OkHttp 
public static void main() {
try {
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("url", "https://npr-ice.streamguys1.com/live.mp3")
    .addFormDataPart("radio_id", "3249")
    .addFormDataPart("api_token", "your api token").build();
Request request = new Request.Builder().url("https://api.audd.io/addStream/")
    .post(data).build();
Response response = null;
response = client.newCall(request).execute();
String result = null;
result = response.body().string();
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
//Thanks to Yaniv Levy and Adam Cole for the help
```

{% endtab %}
{% endtabs %}

You can also use GET requests, even though it's better to send the parameters in the POST body. Here's an example:\
[`https://api.audd.io/getStreams/?api_token=your%20api%20token`](https://api.audd.io/getStreams/?api_token=your%20api%20token)\
Just don't forget to url-encode the data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://audd.gitbook.io/audd/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.