├── .gitbook └── assets │ ├── tunein-api-img-test (1).png │ ├── tunein-api-img-test.png │ └── tunein-api-img.png ├── LICENSE ├── README.md ├── SUMMARY.md ├── api-basics └── getting-started.md ├── credits-basis-and-helpful-resources └── credits-basis-and-helpful-resources.md ├── endpoints-and-streaming └── endpoints │ └── search-endpoint │ └── outline-attributes-and-meaning.md ├── endpoints ├── README.md ├── browse-endpoint │ ├── README.md │ ├── browse-location-ids.md │ ├── browsing-categories.md │ └── filter-parameter.md ├── describe-endpoint │ ├── README.md │ └── response-fields-and-meaning.md ├── search-endpoint │ ├── README.md │ ├── genre-ids-and-meaning.md │ └── outline-attributes-and-meaning.md └── tune-endpoint │ └── README.md └── intro-to-streaming ├── README.md ├── how-to-stream.md └── the-.m3u-extension.md /.gitbook/assets/tunein-api-img-test (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/core-hacked/tunein-api/9342a77698cfaf17b85eb9f7852ee254530bcd97/.gitbook/assets/tunein-api-img-test (1).png -------------------------------------------------------------------------------- /.gitbook/assets/tunein-api-img-test.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/core-hacked/tunein-api/9342a77698cfaf17b85eb9f7852ee254530bcd97/.gitbook/assets/tunein-api-img-test.png -------------------------------------------------------------------------------- /.gitbook/assets/tunein-api-img.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/core-hacked/tunein-api/9342a77698cfaf17b85eb9f7852ee254530bcd97/.gitbook/assets/tunein-api-img.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 core 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | This is unofficial documentation of TuneIn's Streaming API, used by them to 4 | provide web radio streams and podcasts/shows to its users. You are always 5 | welcome to contribute. 6 | cover: .gitbook/assets/tunein-api-img-test.png 7 | coverY: 0 8 | --- 9 | 10 | # 👋 Introduction 11 | 12 | {% hint style="info" %} 13 | This documentation is still in its early stages. You are welcome to contribute, point out unclarity, or add new endpoints/documentation [via GitHub](https://github.com/core-hacked/tunein-api/pulls). 14 | {% endhint %} 15 | 16 | ## Before You Begin 17 | 18 | The base URI for all requests is `https://opml.radiotime.com` you will use this to get the data necessary to stream/play music or podcasts. 19 | 20 | ## API Organization 21 | 22 | The API is organized into three parts. 23 | 24 | [1. The API basics, like this introduction and information on how to get started. ](./) 25 | 26 | [2. T](broken-reference/)[he endpoints, additional information on their response fields/data and how to stream music from the API.](endpoints/) 27 | 28 | [3. Credits, helpful resources & basis for the documentation.](broken-reference/) 29 | 30 | #### Meaning of different colors within the API Documentation. 31 | 32 | | Color | Description | 33 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | 34 | | Yellow | Simplified explanation/TL:DR or used as a "warning" due to the elements or parameters etc. not being fully understood or unknown meaning of the said element. | 35 | | Blue | Usually representing a link or information. | 36 | | Green | Representing something safe. | 37 | | Red | Representing something unsafe. | 38 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | ## API Basics 4 | 5 | * [👋 Introduction](README.md) 6 | * [🤔 Getting Started](api-basics/getting-started.md) 7 | 8 | ## Endpoints & Streaming 9 | 10 | * [🔗 Endpoints](endpoints/README.md) 11 | * [🌐 Browse Endpoint](endpoints/browse-endpoint/README.md) 12 | * [🔭 Browsing Categories](endpoints/browse-endpoint/browsing-categories.md) 13 | * [🌏 Browse Location IDs](endpoints/browse-endpoint/browse-location-ids.md) 14 | * [🔎 Filter Parameter](endpoints/browse-endpoint/filter-parameter.md) 15 | * [📃️ Describe Endpoint](endpoints/describe-endpoint/README.md) 16 | * [📃 Response Fields & Meaning](endpoints/describe-endpoint/response-fields-and-meaning.md) 17 | * [🔍 Search Endpoint](endpoints/search-endpoint/README.md) 18 | * [📂 Outline Attributes & Meaning](endpoints-and-streaming/endpoints/search-endpoint/outline-attributes-and-meaning.md) 19 | * [🆔 Genre IDs & Meaning](endpoints/search-endpoint/genre-ids-and-meaning.md) 20 | * [🎵 Tune Endpoint](endpoints/tune-endpoint/README.md) 21 | * [🌊 Intro to Streaming](intro-to-streaming/README.md) 22 | * [📃 The .M3U Extension](intro-to-streaming/the-.m3u-extension.md) 23 | * [❓ How to Stream](intro-to-streaming/how-to-stream.md) 24 | 25 | ## Credits, Basis & Helpful Resources 26 | 27 | * [⛑ Credits, Basis & Helpful Resources](credits-basis-and-helpful-resources/credits-basis-and-helpful-resources.md) 28 | -------------------------------------------------------------------------------- /api-basics/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Needed information on how to get started. 3 | --- 4 | 5 | # 🤔 Getting Started 6 | 7 | ## Making requests and the limitations of the API 8 | 9 | Sadly, TuneIn has a [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin\_policy), that forbids you to access the API via JavaScript.\ 10 | However, you are still able to make requests using [cURL](https://en.wikipedia.org/wiki/CURL), [Postman](https://www.postman.com/), or other such software. This means that you can use PHP and its command execution functions to have a fully web-based radio streaming experience (although server-sided) or a custom software client/app. 11 | 12 | All requests are made to the Base-URI defined in the [Introdcution](../) section, with the endpoints respective path appended and HTTP method specified before the path. 13 | 14 | ## Authentication & Security 15 | 16 | Although TuneIn implemented a same-origin policy, they did not implement any authentication which means you can get started right away. 17 | 18 | You need to specify the protocol that you want to use (HTTP/ HTTPS) since there is no automatic redirection to https even if you/the client can fully support an https connection. 19 | 20 | {% hint style="warning" %} 21 | Keep in mind that all URLs given as a response by the API will start with `http://` no matter which protocol you requested. So you will need to replace `http://` with `https://` on your end to use HTTPS. 22 | {% endhint %} 23 | 24 | ```batch 25 | http://opml.radiotime.com | not secure by default. 26 | https://opml.radiotime.com | secure and encrypted. 27 | ``` 28 | 29 | An example request using curl could look like the following: 30 | 31 | ```bash 32 | # Docs: GET /endpoint.ashx 33 | curl -s -X GET "https://opml.radiotime.com/endpoint.ashx" 34 | ``` 35 | 36 | ## API Responses 37 | 38 | The API always responds with an XML Document which usually looks something like this if you made a valid request. 39 | 40 | {% code title="Response (valid request)" %} 41 | ```xml 42 | 43 | 44 | Some Title 45 | 200 46 | 47 | 48 | 49 | 50 | 51 | ``` 52 | {% endcode %} 53 | 54 | {% code title="Response (invalid request)" %} 55 | ```xml 56 | 57 | 58 | Invalid method 59 | 404 60 | Invalid method 61 | api.methodNotFound 62 | 63 | 64 | 65 | ``` 66 | {% endcode %} 67 | 68 | ## Alternative responses 69 | 70 | Alternatively, you can add `&render=json` to the end of the request and render it in the json format. By default you will get an XML document. Other types of rendering have not yet been found. Feel free to add those into the documentation. 71 | 72 | ```bash 73 | # Docs: GET /endpoint.ashx | with &render=json added 74 | curl -s -X GET "https://opml.radiotime.com/endpoint.ashx&render=json" 75 | ``` 76 | 77 | {% code title="Response (valid request)" %} 78 | ```json 79 | { 80 | "head": { "title": "Some title", "status": "200" }, 81 | "body": [ 82 | { 83 | "element": "outline", 84 | "type": "audio", 85 | "text": "OctoStation", 86 | "URL": "http://opml.radiotime.com/Tune.ashx?id=a12345", 87 | "bitrate": "128", 88 | "reliability": "99", 89 | "guide_id": "a12345", 90 | "subtext": "OctoStation", 91 | "genre_id": "g61", 92 | "formats": "mp3", 93 | "item": "station", 94 | "image": "http://cdn-profiles.tunein.com/a12345/images/logoq.png", 95 | "now_playing_id": "a12345", 96 | "preset_id": "a12345" 97 | } 98 | ] 99 | } 100 | ``` 101 | {% endcode %} 102 | 103 | {% code title="Response (invalid request)" %} 104 | ```json 105 | { 106 | "head": { 107 | "title": "Invalid method", 108 | "status": "404", 109 | "fault": "Invalid method", 110 | "fault_code": "api.methodNotFound" 111 | }, 112 | "body": [] 113 | } 114 | ``` 115 | {% endcode %} 116 | -------------------------------------------------------------------------------- /credits-basis-and-helpful-resources/credits-basis-and-helpful-resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Helpful resources for the further research of the TuneIn API, including the 4 | basis for the API/Credits. 5 | --- 6 | 7 | # ⛑ Credits, Basis & Helpful Resources 8 | 9 | {% hint style="info" %} 10 | Yes, these are the only resources I could find that remotely correlate to the API or its functions. Most of the documentation comes from my own understanding. 11 | {% endhint %} 12 | 13 | ### [Analysis of TuneIn Radio Stations](http://www.surfingbits.com/blog/2011/analysis-of-tunein-radio-stations/) (Docs + Python) 14 | 15 | By Surfing Bits, the blog of Alex Dementsov. 16 | 17 | ### [Tunejack.sh](https://gist.github.com/xndc/c732204e274743204f1f) (Bash) 18 | 19 | A bash script by xndc to stream music from the API in Linux. 20 | 21 | ### [Playing a live TuneIn Radio URL iOS Swift](https://stackoverflow.com/questions/52754263/playing-a-live-tunein-radio-url-ios-swift) (Swift) 22 | 23 | Post on StackOverflow by Reimond Hill. 24 | 25 | ### [Curseradio](https://github.com/chronitis/curseradio) (Python) 26 | 27 | Command line radio player, repo by chronitis on GitHub, 28 | -------------------------------------------------------------------------------- /endpoints-and-streaming/endpoints/search-endpoint/outline-attributes-and-meaning.md: -------------------------------------------------------------------------------- 1 | # 📂 Outline Attributes & Meaning 2 | 3 | -------------------------------------------------------------------------------- /endpoints/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | Endpoint quick links and descriptions. 4 | --- 5 | 6 | # 🔗 Endpoints 7 | 8 | {% hint style="warning" %} 9 | Endpoint information may be incomplete. You can help by contributing to the project. 10 | {% endhint %} 11 | 12 | ## 🌐 Browse Endpoint 13 | 14 | This endpoint is used to browse through the TuneIn directory and browsing through categories. 15 | 16 | {% content-ref url="browse-endpoint/README.md" %} 17 | [browse-endpoint/README.md](browse-endpoint/README.md) 18 | {% endcontent-ref %} 19 | 20 | ## 📃️ Describe Endpoint 21 | 22 | This endpoint is used to get information about a specific station, show, topic, or podcast. 23 | 24 | {% content-ref url="describe-endpoint/README.md" %} 25 | [describe-endpoint/README.md](describe-endpoint/README.md) 26 | {% endcontent-ref %} 27 | 28 | ## 🔍 Search Endpoint 29 | 30 | This endpoint is used to search for stations, shows, topics, and podcasts. 31 | 32 | {% content-ref url="search-endpoint/README.md" %} 33 | [search-endpoint/README.md](search-endpoint/README.md) 34 | {% endcontent-ref %} 35 | 36 | ## 🎵 Tune Endpoint 37 | 38 | This endpoint is used to get the `.m3u` file needed for streaming. 39 | 40 | {% content-ref url="tune-endpoint/README.md" %} 41 | [tune-endpoint/README.md](tune-endpoint/README.md) 42 | {% endcontent-ref %} 43 | -------------------------------------------------------------------------------- /endpoints/browse-endpoint/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Further information about the browse endpoint. 3 | --- 4 | 5 | # 🌐 Browse Endpoint 6 | 7 | ## GET `/` 8 | 9 | If you request the base URI, you will receive a list of options you can pick from. (The browse categories) You can achieve the same result by requesting `/browse.ashx` without any GET parameters. 10 | 11 | You can select any of these categories to browse further, see [browsing categories](../endpoints/browse-endpoint/browsing-categories.md). 12 | 13 | ### Response 14 | 15 | 
<opml version="1">
16 |     <head>
17 |         <title>Browse</title>
18 |         <status>200</status>
19 |     </head>
20 |     <body>
21 |         <outline type="link" text="Local Radio" URL="http://opml.radiotime.com/Browse.ashx?c=local" key="local"/>
22 |         <outline type="link" text="Music" URL="http://opml.radiotime.com/Browse.ashx?c=music" key="music"/>
23 |         <outline type="link" text="Talk" URL="http://opml.radiotime.com/Browse.ashx?c=talk" key="talk"/>
24 |         <outline type="link" text="Sports" URL="http://opml.radiotime.com/Browse.ashx?c=sports" key="sports"/>
25 |         <outline type="link" text="By Location" URL="http://opml.radiotime.com/Browse.ashx?id=r0" key="location"/>
26 |         <outline type="link" text="By Language" URL="http://opml.radiotime.com/Browse.ashx?c=lang" key="language"/>
27 |         <outline type="link" text="Podcasts" URL="http://opml.radiotime.com/Browse.ashx?c=podcast" key="podcast"/>
28 |     </body>
29 | </opml>
30 | 31 | ## GET `/browse.ashx` 32 | 33 | Browse inside of a category. You can also view all categories by requesting the browse endpoint without any GET parameters. 34 | 35 | | Parameter | Example | Description | 36 | | --------- | ------- | ------------------------------------------------------------------------------------------------------- | 37 | | c | local | This is the browse category. | 38 | | id | r0 | This is the id of the country or continent. r0 corresponds to the continent selection. | 39 | | filter | l203 | Used by the language category to filter. (Meaning unknown as of now) | 40 | 41 | {% hint style="info" %} 42 | For all possible parameter values, see [Browsing Categories](../endpoints/browse-endpoint/browsing-categories.md), [Browse Location IDs](../endpoints/browse-endpoint/browse-location-ids.md), or [The Filter Parameter](../endpoints/browse-endpoint/filter-parameter.md). 43 | {% endhint %} 44 | 45 | ### Response 46 | 47 | {% code title="Category: local" %} 48 | 49 | ```xml 50 | 51 | 52 | Local Radio 53 | 200 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | ``` 62 | 63 | {% endcode %} 64 | 65 | ### Browsing Categories 66 | 67 | {% content-ref url="browsing-categories.md" %} 68 | [browsing-categories.md](browsing-categories.md) 69 | {% endcontent-ref %} 70 | 71 | ### Browse Location IDs 72 | 73 | {% content-ref url="browse-location-ids.md" %} 74 | [browse-location-ids.md](browse-location-ids.md) 75 | {% endcontent-ref %} 76 | 77 | ### Information about the `filter` parameter 78 | 79 | {% content-ref url="filter-parameter.md" %} 80 | [filter-parameter.md](filter-parameter.md) 81 | {% endcontent-ref %} 82 | -------------------------------------------------------------------------------- /endpoints/browse-endpoint/browse-location-ids.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Location IDs and the corresponding country/continent from the browse endpoint. 3 | --- 4 | 5 | # 🌏 Browse Location IDs 6 | 7 | {% hint style="warning" %} 8 | This will take some time to gather. If you feel like helping out, please [contribute](https://github.com/core-hacked/tunein-api/pulls). 9 | {% endhint %} 10 | 11 | ### ID's of Continents 12 | 13 | | Location ID | Corresponding Continent | 14 | | ----------- | ----------------------- | 15 | | r101215 | Africa | 16 | | r101216 | Asia | 17 | | r100297 | Australasia | 18 | | r101320 | Central America | 19 | | r101217 | Europe | 20 | | r101218 | North America | 21 | | r101219 | South America | 22 | 23 | ### ID's of Countries (Europe) 24 | 25 | | Location ID | Corresponding Country | 26 | | ----------- | ---------------------- | 27 | | r100288 | Albania | 28 | | r100290 | Andorra | 29 | | r100295 | Armenia | 30 | | r101221 | Austria | 31 | | r101222 | Azerbaijan | 32 | | r100303 | Belarus | 33 | | r100304 | Belgium | 34 | | r100309 | Bosnia and Herzegovina | 35 | | r101225 | Bulgaria | 36 | | r100331 | Croatia | 37 | | r101231 | Cyprus | 38 | | r101232 | Czech Republic | 39 | | r101233 | Denmark | 40 | | r101237 | Estonia | 41 | | r101239 | Finland | 42 | | r101240 | France | 43 | | r101435 | Georgia | 44 | | r100346 | Germany | 45 | | r101244 | Greece | 46 | | r101249 | Hungary | 47 | | r101250 | Iceland | 48 | | r101252 | Ireland | 49 | | r100359 | Italy | 50 | | r102406 | Kosovo | 51 | | r101259 | Latvia | 52 | | r100373 | Liechtenstein | 53 | | r100374 | Lithuania | 54 | | r101262 | Luxembourg | 55 | | r101263 | Macedonia | 56 | | r101268 | Malta | 57 | 58 | {% hint style="warning" %} 59 | Unfinished, for a list from the API, follow the `/browse.ashx?id=r0` endpoint. 60 | {% endhint %} 61 | -------------------------------------------------------------------------------- /endpoints/browse-endpoint/browsing-categories.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: This page documents all browsing categories found on the browse endpoint. 3 | --- 4 | 5 | # 🔭 Browsing Categories 6 | 7 | | Category | Return Type | Description | 8 | | -------- | ------------ | ---------------------------------------------------------------------------- | 9 | | local | streaming | Browse the local radio via Geo-Location. | 10 | | music | further menu | Browse music types/categories. | 11 | | talk | further menu | Returns links to further browsing categories. | 12 | | sports | further menu | Returns links to further browsing categories. | 13 | | lang | further menu | Returns links relating to language. | 14 | | podcast | split menu | Returns a split menu between Music, Talk, and Sports with categories inside. | 15 | -------------------------------------------------------------------------------- /endpoints/browse-endpoint/filter-parameter.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Information about the filter parameter. 3 | --- 4 | 5 | # 🔎 Filter Parameter 6 | 7 | {% hint style="warning" %} 8 | The filter parameter and its capabilities are currently not fully discovered some parts are hidden within the API but it will be guesswork to find all possible filters. 9 | 10 | If you happen to have information about the filters or have discovered a new one, please [kindly contribute](https://github.com/core-hacked/tunein-api/pulls) to the project's documentation. 11 | {% endhint %} 12 | 13 | This part of the documentation aims to find and document the various filter options of the API. 14 | 15 | > Most of the filter are weird but a pattern that is noticed between all of them is `letter:text` 16 | > 17 | > Two known examples of this are: `s:popular` and `p:show` 18 | 19 | {% hint style="info" %} 20 | These do not seem to work unless you search by an ID of something with a filter. Example: you filter by language and set the filter to be popular stations. 21 | {% endhint %} 22 | 23 | > The three main types for the `p:` filter are `show, station, topic.` 24 | > 25 | > These are the three return values found when looking at the `item` attribute of the outline elements within the response. 26 | 27 | ### Helpful resources and some basis for the documentation. 28 | 29 | {% content-ref url="../../../credits-basis-and-helpful-resources/credits-basis-and-helpful-resources.md" %} 30 | [credits-basis-and-helpful-resources.md](../../../credits-basis-and-helpful-resources/credits-basis-and-helpful-resources.md) 31 | {% endcontent-ref %} 32 | -------------------------------------------------------------------------------- /endpoints/describe-endpoint/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Further information about the describe endpoint. 3 | --- 4 | 5 | # 📃️ Describe Endpoint 6 | 7 | ## GET `/describe.ashx` 8 | 9 | This is the endpoint that allows you to look up station information. 10 | 11 | | Parameter | Example | Description | 12 | | --------- | ------- | ------------------------ | 13 | | id | s42069 | This is your station id. | 14 | 15 | ### Response 16 | 17 | ```xml 18 | 19 | 20 | 200 21 | 22 | 23 | 24 | 25 | 26 | s42069 27 | s42069 28 | OctoStation 29 | OctoStation 30 | 2 cool 4 a slogan! 31 | 96.2 32 | FM 33 | http://www.octostation.com/ 34 | http://tunein.com/contact/resolve/?stationId=42069 35 | http://tun.in/abcDef 36 | false 37 | true 38 | true 39 | false 40 | false 41 | false 42 | radioeksen 43 | https://cdn-profiles.tunein.com/s42069/images/logoq.jpg?t=636445279591030000 44 | Istanbul, Turkey 45 | Octo bass for your ears 46 | info@octostation.com 47 | (420) 690 00 00 48 | Someplace, TX, 53882 Texas Road 49 | English 50 | g115 51 | Alternative Rock 52 | r101125 53 | 420690 54 | GMT - 6 (Austin, Texas) 55 | 180 56 | true 57 | true 58 | false 59 | false 60 | true 61 | true 62 | true 63 | http://tunein.com/station/?stationId=42069 64 | false 65 | false 66 | false 67 | music 68 | true 69 | true 70 | false 71 | false 72 | false 73 | false 74 | 75 | 76 | 77 | 78 | ``` 79 | 80 | ### Get station information 81 | 82 | {% content-ref url="response-fields-and-meaning.md" %} 83 | [response-fields-and-meaning.md](response-fields-and-meaning.md) 84 | {% endcontent-ref %} 85 | -------------------------------------------------------------------------------- /endpoints/describe-endpoint/response-fields-and-meaning.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Response fields and their meaning for the describe endpoint. 3 | --- 4 | 5 | # 📃 Response Fields & Meaning 6 | 7 | | Field Name | Description | 8 | | -------------------------------- | --------------------------------------------------------------------------------------------- | 9 | | element | Indicates that the object represents a station. | 10 | | guide\_id | The unique ID of the station used by Radiotime. | 11 | | preset\_id | The unique ID of the station used by TuneIn. | 12 | | name | The name of the station. | 13 | | call\_sign | The call sign of the station. | 14 | | slogan | The slogan or tagline of the station. | 15 | | frequency | The frequency of the station's broadcast. | 16 | | band | The band (e.g. FM, AM) on which the station broadcasts. | 17 | | url | The website URL of the station. | 18 | | report\_url | The URL of the TuneIn contact form for reporting issues with the station. | 19 | | detail\_url | The URL of the TuneIn station detail page. | 20 | | is\_preset | Indicates whether the station is a TuneIn preset station. | 21 | | is\_available | Indicates whether the station is currently available. | 22 | | is\_music | Indicates whether the station plays music. | 23 | | has\_song | Indicates whether the station is currently playing a song. | 24 | | has\_schedule | Indicates whether the station has a schedule of programming. | 25 | | has\_topics | Indicates whether the station has topic-based programming. | 26 | | twitter\_id | The Twitter handle of the station. | 27 | | logo | The URL of the station's logo. | 28 | | location | The location of the station. | 29 | | current\_song | The currently playing song on the station, if available. | 30 | | current\_artist | The artist of the currently playing song on the station, if available. | 31 | | current\_artist\_id | The unique ID of the artist of the currently playing song on the station, if available. | 32 | | current\_album | The album of the currently playing song on the station, if available. | 33 | | current\_artist\_art | The URL of the artist image for the currently playing song on the station, if available. | 34 | | current\_album\_art | The URL of the album cover image for the currently playing song on the station, if available. | 35 | | description | A description of the station. | 36 | | email | The email address of the station. | 37 | | phone | The phone number of the station. | 38 | | mailing\_address | The mailing address of the station. | 39 | | language | The language(s) spoken on the station. | 40 | | genre\_id | The unique ID of the station's genre. | 41 | | genre\_name | The name of the station's genre. | 42 | | region\_id | The unique ID of the station's region. | 43 | | country\_region\_id | The unique ID of the station's country region. | 44 | | latlon | The latitude and longitude of the station | 45 | | region\_id | The unique ID of the region. | 46 | | country\_region\_id | The ID of the country/region. | 47 | | latlon | The latitude and longitude of the station. | 48 | | tz | The time zone of the station. | 49 | | tz\_offset | The time zone offset in minutes. | 50 | | publish\_song | Whether the station is currently publishing a song. | 51 | | publish\_song\_url | The URL of the currently published song. | 52 | | publish\_song\_rejection\_reason | The reason why the song publishing was rejected. | 53 | | now\_playing\_url | The URL of the now playing data. | 54 | | external\_key | The external key of the station. | 55 | | ad\_eligible | Whether the station is eligible for ads. | 56 | | preroll\_ad\_eligible | Whether the station is eligible for preroll ads. | 57 | | companion\_ad\_eligible | Whether the station is eligible for companion ads. | 58 | | video\_preroll\_ad\_eligible | Whether the station is eligible for video preroll ads. | 59 | | fb\_share | Whether the station can be shared on Facebook. | 60 | | twitter\_share | Whether the station can be shared on Twitter. | 61 | | song\_share | Whether the currently playing song can be shared. | 62 | | donation\_eligible | Whether the station is eligible for donations. | 63 | | donation\_url | The URL to donate to the station. | 64 | | donation\_text | The text displayed to ask for donations. | 65 | | donation\_icon | The URL of the donation icon. | 66 | | song\_buy\_eligible | Whether the currently playing song is eligible for purchase. | 67 | | tunein\_url | The URL of the station on TuneIn. | 68 | | is\_family\_content | Whether the station's content is family-friendly. | 69 | | is\_mature\_content | Whether the station's content is mature. | 70 | | is\_event | Whether the station is an event. | 71 | | content\_classification | The classification of the station's content. | 72 | | echoed\_count | The number of echoes the station has received. | 73 | | favorited\_count | The number of times the station has been favorited. | 74 | | is\_favorited | Whether the station is favorited. | 75 | | is\_favoritable | Whether the station is favoritable. | 76 | | has\_profile | Whether the station has a profile. | 77 | | can\_cast | Whether the station can be casted. | 78 | | nielsen\_eligible | Whether the station is eligible for Nielsen ratings. | 79 | | nielsen\_provider | The provider of Nielsen ratings for the station. | 80 | | nielsen\_asset\_id | The ID of the Nielsen asset for the station. | 81 | | nowplaying\_channel | The channel of the now playing data. | 82 | | why\_ads\_text | The text explaining why ads are played on the station. | 83 | | use\_native\_player | Whether the station uses a native player. | 84 | | live\_seek\_stream | Whether the station supports live seeking. | 85 | | seek\_disabled | Whether seeking is disabled for the station. | 86 | -------------------------------------------------------------------------------- /endpoints/search-endpoint/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Further information about the search endpoint. 3 | --- 4 | 5 | # 🔍 Search Endpoint 6 | 7 | ## GET `/search.ashx` 8 | 9 | This is the endpoint that allows you to search on TuneIn. 10 | 11 | | Parameter | Example | Description | 12 | | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | 13 | | query | GitFM | This is your search query. It needs to be properly [URL escaped/encoded](https://www.w3schools.com/tags/ref_urlencode.ASP). | 14 | 15 | ### Response 16 | 17 | 
<opml version="1">
18 |     <head>
19 |         <title>Search Results: GitFM</title>
20 |         <status>200</status>
21 |     </head>
22 |     <body>
23 |         <outline type="link" text="Artist: GitFM" URL="http://opml.radiotime.com/Browse.ashx?id=a123456" guide_id="a123456" image="http://cdn-albums.tunein.com/gn/example.jpg" has_profile="false"/>
24 |         <outline type="audio" text="GitFM" URL="http://opml.radiotime.com/Tune.ashx?id=a12345" bitrate="128" reliability="99" guide_id="a12345" subtext="Octo - Git gud" genre_id="g61" formats="mp3" playing="Octo - Git gud" show_id="p1234567" item="station" image="http://cdn-profiles.tunein.com/a12345/images/logoq.jpg?t=123456" current_track="C-Section" now_playing_id="a12345" preset_id="a12345"/>
25 |     </body>
26 | </opml>
27 | 28 | {% code title="Results not found." overflow="wrap" %} 29 | 30 | ```xml 31 | 32 | 33 | Search Results: GitFM 34 | 200 35 | 36 | 37 | 38 | 39 | 40 | ``` 41 | 42 | {% endcode %} 43 | 44 | ### Genre IDs and their meanings. 45 | 46 | {% content-ref url="genre-ids-and-meaning.md" %} 47 | [genre-ids-and-meaning.md](genre-ids-and-meaning.md) 48 | {% endcontent-ref %} 49 | 50 | ### Outline attributes and their meanings. 51 | 52 | {% content-ref url="outline-attributes-and-meaning.md" %} 53 | [genre-ids-and-meaning.md](outline-attributes-and-meaning.md) 54 | {% endcontent-ref %} 55 | -------------------------------------------------------------------------------- /endpoints/search-endpoint/genre-ids-and-meaning.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: All genre IDs and their explained meaning. 3 | --- 4 | 5 | # 🆔 Genre IDs & Meaning 6 | 7 | {% hint style="warning" %} 8 | This will take some time to gather, as well as, to explain/get information about what the genre ID actually means/what the corresponding genre is. [If you know anything, please contribute to the project.](https://github.com/core-hacked/tunein-api/pulls) 9 | {% endhint %} 10 | -------------------------------------------------------------------------------- /endpoints/search-endpoint/outline-attributes-and-meaning.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: >- 3 | The attributes returned within the XML response inside of the 'outline' 4 | elements. 5 | --- 6 | 7 | # 📂 Outline Attributes & Meaning 8 | 9 | | Attribute | Description | 10 | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | 11 | | type | This is the type of the displayed element. | 12 | | text | This is the "text" or title of the element. It is usually the name of the station. | 13 | | URL | This is the tune/streaming URL or a link to the corresponding page, depending on the type. | 14 | | bitrate | This is the bitrate of the station/stream. It's present if the element corresponds to a direct streaming URL. | 15 | | reliability | This is the reliability score of the station/stream. The higher the better. It is a scale going from 0 to 100. | 16 | | guide\_id | This seems to be the identifier for the stream and-/or current track/station. | 17 | | subtext | This is the "subtext" or description of the station. Some stations use this as a way of displaying the currently playing song. | 18 | | genre\_id | This is the ID of the genre. [View a list of genre IDs and their genre.](search-endpoint/) | 19 | | formats | This is the format of the 'outline' element, usually mp3. | 20 | | show\_id | This is the show/station id. | 21 | | item | Although the name, it also defines the type of the 'outline' element. See below for more information. | 22 | | image | The image of the radio station or podcast/show. | 23 | | current\_track | The currently playing track, usually the same as the subtext. | 24 | | now\_playing\_id | Probably the id of the currently playing track or the station. | 25 | | preset\_id | Usually the same as the now playing ID or Tune ID. | 26 | | playing\_image | Some stations also stream the image of the currently playing song but it won't always be present. | 27 | | has\_profile | If the outline element in the search is an artist, this tells you if they have a profile on TuneIn you can visit. | 28 | | stream\_type | If present it's usually `download`. It also usually means that the current element represents a topic and is a fixed audio file instead of a live stream. | 29 | | topic\_duration | This is the duration of the topic. | 30 | 31 | ### The `type` attribute and its possible values. 32 | 33 | The `type` attribute defines the current outline element's type.\ 34 | Currently, it has three known values. 35 | 36 | | Value | Description | 37 | | ----- | ----------------------------------------------------------------------------------------------------------------------------------- | 38 | | audio | This means that the outline element represents a station or show with a valid m3u file or in the case of a topic, valid m3u files. | 39 | | link | This represents a link to another page, an artist's or station's profile, etc. | 40 | | text | This means that the element contains only text and usually does not have a URL corresponding to something. | 41 | 42 | ### The `item` attribute and its possible values. 43 | 44 | The `item` attribute defines the current outline element's type.\ 45 | Currently, it has three known values. 46 | 47 | | Value | Description | 48 | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 49 | | station | This means that the outline element represents a currently ongoing live stream. (live audio) | 50 | | topic | This means that the outline element represents an already passed live stream, that has been recorded or a part of an existing podcast. (non-live audio) | 51 | | show | This represents a collection of topics/a further link to audio elements of, ex. a podcast. (collection of non-live audios) | 52 | -------------------------------------------------------------------------------- /endpoints/tune-endpoint/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Further information about the tune endpoint. 3 | --- 4 | 5 | # 🎵 Tune Endpoint 6 | 7 | ## GET /`tune.ashx` 8 | 9 | Get the `.m3u` file needed for streaming. 10 | 11 | | Parameter | Example | Description | 12 | | --------- | -------- | ------------------------------------------------------------------------------------------ | 13 | | id | s12345 | This is the ID of the tune. You will get these from an outline objects attributes. | 14 | | sid | p1234567 | Purpose unknown, used in combination with topics/shows. | 15 | 16 | ### Response 17 | 18 | This endpoint is a direct download for the tune file with the .m3u extension. \ 19 | Learn more about the extension and how to use it/play music from it. 20 | 21 | {% content-ref url="../intro-to-streaming/the-.m3u-extension.md" %} 22 | [the-.m3u-extension.md](../intro-to-streaming/the-.m3u-extension.md) 23 | {% endcontent-ref %} 24 | -------------------------------------------------------------------------------- /intro-to-streaming/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn how to stream/get a stream URL from the Tune API. 3 | --- 4 | 5 | # 🌊 Intro to Streaming 6 | 7 | ### Understanding `.m3u` files 8 | 9 | {% content-ref url="the-.m3u-extension.md" %} 10 | [the-.m3u-extension.md](the-.m3u-extension.md) 11 | {% endcontent-ref %} 12 | 13 | ### How to Stream a Song 14 | 15 | {% content-ref url="how-to-stream.md" %} 16 | [how-to-stream.md](how-to-stream.md) 17 | {% endcontent-ref %} 18 | -------------------------------------------------------------------------------- /intro-to-streaming/how-to-stream.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn how to extract a streaming url from an M3U File and play music from it. 3 | --- 4 | 5 | # ❓ How to Stream 6 | 7 | ## Streaming in Linux. 8 | 9 | Streaming inside of Linux is very simple, you can use `xdg-open` to find an app that supports this format by giving it the `Tune.m3u` file directly. You can view an implemented search and player made in bash on GitHub. 10 | 11 | ### [Tunejack.sh](https://gist.github.com/xndc/c732204e274743204f1f) 12 | 13 | Instant radio streaming script using the TuneIn API by xndc. 14 | 15 | ## Streaming on non-Linux devices or the web. 16 | 17 | To start off here, although some players support the M3U format, there is a simple way to do it on all platforms. 18 | 19 | ### URL Extraction and Usage. 20 | 21 | If your player does not support M3U or you don't want to install additional software, you can extract the URL from the m3u file by simply viewing it inside of a text editor. 22 | 23 | It should give you a URL or multiple (some stations/streams have varying qualities) that you can open inside of your web browser to give you an mp3 audio control. 24 | 25 | You can also use this inside of an HTML ` tag, to play music on your own website. 26 | 27 | ```html 28 | 31 | ``` 32 | 33 | {% hint style="info" %} 34 | This is pretty much the basis for streaming, if you need the "rich" streaming experience, you will need to create a parser that can display this either in HTML or some other language you want. 35 | {% endhint %} 36 | -------------------------------------------------------------------------------- /intro-to-streaming/the-.m3u-extension.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Learn about and understand the .M3U extension. 3 | --- 4 | 5 | # 📃 The .M3U Extension 6 | 7 | ### Understand what the `.M3U` extension is. 8 | 9 | {% hint style="info" %} 10 | **M3U** (_MP3 URL_[\[1\]](https://en.wikipedia.org/wiki/M3U#cite\_note-WinPlay3v20-1)[\[2\]](https://en.wikipedia.org/wiki/M3U#cite\_note-Gnomie-2) or [Moving Picture Experts Group Audio Layer 3](https://en.wikipedia.org/wiki/MPEG\_Audio\_Layer\_3) [Uniform Resource Locator](https://en.wikipedia.org/wiki/Uniform\_Resource\_Locator)[\[3\]](https://en.wikipedia.org/wiki/M3U#cite\_note-3) in full) is a computer file format for a multimedia [playlist](https://en.wikipedia.org/wiki/Playlist). One common use of the M3U file format is creating a single-entry playlist file pointing to a [stream](https://en.wikipedia.org/wiki/Streaming\_media) on the Internet. The created file provides easy access to that stream and is often used in downloads from a website, for emailing, and for listening to [Internet radio](https://en.wikipedia.org/wiki/Internet\_radio). 11 | 12 | Although originally designed for audio files, such as [MP3](https://en.wikipedia.org/wiki/MP3), it is commonly used to point media players to audio and video sources, including online sources. M3U was originally developed by [Fraunhofer](https://en.wikipedia.org/wiki/Fraunhofer\_Society) for use with their [Winplay3](https://en.wikipedia.org/wiki/Winplay3) software,[\[4\]](https://en.wikipedia.org/wiki/M3U#cite\_note-4) but numerous media players and software applications now support the format. 13 | {% endhint %} 14 | 15 | > _Sourc_e: [_Wikipedia - M3U_](https://en.wikipedia.org/wiki/M3U) 16 | 17 | ### Simple explanation. (Self-written) 18 | 19 | So, the `.M3U` format basically hosts a URL or multiple URLs of an audio stream or of mp3 files. \ 20 | You can extract this URL to play/stream the audio in MP3 format. It is as per Wikipedia, only a [de-facto](https://en.wikipedia.org/wiki/De\_facto) standard and does not have any formal specification. 21 | 22 | #### Learn how to stream audio from `.M3U` files. 23 | 24 | {% content-ref url="how-to-stream.md" %} 25 | [how-to-stream.md](how-to-stream.md) 26 | {% endcontent-ref %} 27 | --------------------------------------------------------------------------------