Radio Directory API Documentation version 1.7

Welcome developers to our api, this api get new updates all the time so to be up to date, check this documentation time by time.

Creative Commons License
Create or check your api-keys

The base URL to the API

To use the API you just call using this base url and then add the function calls to it like a normal URL.

http://api.dirble.com/v1/

Get All Categories:

URL: categories/apikey/api-key

See the example of what the json will look like below:

[{"id":7,"name":"Alternative rock","description":"alternative rock"},{"id":11,"name":"Classical","description":"Classical music such as Mozart and Beethoven but also Greig and others."},{"id":3,"name":"Dance","description":"dance music, the new from 80s and 90s, like bubblegum and more."}]

Get Primary Categories:

URL: primaryCategories/apikey/api-key

This will only get the main, head categories.

See the example of what the json will look like below:

[{"id":7,"name":"Alternative rock","description":"alternative rock"},{"id":11,"name":"Classical","description":"Classical music such as Mozart and Beethoven but also Greig and others."},{"id":3,"name":"Dance","description":"dance music, the new from 80s and 90s, like bubblegum and more."}]

Get Child Categories:

URL: childCategories/apikey/api-key/primaryid/primary-category id

This will only get child categories of a primary/head/main category.

amount show how many stations it exist in each childcateogry

See the example of what the json will look like below:

[{"id":31,"name":"Conspiracy","description":"","amount":1},{"id":21,"name":"News","description":"","amount":45},{"id":30,"name":"Politic","description":"","amount":0}]

Get Stations in a Category

URL: stations/apikey/api-key/id/category id

status is the status about the stream is up or not, 1 means up, 0 means down. Warning The status can not be 100% sure yet. Its mainly just working for shoutcast and some Icecast

Heads-up To get stations for primaryCategory, use this call and the specific primarycategory's id.

See the example of what the json will look like below:

[{"id":7,"name":"PowerFM.se","streamurl":"http:\/\/powerfm.se\/64k.pls","country":"SE","bitrate":"64 kbps","status":1},{"id":9,"name":"Radioseven","streamurl":"http:\/\/178.32.238.139:8500","country":"SE","bitrate":"128 kbps","status":1},{"id":6,"name":"Digitally imported Psy- & goa-trance","streamurl":"http:\/\/listen.di.fm\/public3\/goapsy.pls","country":"GB","bitrate":"96 kbps","status":1}]

When no station found in a category, the api will return a empty string with 404 HTTP status header.



Get stations for Continent

URL: continent/apikey/api-key/continent/continent urlid

get stations in a specified continent, continent urlid is the name but in small letters with - instead of space. see the url for a continent in the county page.

status is the status about the stream is up or not, 1 means up, 0 means down. Warning The status can not be 100% sure yet. Its mainly just working for shoutcast and some Icecast

See the example of what the json will look like below:

[{"id":7,"name":"PowerFM.se","streamurl":"http:\/\/powerfm.se\/64k.pls","country":"SE","bitrate":"64 kbps","status":1},{"id":9,"name":"Radioseven","streamurl":"http:\/\/178.32.238.139:8500","country":"SE","bitrate":"128 kbps","status":1},{"id":6,"name":"Digitally imported Psy- & goa-trance","streamurl":"http:\/\/listen.di.fm\/public3\/goapsy.pls","country":"GB","bitrate":"96 kbps","status":1}]

Get stations for Country

URL: country/apikey/api-key/country/country code

get stations in a specified country, check in the bottom of this page for info about the country code.

status is the status about the stream is up or not, 1 means up, 0 means down. Warning The status can not be 100% sure yet. Its mainly just working for shoutcast and some Icecast

See the example of what the json will look like below:

[{"id":7,"name":"PowerFM.se","streamurl":"http:\/\/powerfm.se\/64k.pls","country":"SE","bitrate":"64 kbps","status":1},{"id":9,"name":"Radioseven","streamurl":"http:\/\/178.32.238.139:8500","country":"SE","bitrate":"128 kbps","status":1},{"id":6,"name":"Digitally imported Psy- & goa-trance","streamurl":"http:\/\/listen.di.fm\/public3\/goapsy.pls","country":"GB","bitrate":"96 kbps","status":1}]

Get Station

URL: station/apikey/api-key/id/station-id

Get information on a station by id-number.
You will get normal information such as streamurl, website url and description but also which directories/categories the stations is added to and a songhistory if the station support it.

See the example of what the response json will look like below:

{"id":"6281","name":"Christmas Station UK","streamurl":"http:\/\/s19.myradiostream.com:9218","bitrate":"128 kbps","description":"","country":"GB","added":"2013-12-08 03:01:01","urlid":"christmas-station-uk","website":"http:\/\/myradiostream.com\/christmasstation","status":"2","songhistory":[{"name":"Frank Kelly","title":"Christmas Countdown","time":"2013-12-08 13:31:18"},{"name":"Jona Lewie","title":"Stop The Cavalry","time":"2013-12-08 13:29:18"},{"name":"Mr. Scruff","title":"Kalimba","time":"2013-12-08 13:23:17"},{"name":"Spice Girls","title":"Sleigh Ride","time":"2013-12-08 13:21:17"},{"name":"Richard Stoltzman\/Slovak Radio Symphony Orchestra","title":"Maid with the Flaxen Hair","time":"2013-12-08 13:17:17"},{"name":"Leslie Bricusse","title":"Overture","time":"2013-12-08 13:13:17"},{"name":"Bob Acri","title":"Sleep Away","time":"2013-12-08 13:11:17"},{"name":"The Beach Boys","title":"Little St. Nick","time":"2013-12-08 13:09:16"},{"name":"Various Artists","title":"Ding! Dong! Merrily on High","time":"2013-12-08 13:07:16"},{"name":"Lynn Ahrens","title":"Nothing to Do With Me","time":"2013-12-08 13:03:16"}],"directory":[{"id":"45","name":"Variety","urlid":"variety"}]}

Add Station

URL (POST): station/apikey/api-key/

add a station with specified information to the queue list.
Name, website and Directory is Required.

This data can be inserted:

  • name
  • streamurl
  • website
  • country
  • directory

You will send a json object in the body in the request, example how the json could look like:

{"name":"nisse","website":"http:\/\/", "streamurl":"http:\/\/","country":"se","directory":"Rock, "}

directory is the name of the directories, separated with comma.

See the example of what the response json will look like below:

{"name":"nisse","streamurl":"","website":"http:\/\/","urlid":"nisse","country":"se","status":1}

OBS! Observe the status, the status will be 0 if error. 1 if success, or a normal errormsg.
if you get status 0, then you probably just sent empty name, website or directory.
It could also be wrong directories, you should only let the users to add categories that already exist, you can get all categories with a call: Get Categories


Get Amount of station (for check of updates)

URL: amountStation/apikey/api-key

Get amount of station, perfect to check if any new station has been added, like when you cache the data.

See the example of the response:

{"status":"ok","amount":175}

Handle Errors

When no stations is found in a directory, it will return a empty array with 404 HTTP Status header.

When getting a errormsg when problems with the apikey, you will get a error like below:

			[{"errormsg":"The Apikey is wrong or deactivated."}]			

The apikey-error will also get a 401 HTTP status header.

Formats

We can respond with JSON, XML and HTML as formats

default is json

just add format/format in the end of url.

This formats can you use

format url path
json /format/json
xml /format/xml
html /format/html

how to read it

how to read the urls.

api-key - is there the api-key should be.

* id - is the id for stations, categories etc.

Other good stuff to know

Our country codes follows the ISO 3166-1 alpha 2 standard.