idiomag API Documentation

The new idiomag API lets you build your own applications using idiomag data.

idiomag is a personalised publishing platform that aggregates quality content about music, and delivers a unique blend to every reader based on their music taste. This page provides the full details of all the API functionality. Please email api@idiomag.com for any technical questions you may have.

What you get access to

  • Thousands of top news articles, reviews, and interviews
  • Filtered videos, images and MP3s for tens of thousands of artists
  • Collaborative filtering and "discovery" music recommendation based on single or multiple artists, and via profile-import from a wide variety of 3rd party sites including Last.fm, Pandora, iLike and iMeem
  • A leading implementation of APML, providing access to user's music interest profiles, for both input and output of the recommendation technology
  • Terms for Commercial and Non-commercial use the API are available here.

How it Works

  • The idiomag API is RESTful, with calls constructed in the form:
  • http://www.idiomag.com/api/<resource>/<method>/<format>?key=<key>
  • All API calls require the parameter 'key' to be passed. Key is your unique API identifier which you receive when you sign up as a developer.
  • Our API calls are available in multiple formats including xml, json, rss, apml, xspf and foaf. You can specify which format you would like by adding /format to the end of the url, eg /artists/articles/xml. Which formats are available vary by call, all calls are available in both xml and json.
  • For example, to receive the latest articles about the artist 'Radiohead' in RSS format use the uri:
  • http://www.idiomag.com/api/artist/articles/rss?key=<key>&artist=Radiohead
  • Or for a playlist of videos for a tag (genre) in xspf format:
  • http://www.idiomag.com/api/tag/videos/xspf?key=<key>&tag=Indie
  • With JSON formatted output you can also specify a callback for use in JSONP:
  • http://www.idiomag.com/api/tag/videos/json?key=<key>&tag=Indie&callback=alert

Your Idiomag API Account

Please login to idiomag or join below in order to use the API. All fields are required.

Idiomag API Methods

Articles Methods

  • /articles/latest/
    Returns a list of the latest articles available in idiomag
    - Required inputs: key
    - Available output formats: xml, json, rss

Artist Methods

  • /artist/info/
    Returns information about a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json
  • /artist/tags/
    Returns a list of tags for a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json, apml
  • /artist/articles/
    Returns a list of latest articles for a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json, rss
  • /artist/photos/
    Returns a list of latest photos for a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json, rss
  • /artist/videos/
    Returns a list of latest videos for a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json, xspf
  • /artist/playlist/
    Returns a list of latest songs for a given artist
    - Required inputs: key, artist
    - Available output formats: xml, json, xspf

User Methods

  • /user/info/
    Returns information about a given user
    - Required inputs: key, user
    - Available output formats: xml, json, apml
  • /user/friends/
    Returns a list of friends for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, foaf
  • /user/articles/
    Returns a list of latest articles for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, rss
  • /user/lovedarticles/
    Returns a list of latest loved articles for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, rss
  • /user/photos/
    Returns a list of latest photos for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, rss
  • /user/videos/
    Returns a list of latest videos for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, xspf
  • /user/playlist/
    Returns a list of latest songs for a given user
    - Required inputs: key, user
    - Available output formats: xml, json, xspf

Tag Methods

A tag is a music genre, such as Indie, Jazz or Emo. Click here to see a list of all tags currently available.

  • /tag/articles/
    Returns a list of latest articles for a given tag
    - Required inputs: key, tag
    - Available output formats: xml, json, rss
  • /tag/photos/
    Returns a list of latest photos for a given tag
    - Required inputs: key, tag
    - Available output formats: xml, json, rss
  • /tag/videos/
    Returns a list of latest videos for a given tag
    - Required inputs: key, tag
    - Available output formats: xml, json, xspf
  • /tag/playlist/
    Returns a list of latest songs for a given tag
    - Required inputs: key, tag
    - Available output formats: xml, json, xspf
  • /tag/artists/
    Returns a list of artists for a given tag
    - Required inputs: key, tag
    - Available output formats: xml, json, apml

Recommendation Methods

Recommendation provides recommendations based on a list of artists. This list of artists can be provided as either an apml file, a series of request parameters or imported from a third party site such as last.fm.

APML

To receive a recommendation from an apml file of artists, you will need to pass the url of a valid apml file as parameter 'apml'. For example:

http://www.idiomag.com/api/recommendation/articles/xml?key=<key>&apml=http%3A%2F%2Fresearch.sun.com%3A8080%2FAttentionProfile%2Fapml%2Fmusic%2Fpixelm2

Artist List

To receive a recommendation from a list of artists, provide these artists as multiple 'artists[]' parameters. For example:

http://www.idiomag.com/api/recommendation/articles/xml?key=<key>&artists[]=muse&artists[]=radiohead

Third Party Sites

Recommendations can be provided from user profiles on third party websites. To receive these provide a network name with parameter 'network' and the desired username with parameter 'username'. Supported network names are 'lastfm', 'mog', 'ilike', 'mystrands', 'projectplaylist', 'imeem', 'pandora', 'bebo', 'myspace' and 'songza'. For example:

http://www.idiomag.com/api/recommendation/articles/xml?key=<key>&network=lastfm&username=pixelm2

  • /recommendation/articles/
    Returns a list of latest articles recommended for given artists
    - Required inputs: key, One of (artists[], apml or [network and user])
    - Available output formats: xml, json, rss
  • /recommendation/artists/
    Returns a list of artists recommended for given artists
    - Required inputs: key, One of (artists[], apml or [network and user])
    - Available output formats: xml, json, apml