STREAMFINDER.COM API DOCUMENTATION

October, 10th 2013

This API is designed to give licensed 3rd parties access to the radio station data gathered by StreamFinder.com

We add hundreds of stations every week to our directory and we also eliminate dozens of stations every week.

To access either our DEV API or LIVE API you will need a codekey.

To test our our API we have a FREE development API license you can apply for here:

http://streamfinder.com/internet-radio-api/

- limited to a small number of genres

- only returns up to 10 listings in each genre

- limited to only genre_search method for searching

- limit of 1,000 API calls

Our regular full access API requires an API licensing contract in place.

API Access URL

http://streamfinder.com/api/

Authentication

All API calls must be authenticated with an API codekey.

Simply specify api_codekey=abc123[your codekey here] in your query to authenticate and log your usage.

Return Data Format

Our API is written to return either XML or JSON data formats.

Simply specify return_data_format=json or return_data_format=xml in your query to specify what you would like returned to your application.

API Methods

The API opens a variety of methods to programmers

Either will accept a POST or GET of the following variables:

do (this is our main action switch) - it accepts the following values

Meta information

- get_country_list - will return a list of all countries with their id variables

- get_genre_list - will return a list of all station genres available for searching with their id and names

- get_top_genres - will return a list of all master genres minus child genres and geographic genres (commercial only)

- get_api_usage - will return a message with details about your api account and usage

Search types

- genre_search > will return station listings based on the stated genre of the radio station

    - gid=x ( required with genre_search - genre id from 'get_genre_list' above)

Search types available with Commercial License

- keyword_search > will return listings based on a keyword search of station title and description

    - kw=string+to+find( required when searching action is 'do=keyword_search' )

- tag_search > will return station listings based on broadcaster provided tags

    - tag=tag+to+find

- country_search > will return station listings originating from a particular country

    - country=US (required with country_search 2 digit ISO code from 'get_country_list' above)

- city_search > returns station listings from particular cities

    - city=Chicago (city required with city_search )

- artist_search > returns station listings that have played requested artist in the last 30 days - data only available for ShoutCast servers at this time

    - artist=Michael+Jackson (artist required with artist_search )

Search action modifiers

- num > number of results to return ( default is '10' ) *REQUIRED*

- start > where in the result set returned to start returning listings ( default is '1' )

- format > stream format to return ( many stations have multiple streams for different platforms )

            - format=sc (returns only shoutcast streams)

            - format=sc_compat (returns shoutcast, icecast, steamcast and other icy based streams)

            - format=aac (returns mp3 aac streams from shoutcast and icecast servers)

            - format=wm (returns all windows media streams)

            - format=wm_compat (returns all windows media streams and misc mp3 streams returned by 'mp3' value below)

            - format=ogg (returns ogg/vorbis streams)

            - format=mp3 (returns misc mp3 streams)

            - format=all (returns all stream formats)

- now > if possible return 'now playing' data for this station ( optional, set 'now=1' to toggle )

    - takes extra time to ping streaming servers

    - only works on 'format=sc' and 'format=sc_compat' type servers at this time

    - do not turn on if not using those formats

- recent > if possible return an array of recently played songs for this station

    - takes extra time to ping streaming servers

    - only works on 'format=sc' and 'format=sc_compat' type servers at this time

    - do not turn on if not using those formats

- refresh_recent >

- refresh_all >

All Search Actions return the following values:

- total_results         = number of radio station listings that match your request

- result_start          = starting point of result set where station_list begins

- result_end            = ending point in station_list

- gid                                  = set if genre_search is used

- genre_name          = set if genre_search is used

- kw                                  = set if keyword_search is used

- tag                                 = set if tag_search is used

- country                   = set if country_search is used

- city                                = set if city_search is used

- station_list           = (array of station data)

Artist Search Action also returns 'song' with the title of the recently played song

example single station listing contained within station_list object:

[number] => 6 (result set station number - this is number 6 in the queried result set)

[sid] => 16267 (streamfinder station id - can be used in a station specific query below)

[name] => Pro FM Dance Radio 24/7 80's - 90' s Danceclassics and Todays Dancehits (station name)

[www] => http://profm.com  (station website)

[streams] => stdClass Object

(

[stream_url] => http://stream.pro-fm.net:8200/listen.pls (stream url)

[stream_format] => 1 (station format id code)

[stream_format_string] => Shoutcast (station format name)

[stream_bitrate] => 2 (station stream bitrate id code)

[stream_bitrate_string] => 32 kbps (station stream bitrate name)

[now_playing] => Lady GaGa - Fernando (supplied if query specifies now=1 )

[test_up] => 1 ( indicates stream_url above is UP. supplied if query specifies test_up=1 )

)

