StreamFinder.com Radio Station Ingestion API Documentation

March 25, 2013

This documentation describes the usage of our API and its methods of ingestion of radio station data into the StreamFinder.com database. This API is designed for streaming ISP’s, stream hosts, radio station networks with more than 10 stations and other radio station networks that regularly want to add their stations to our database.

Request Access

The first step to ingestion is to apply for an Ingestion API Key

http://streamfinder.com/station-data-ingestion-api/

Approval for requests takes anywhere from 10 minutes to 24 hours depending on how busy we are. Typical response time is within the hour. Once you have a codekey you can start to access our ingestion API.

API Access URL

We accept GET or POST requests.

http://streamfinder.com/api/ingest/

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.

Data Format

All data passed into the API and out of the API will be in json format.

Methods

There are three meta methods and two main methods for this API - all are attached to the variable ‘do’, ex: do=get_api_usage

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 with their id and names

get_api_usage - will return a message with details about past ingestion events using the API format is date => number of stations submitted

Main actions

add

ex: do=add

This method expects a json array of radio station data in the following format.

radio station listing format

There are 4 main areas of station data that we need to collect to create an effective listing on StreamFinder.com that will work to attract new listeners and provide value to you and your client stations:

- Station Owner Data & Social Media Info

- Station Name, Desc. & URL

- Station Stream Links

- Station Genres, categories, tags

The following variables can be used in your station listings. Bold items are required and italic items are optional. Stations submitted without bold items will be rejected automatically. We require the station admin email in our listings so that they can be notified of various actions that occur.

contact_name

contact_email*

station_your_id

station_name

station_desc

station_url

station_country

station_city

station_zip

station_facebook

station_twitter

station_myspace

widget_code

genre1

genre2

genre3

genre4

tag1

tag2

tag3

tag4

stream_url1

stream_url1_format

stream_url1_bitrate

stream_url2

stream_url2_format

stream_url2_bitrate

stream_url3

stream_url3_format

stream_url3_bitrate

stream_url4

stream_url4_format

stream_url4_bitrate

Details of each field

contact_name

(optional) The name of a station administrator who is responsible for broadcasting. Used to personalize emails that come from our service when sent to station.

contact_email

(required) We notify a station admin when someone saves their station as a favorite, when their station is chosen as a featured station, when their monthly log report is ready or when their streaming links are no longer valid. These are key to the relationship we have with the stations we list on our site. We do not sell, give-away or spam these contacts.

station_your_id

(required)  This represents the unique id of this station in your tracking system or database. Used by our system to notify you about a specific station.

station_name

(required) The name of the radio station. This field is used by our keyword search on our consumer facing site and needs to be something friendly for full-text search. It is easier to find a station named “94.7 Hot Dance Mix and Club Tracks” than just “94.7 The Mix” - this is our recommendation - we realize users will name their radio stations whatever they want. But a well-named station is more likely to come up in our search results.

station_desc

(required) Two or three sentence description of the station - this field is used in keyword search - it helps to have specific information pertaining to the type of music or programming delivered by the station.

station_url

(required) The website address. Starting with http:// - please include it.

station_country

(required) Two letter ISO country code (ex: US = United States)

List here: http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

mysql table here: http://27.org/isocountrylist/

station_city

(required) Station city - used in search.

station_zip

(optional)  Postal code. Used in geographic search - not required.

station_facebook

(optional) Full url to station facebook page starting with ‘http://’ - if provided we will link to their facebook page off their streamfinder station page.

station_twitter

(optional) Twitter username. No need to provide full url, just the username. If provided we will provide a link to their twitter page and we will auto-follow them.

station_myspace

(optional) Full url to station myspace page starting with ‘http://’ - if provided we will link to their myspace page off their streamfinder station page.

widget_code

(optional) If station has a player widget or if you provide such a widget them add the code here. It can be object, embed or html code. Heavily filtered.

genre1

(genre1 required) These are ID’s that relate to our genre values.

genre2

(optional)

genre3

(optional)

genre4

(optional)

tag1

(optional) This can be additional meta information that is searchable on the site - it can be the same as the genre names or something different not represented in genre values.

tag2

tag3

tag4

(optional)

stream_url1

(required) Full url (http:// or mms:// included) to the streaming link. NOT a link to a player page or widget - this is a direct link to the streaming source. A station can have multiple streams

Shoutcast Example:

http://servername.com:8000/listen.pls OR http://128.128.128.128:8000/stream.pls 

Shoutcast AAC Example:

http://servername.com:8000/listen_aac.pls OR http://128.128.128.128:8000/stream_aac.pls 

Windows Media Example:

http://servername.com/listen.asx 

MP3 Example:

http://servername.com/listen.m3u 

OGG Example:

http://servername.com/listen.ogg 

IceCast Example:

http://servername.com/mountpoint/listen.m3u 

Real Media Example:

http://servername.com/listen.ra 

Quicktime Example:

http://servername.com/listen.mov

stream_url1_format

(required) Type of stream. Values listed below

sc         = shoutcast 1.x

sc2         = shoutcast 2.x

sc_aac = shoutcast aac+ stream

ic         = icecast

wm         = windows media

ogg         = ogg vorbis stream

mp3         = direct mp3 stream

real         = real media

qt         = quicktime

stream_url1_bitrate

(required) Integer representing streaming rate in KBPS. 32, 96, 128 etc.

stream_url2

stream_url2_format

stream_url2_bitrate

stream_url3

stream_url3_format

stream_url3_bitrate

stream_url4

stream_url4_format

stream_url4_bitrate

(all optional)

Creating the JSON object:

1) Define your stations as an array - in PHP it would look something like this:

