API Docs

API Key

The first step is to sign up for an API key. Starting in April 2012, we will refuse API queries without a valid API key.

Basics

Free Music Archive provides a basic API to access artist, album, track, genre and curator data, in XML, JSON or JSONP format.

You can access all the data by formatting URLs like so:

http://freemusicarchive.org/api/get/{dataset}.{format}?api_key={yourkey}

For example:

http://freemusicarchive.org/api/get/curators.xml?api_key=60BLHNQCAOUFPIBZ

... will return a list of FMA curators in XML format.

Parameters

Certain parameters can be passed via query string to your request to sort, paginate, and filter the resulting dataset.

Pagination & Sorting

All results are paginated and set to a limit of 20 per page by default. This can be set directly via a 'limit' query string parameter, with a maximum allowed value of 50, like so:

http://freemusicarchive.org/api/get/curators.xml?api_key=60BLHNQCAOUFPIBZ&limit=10

You can also page a 'page' query string parameter to navigate to specific result pages of the dataset:

http://freemusicarchive.org/api/get/curators.xml?api_key=60BLHNQCAOUFPIBZ&limit=10&page=3

Each dataset indicates the total number of records ('total'), the total number of pages ('pages'), the current page ('page'), and the current record limit per page ('limit').

Each dataset can also be sorted by any field that is returned, using 'sort_by' and 'sort_dir' (sort direction) query string parameters. The 'sort_by' parameter can be any field returned in the set (listed below) and 'sort_dir' can be set to 'asc' (ascending) or 'desc' (descending).

http://freemusicarchive.org/api/get/curators.xml?api_key=60BLHNQCAOUFPIBZ&limit=10&page=3&sort_by=curator_date_created&sort_dir=desc

Certain datasets can also take extra query string parameters to filter results. For example, albums can be filtered by an artist's 'artist_id' value, like so:

http://freemusicarchive.org/api/get/albums.xml?api_key=60BLHNQCAOUFPIBZ&artist_id=128

All records accessible via the api have corresponding "handles", which are unique string identifiers for each record. You can can find handles at the end of the URLs throughout the site, and use them instead of ids. For instance, WFMU's curator page is here:

http://freemusicarchive.org/curator/wfmu

'wfmu' is the "curator_handle", which you can use to query all of WFMU's albums:

http://freemusicarchive.org/api/get/albums.xml?api_key=60BLHNQCAOUFPIBZ&curator_handle=wfmu

Specific filter options are listed per dataset below.

Datasets

• Curators

  Fields

  • curator_id
  • curator_handle
  • curator_url
  • curator_site_url
  • curator_image_file
  • curator_type
  • curator_title
  • curator_tagline
  • curator_bio
  • curator_site_url
  • curator_favorites
  • curator_comments
  • curator_playlists
  • curator_date_created

• Genres

  Fields

  • genre_id
  • genre_parent_id
  • genre_title
  • genre_handle
  • genre_color

• Artists

  Fields

  • artist_id
  • artist_handle
  • artist_url
  • artist_name
  • artist_bio
  • artist_members
  • artist_website
  • artist_wikipedia_page
  • artist_donation_url
  • artist_contact
  • artist_contact_address
  • artist_active_year_begin
  • artist_active_year_end
  • artist_related_projects
  • artist_associated_labels
  • artist_comments
  • artist_favorites
  • artist_date_created
  • artist_flattr_name
  • artist_paypal_name

• Albums

  Fields

  • album_id
  • album_handle
  • album_url
  • album_title
  • album_type
  • artist_name
  • artist_url
  • album_producer
  • album_engineer
  • album_information
  • album_date_released
  • album_comments
  • album_favorites
  • album_tracks
  • album_listens
  • album_date_created

  Parameters

  • album_handle

    (string) include album with album handle

  • artist_id

    (integer) include albums with artist id

  • artist_handle

    (string) include albums with artist handle

  • genre_handle

    (string) include albums with genre handle

  • curator_handle

    (string) include albums with curator handle

• Tracks

  Fields

  • track_id
  • track_title
  • track_url
  • track_image_file
  • artist_id
  • artist_name
  • artist_url
  • artist_website
  • album_id
  • album_title
  • album_url
  • license_title
  • license_url
  • track_language_code
  • track_duration
  • track_number
  • track_disc_number
  • track_explicit
  • track_explicit_notes
  • track_copyright_c
  • track_copyright_p
  • track_composer
  • track_lyricist
  • track_publisher
  • track_instrumental
  • track_information
  • track_date_recorded
  • track_comments
  • track_favorites
  • track_listens
  • track_interest
  • track_bit_rate
  • track_date_created

  Parameters

  • track_id

    (integer) include only track with track id

  • artist_id

    (integer) include tracks with artist id

  • album_id

    (integer) include tracks with album id

  • genre_id

    (integer) include tracks with genre id

  • genre_handle

    (string) include tracks with genre handle

  • artist_handle

    (string) include tracks with artist handle

  • curator_handle

    (string) included tracks with curator handle

  • commercial

    (boolean) include tracks where permitted use for commercial purposes

  • remix

    (boolean) include tracks where permitted to remix

  • podcast

    (boolean) include tracks where permitted to add to podcast

  • video

    (boolean) include tracks where permitted to sync with video

  • added_week

    (boolean) include tracks added in the last week

  • added_month

    (boolean) include tracks added in the last month

  • only_instrumental

    (boolean) include only instrumental tracks

  • only_radio_safe

    (boolean) include only radio safe tracks

  • min_duration

    (time) include tracks at leasts as long as (must be in 'HH:MM:SS' format)

  • max_duration

    (time) include tracks no longer than (must be in 'HH:MM:SS' format)

Friendly Usage

Make an effort to avoid excessive queries. Cache responses to avoid duplicating queries. If you expect a large volume of traffic (more than 10000 per day), please contact us (dev@freemusicarchive.org) to discuss.