Station specific actions

- station_detail > returns all information about a station - all meta data, all genre ids, all streaming links and tags. Must identify station using station id (sid) in the query string.

do=station_detail&sid=1234

Returns This:

stdClass Object

(

[station_meta] => stdClass Object

(

[0] => 20690

[id] => 20690

[1] => 3510

[userid] => 3510

[2] => Radio NOVA Chicago

[name_show] => Radio NOVA Chicago

[3] =>

[station_admin_name] =>

[4] =>

[station_phone_number] =>

[5] => info@radionova.tv

[station_admin_email] => info@radionova.tv

[6] => 0

[station_im_account_type] => 0

[7] =>

[station_im_handle] =>

[8] => http://www.facebook.com/pages/Radio-Nova-Chicago/161970453813885

[station_facebook_url] => http://www.facebook.com/pages/Radio-Nova-Chicago/161970453813885

[9] =>

[station_myspace_url] =>

[10] => novachicago

[station_twitter_id] => novachicago

[11] =>

[station_logo] =>

[12] =>

[date_show] =>

[13] => Radio Nova Chicago is a internet radio station specializing in euro dance music genres such as eurodance, italodance, dj mixes and classic euro streaming live high fidelity AAC aacPlus format.

[show_desc] => Radio Nova Chicago is a internet radio station specializing in euro dance music genres such as eurodance, italodance, dj mixes and classic euro streaming live high fidelity AAC aacPlus format.

[14] => listings_stream_links

[show_url] => listings_stream_links

[15] => http://radionova.tv

[show_website] => http://radionova.tv

[16] => 9999999999

[genre] => 9999999999

[17] => 99

[format] => 99

[18] => 0

[recurring] => 0

[19] => 2008-05-12

[date_listed] => 2008-05-12

[20] => 2011-01-28 00:08:40

[date_updated] => 2011-01-28 00:08:40

[21] => 1

[status] => 1

[22] =>

[geo_id] =>

[23] => US

[country_id] => US

[24] => Chicago

[city] => Chicago

[25] => 60076

[postal_code] => 60076

[26] => 0

[is_terrestrial] => 0

[27] => 0

[call_letters] => 0

[28] => 0

[frequency] => 0

[29] =>

[widget_code] =>

)

[streaming_links] => Array

(

[0] => stdClass Object

(

[id] => 32855

[listing_id] => 20690

[format] => 1

[url] => http://radionova.tv:8000/listen.pls

[bitrate] => 5

[date_added] => 2011-01-28

[date_checked] => 2011-04-27

[status] => 1

[strikes] => 0

)

[1] => stdClass Object

(

[id] => 32854

[listing_id] => 20690

[format] => 1

[url] => http://radionova.tv:8006/listen.pls

[bitrate] => 3

[date_added] => 2011-01-28

[date_checked] => 2011-04-27

[status] => 1

[strikes] => 0

)

[2] => stdClass Object

(

[id] => 32853

[listing_id] => 20690

[format] => 20

[url] => http://radionova.tv:8008/listen.pls

[bitrate] => 1

[date_added] => 2011-01-28

[date_checked] => 2011-04-27

[status] => 1

[strikes] => 0

)

)

[genres] => Array

(

[0] => 27

[1] => 54

[2] => 56

[3] => 5

)

[tags] => Array

(

[0] => romanian

[1] => dance

[2] => eurodance

[3] => italodance

[4] => dj mixes

[5] => classic euro

)

)

Sample Queries

Retrieve a list of genre id’s - do this so that you can browse a list of stations matching that genre.

http://streamfinder.com/api/index.php?api_codekey={yourcodekey}

&return_data_format=json

&do=get_genre_list

Returns this:

{"genres":[{"gid":80,"genre_name":"Rock and Roll"},{"gid":10,"genre_name":"Jazz"},{"gid":5,"genre_name":"Electronic Dance Music"},{"gid":42,"genre_name":"Alternative Rock"}]}

Browse radio stations by genre id returned above - browse for “Alternative Rock” radio stations streaming in mp3 format and return 10 results

http://streamfinder.com/api/index.php?api_codekey={yourcodekey}

&return_data_format=json

&do=genre_search

&gid=42

&format=mp3

&num=10