You came this way: Home > API

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.

API Examples

API Demo - apidemo.freemusicarchive.org
a basic demo to create static playlists using FMA + Echo Nest

FMA Radio - fma.jsawruk.com
advanced static playlists using FMA + Echo Nest searches for similar artists, mood, style, license

Unity3D Playlists - http://wiki.musichackday.org/index.php?title=Unity-echonest
A Unity3D plugin that dynamically generates soundtracks based on FMA + Echo Nest

Special APIs

We have a special API for performing a search over artists, albums, and track names; here is an example:

http://freemusicarchive.org/api/trackSearch?q=deerhoof&limit=10

Which returns:

{
  "page_cache_key": "anonuser_pagecache_\/api\/trackSearch?q=deerhoof&limit=10",
  "page_title": "Free Music Archive",
  "aRows": [
    "[Deerhoof] Panda Panda Panda (7172)",
    "[Deerhoof] All Rise (7173)",
    "[Deerhoof] Basket Ball Get Your Groove Back (Live @ KEXP) (8466)",
    "[Dr. David Suendermann] Fresh Born (Deerhoof Cover) (9641)",
    "[Keith Kawaii] Fresh Born (Deerhoof Cover) (9640)",
    "[Deerhoof] Deerhoof at ATP NY (20586)",
    "[Deerhoof] Come See The Duck (23189)",
    "[Matt LeGroulx] New Sneakers (Deerhoof) (84040)"
  ]
}

The number in parentheses is the track ID and the string in the brackets is the artist name.

We make the list of recently added tracks available at:

http://freemusicarchive.org/recent.json

And featured tracks and mixes:

http://freemusicarchive.org/featured

Partnership with The Echo Nest

The Free Music Archive has partnered with The Echo Nest to provide easy integration with the two catalogues.

Developers will now be able to use FMA track IDs with The Echo Nest's API.

For example, to have FMA IDs for tracks included in data from The Echo Nest, add the parameters bucket=id:fma and bucket=tracks to your query, like this:

http://developer.echonest.com/api/v4/song/search?api_key=FILDTEOIK2HBORODV&format=json&artist=Virt&bucket=id:fma&bucket=tracks
Which will return data like this:
{
  "title": "Five Nine Seven Eight",
  "artist_name": "virt",
  "id": "SOLRRUR131F71D6CAE",
  "tracks": [
    {
      "foreign_release_id": "fma:release:8533",
      "catalog": "fma",
      "foreign_id": "fma:track:43491",
      "id": "TRJKVYD131BAB79113"
    }
  ],
  "artist_id": "ARXVV6I1187B9B4F78",
  "audio_md5": "6da4af2de411d9694b0623420d51c683"
}
You can see the FMA IDs in the tracks array.

You can also subsitute FMA IDs in place of Echo Nest IDs in Echo Nest API calls, but they will be prefixed with fma:song instead of fma:track. For example:

http://developer.echonest.com/api/v4/song/profile?api_key=$API_KEY&id=fma:song:43491&bucket=audio_summary

Which will give you:

{
  "response": {
    "status": {
      "version": "4.2",
      "code": 0,
      "message": "Success"
    },
    "songs": [
      {
        "artist_id": "ARXVV6I1187B9B4F78",
        "artist_name": "virt",
        "id": "SOLRRUR131F71D6CAE",
        "audio_summary": {
          "key": 9,
          "analysis_url": "http://echonest-analysis.s3.amazonaws.com/TR/TRJKVYD131BAB79113/3/full.json?AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ&Expires=1375307740&Signature=iUEXU2tWYV60fSaQjLtiEZgJfG0%3D",
          "energy": 0.99061818156176795,
          "liveness": 0.058578841220582725,
          "tempo": 86.694999999999993,
          "speechiness": 0.054231209680322578,
          "acousticness": 0.18354703884809337,
          "mode": 1,
          "time_signature": 5,
          "duration": 270.05342000000002,
          "loudness": -4.3419999999999996,
          "audio_md5": "6da4af2de411d9694b0623420d51c683",
          "valence": 0.91941575353134664,
          "danceability": 0.59704226628847878
        },
        "title": "Five Nine Seven Eight"
      }
    ]
  }
}

For more examples and information about this, please take a look at The Echo Nest's Rosetta Stone documentation.


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_location
    • 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
    • artist_latitude
    • artist_longitude
    • artist_image_file
    • artist_images
  • Albums

    Fields
    • album_id
    • album_title
    • album_handle
    • album_url
    • 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
    • album_image_file
    • album_images
    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

    • album_url

      (string) include albums with album url

    • album_title

      (string) include albums with album title

    • alblum_handle

      (string) include albums with album 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
    • track_file
    • license_image_file
    • license_image_file_large
    • license_parent_id
    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) include tracks with curator handle

    • album_url

      (string) include tracks with album url

    • album_title

      (string) include tracks with album title

    • alblum_handle

      (string) include tracks with album 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.