You came this way: Home > API

API Docs

Basics

Free Music Archive provides a basic API to access artist, album, track, and curator data, in XML or JSON format that can be accessed via: 

http://freemusicarchive.org/api/get/{dataset}.{format}

For example: 

http://freemusicarchive.org/api/get/curators.xml

... 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?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?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?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?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?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

  • 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

  • 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
    • artist_id

      (integer) Filter albums by artist id

    • artist_handle

      (string) Filter albums by artist handle

    • genre_handle

      (string) Filter albums by genre handle

    • curator_handle

      (string) Filter albums by curator handle

  • Tracks

    Fields
    • track_id
    • track_title
    • track_url
    • track_image_file
    • artist_id
    • artist_name
    • artist_url
    • album_id
    • album_title
    • album_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_date_created
    Parameters
    • artist_id

      (integer) Filter tracks by artist id

    • album_id

      (integer) Filter tracks by album id

    • genre_id

      (integer) Filter tracks by genre id

    • genre_handle

      (string) Filter tracks by genre handle

    • artist_handle

      (string) Filter tracks by artist handle

    • curator_handle

      (string) Filter tracks by curator handle