iheart-api

Collected documentation on what I've learned about iHeartRadio's API. Most (all)
of this is copied from comments in the source code, referenced by file.

<parse_iheart_json.py>

# The iheartradio API is not publicly documented, to my knowledge. At 
# the time of writing, one can submit a GET request to a URL of the
# following form (where STATION_ID_NUMBER is a five-digit number):
#
# http://iheart.com/a/live/station/STATION_ID_NUMBER/stream/
#
# The response will be UTF-8 encoded JSON describing some vital
# information about the station (if it exists), such as name, market,
# genre, and links to various live streams of its content (often RTMP or
# HTTP, but usually (never?) both). Valid station ID numbers can
# currently be obtained by searching for stations on the
# http://www.iheart.com website - for example, in the following URL, the
# station ID number is 1165:
#
# http://www.iheart.com/live/WOOD-Radio-1069-FM-1300AM-1165/
#
# See also the docstring and block comment for station_search().
#
# However, in late 2014, iheart altered this particular API structure.
# It now contains far less information than it used to, and is not used
# here anymore. Deep-packet analysis of various official iHeartRadio
# apps is still underway, for now the following URL seems to work
# (used by the Roku channel):
#
# http://proxy.iheart.com/streams_list_by_ids/?stream_ids=STATION_ID_NUMBER&apikey=null
# AGAIN, in early 2017 the above API broke; the new URL comes from
# Nathan Rajlich's node.js library (https://github.com/TooTallNate/iheart).
# Deep-packet analysis of official iHeartRadio apps remains to be done.

(by happy coincidence, here's the block comment for station_search())

# This information is derived from deep packet inspection of the
# official iHeartRadio Android app's HTTP traffic. Exhaustive analysis
# has not been done as of this writing.
#
# iheartradio has a simple API for running searches against its station
# database. The response to a GET request to a URL of the form:
#
# http://api.iheart.com/api/v1/catalog/searchAll?&keywords=<keywords>
#
# where <keywords> is a search term, will be UTF-8 encoded JSON giving
# detailed search results; containing both search metadata and detailed
# information on all search results. Importantly, ID numbers for search
# results are included.
#
# There are a great many additional parameters that the official app
# includes. A full API request URL from the official app follows:
#
# http://api2.iheart.com/api/v1/catalog/searchAll?&keywords=wjr&bestMatch=True&queryStation=True&queryArtist=True&queryTrack=True&queryTalkShow=True&startIndex=0&maxRows=12&queryFeaturedStation=False&queryBundle=False&queryTalkTheme=False&amp_version=4.11.0
#
# Analysis of these parameters will be conducted some other time (TM),
# however it appears only &keywords is necessary; it is the only one
# this program uses.

(in the following, note that the 'station dictionary' is generated directly
from iheart's JSON by the standard json module)

(The following comment block refers to some obsolete data structures, but the
stream types it refers to are once again present as of early 2017. Note that
in early 2017 there are secure_ variants of several non-rtmp stream types, that
simply refer to an https:// URL rather than an http:// URL.)

# There are two keys within the station dictionary which contain dicts
# of stream URLs. The first is 'stream_urls', which seems to always have
# at least two members - 'rtmp' (which is an RTMP URL which VLC and some
# mplayer versions don't seem to understand) and 'http' (which is an
# HTTP URL which neither mplayer or vlc seem to understand in any case I
# have tested). Quite often, at least one of these will be None (but
# both are always present for a valid station). For our purposes we will
# ignore this member. The second is 'streams', which *only* contains
# members for those streams which actually exist (there will never be a
# None in this dict). Keys which have been observed:
#
# shoutcast_stream: Seems to always be a standard shoutcast stream URL.
#                   Widely understood and works in both VLC and mplayer,
#                   as far as I've tested.
#
# secure_rtmp_stream: An RTMP URL, not always the same as the RTMP URL
#                     in stream_urls. In cases I've seen it's more
#                     likely to work than the RTMP URL in stream_urls,
#                     but some mplayers still don't like it (VLC seems
#                     fine).
#
# rtmp_stream: Yet another rtmp URL; in the one instance I've seen so
#              far, it's identical to the one in stream_urls.
#
# hls_stream: A URL for Apple's HTTP Live Streaming protocol, understood
#             by recent mplayer and VLC.
#
# stw_stream: Some kind of special HTTP-based stream, which neither
#             mplayer or VLC understand. Seems related to the (former?)
#             StreamTheWorld Flash-based platform, always(?) seems to
#             occur together with pls_stream.
#
# pls_stream: Contains a link to a PLS file (INI-based playlist). Occurs
#             alongside stw_stream. Seems to contain a large number of
#             HTTP links, none of which are the same as stw_stream.
#             Seems to work in VLC, but not any mplayer I have tested.
#
# Stations tend to have either both shoutcast_stream and one of the
# RTMP streams, OR both stw_stream and pls_stream. There may be others I
# have not encountered - dictionary dumps (use -vvv) of stations with
# other stream types would be greatly appreciated.