API

All API calls have a very simple overall structure:

http://api.yes.com/{version}/{call}?{parameters}

Arguments

version
Only version 1 is available currently.
call
One of the various API calls described below.
parameters
Each call has different parameters.

Response

The response is always an object in either JSON or XML, common to every object is one attribute/element "yes" that has the string value of the call name, all other attributes/elements are specific to the call. Many calls return song objects which frequently contain rich metadata such as cover art, videos, and chart positions.

There are two standard parameters that work on any call:

type
[optional] Defaults to 'json' and can be set to 'xml' as an alternative response encoding format (example).
callback
[optional] Only applies with type=json, a function name to wrap the JSON object with.

station

Get current information about a single station including now playing song, slogan, frequency, market, and links to any known webcast stream or site.

Parameters

name
The station name (for AM/FM it is just the call letters).

Examples

stations

Search and find a list of stations by name, frequency, genre, artist, or location.

Parameters

match
[optional] Used to search station names, call letters, slogans, frequency, or cities/states.
freq
[optional] Also match an exact AM/FM frequency.
mid
[optional] Also match only stations that have this media id (see media call) in their top 100 charts.
genre
[optional] Also match any genre keywords like pop, rock, etc.
loc
[optional] Also match stations within 60 miles of the given zip code, "lat,lon", or city/state names.
max
[optional] Defaults to 10 stations returned.

Examples

log

Get the log of all the songs played on the given station in a selected day within the last week.

Parameters

name
The station name.
ago
[optional] The days ago from now for the given date you want, an integer from 0-6 and defaults to 0 (the log today so far).

Examples

recent

Get the most recent songs played on any station.

Parameters

name
The station name.
max
How many recent songs to return (default is 10).

Examples

chart

Get the current top 100 songs for any station based on number of times played and user voting (calculated daily).

Parameters

name
[optional] The station name, defaults to US national top 100 if none given.
date
[optional] Return just the charts from a specific date in the format year-mm-dd (April 2008 and newer).
genre
[optional] Filter any request to a specific Genre ( Americana Blues Christian Classical Country Electronica Hip-Hop Jazz Latin Metal New Age Pop Punk R&B/Soul Rock Smooth Jazz World ).
hot
[optional] Alternative sorting, must be either "fresh" (by most increase in charts day-to-day, not supported in combination with date field) or "vote" (most votes via yes.com).
max
How many songs to return (default is 10).

Examples

media

Get a list of any matching artist names or song titles based on airtime popularity.

Parameters

q
The string to search with, can be partial (used for autocomplete) or full names.
aid
[optional] Instead of a general query, a known Artist ID can be passed to return just media from that artist.
mid
[optional] Instead of a general query, a known Media ID can be passed to return extra information (lyrics from Lyric Wiki and matching videos from YouTube and MTV) about just that song.
max
How many songs to return (default is 10, max is 50).

Examples

related

Given a song, return a list of related songs based on airtime in the last week.

Parameters

mid
The media ID (use media call to search for IDs).
max
Maximum number of related songs to return (default is 20).

Examples

Links, Demos, and Code

The API is growing like mad, definitely join the mailing list or check out some of the links, demos, or code below:

Terms of use