$stations[1] = array(

“contact_name” => “Huey Malham”,

“contact_email” => “manager@hotmix96.com”,

“station_name” => “Hot Mix 96 - Chicago\’s Urban and Soul”,

“station_desc” => “Playing the best of recent urban music”,

“station_url” => “http://hotmix96.com”,

“station_country” => “US”,

“station_city” => “Chicago”,

“genre1” => 34,

“genre2” =>  128,

“genre3” => 46,

“tag1” => “Chicago House Music”,

“tag2” => “DJ Cheez Wiz”,

“stream_url1” => “http://hosting-provider.com/stream/listen.pls”,

“stream_url1_format” => “sc”,

“stream_url1_bitrate” => “128”,

“stream_url2”  =>  “http://hosting-provider.com/stream/listen.asx”,

“stream_url2_format”  =>  “wm”,

“stream_url2_bitrate”  =>  “128”,

“stream_url3”  =>  “http://hosting-provider.com/stream/listen_aac.pls”,

“stream_url3_format”  =>  “sc_aac”,

“stream_url3_bitrate”  =>  “32”

);

//Convert the array to a json obj

//http://www.php.net/manual/en/function.json-encode.php

$stations_json = json_encode($stations);

All stations to be added should be inside a json object called stations (obj)

example $stations_json above would look like this:

“stations” : [

{

//station 1

“contact_name” : “Huey Malham”,

“contact_email” : “manager@hotmix96.com”,

“station_name” : “Hot Mix 96 - Chicago\’s Finest R&B, Urban and Soul”,

“station_desc” : “Playing the best of recent urban music, rap and r&b....”,

“station_url” : “http://hotmix96.com”,

“station_country” : “US”,

“station_city” : “Chicago”,

“genre1” : 34,

“genre2” : 128,

“genre3” : 46,

“tag1” : “Chicago House Music”,

“tag2” : “DJ Cheez Wiz”,

“stream_url1” : “http://hosting-provider.com/stream/listen.pls”,

“stream_url1_format” : “sc”,

“stream_url1_bitrate” : “128”,

“stream_url2” : “http://hosting-provider.com/stream/listen.asx”,

“stream_url2_format” : “wm”,

“stream_url2_bitrate” : “128”,

“stream_url3” : “http://hosting-provider.com/stream/listen_aac.pls”,

“stream_url3_format” : “sc_aac”,

“stream_url3_bitrate” : “32”,

}

,

{

//station 2

//..etc

}

]

Example API Usage in PHP

//fill in the station data array

$stations[1] = array(

“contact_name” => “Huey Malham”,

“contact_email” => “manager@hotmix96.com”,

“station_name” => “Hot Mix 96 - Chicago\’s Urban and Soul”,

“station_desc” => “Playing the best of recent urban music”,

“station_url” => “http://hotmix96.com”,

“station_country” => “US”,

“station_city” => “Chicago”,

“genre1” => 34,

“genre2” =>  128,

“genre3” => 46,

“tag1” => “Chicago House Music”,

“tag2” => “DJ Cheez Wiz”,

“stream_url1” => “http://hosting-provider.com/stream/listen.pls”,

“stream_url1_format” => “sc”,

“stream_url1_bitrate” => “128”,

“stream_url2”  =>  “http://hosting-provider.com/stream/listen.asx”,

“stream_url2_format”  =>  “wm”,

“stream_url2_bitrate”  =>  “128”,

“stream_url3”  =>  “http://hosting-provider.com/stream/listen_aac.pls”,

“stream_url3_format”  =>  “sc_aac”,

“stream_url3_bitrate”  =>  “32”

);

//Convert the array to a json obj

//http://www.php.net/manual/en/function.json-encode.php

$stations_json = json_encode($stations);

//prepare to post up the data into the api

$url = http://streamfinder.com/api/ingest/?api_codekey=[codekey]&do=add&stations=$stations_json”;

//use cURL to send the data to the api

//http://www.php.net/manual/en/function.curl-exec.php 

// create a new cURL resource

$ch = curl_init();

// set URL and other appropriate options

curl_setopt($ch, CURLOPT_URL , $url);

curl_setopt($ch, CURLOPT_HEADER, 0);

// grab URL and pass it to the browser

curl_exec($ch);

// close cURL resource, and free up system resources

curl_close($ch);