Skip to content

Home

Jump to bottom Edit New page
peoplesmusicstore edited this page Sep 13, 2010 · 7 revisions

People’s Music Store API documentation.

People’s Music Store use Ruby on Rails’ restful routes, and therefore the API is pretty discoverable.

Contents:

  • Formats
    • XML
    • JSON
    • JSONP
  • Resources
    • Store
    • Product
      • Track
      • Release
    • Preview files
  • Search
    • Search parameters
    • Searching Releases
    • Searching Tracks
    • Searching Stores

Formats

You can HTTP GET most resources in HTML, JSON, JSONP and XML

For example, to get an XML representation for a store, use the same URL, but with an xml file extension:

XML

curl http://peoplesmusicstore.com/coupde.xml

will return:

<?xml version="1.0" encoding="UTF-8"?>
<store>
  <description-html>Music that blows</description-html>
  <id type="integer">501</id>
  <logo-image-path>/images/uploaded/0000/2223/bald_boring.jpg</logo-image-path>
  <title>Coup de tunes</title>
  <url>http://peoplesmusicstore.com/coupde</url>
  <collections type="array">
    <collection>
      <description-html nil="true"></description-html>
      <title>Wrong Music</title>
      <collection-items type="array">
        <collection-item>
          <title>Hang The DJ</title>
          <artist>Shitmat</artist>
          <url>http://peoplesmusicstore.com/coupde/catalogue_items/70304</url>
        </collection-item>
      </collection-items>
    </collection>
  </collections>
</store>

JSON

curl http://peoplesmusicstore.com/coupde.json

will return:

{
  "logo_image_path": "/images/uploaded/0000/2223/bald_boring.jpg",
  "collections": 
  [{
    "collection_items":
    [{
      "artist": "Shitmat", 
      "url": "http://peoplesmusicstore.com/coupde/catalogue_items/70304", 
      "title": "Hang The DJ"
    }], 
    "title": "Wrong Music", 
    "description_html": null
  }], 
  "title": "Coup de tunes", 
  "description_html": "Music that blows", 
  "id": 501, 
  "url": "http://peoplesmusicstore.com/coupde"
}

JSONP

We also support a callback method on JSON requests, so you are able to do client-side cross domain requests:

curl http://peoplesmusicstore.com/coupde.json?callback=methodname

will return:

methodname({
  "logo_image_path": "/images/uploaded/0000/2223/bald_boring.jpg",
  "collections": 
  [{
    "collection_items":
    [{
      "artist": "Shitmat", 
      "url": "http://peoplesmusicstore.com/coupde/catalogue_items/70304", 
      "title": "Hang The DJ"
    }], 
    "title": "Wrong Music", 
    "description_html": null
  }], 
  "title": "Coup de tunes", 
  "description_html": "Music that blows", 
  "id": 501, 
  "url": "http://peoplesmusicstore.com/coupde"
})

Resources

Store

As shown above, stores return some basic details, then all collections, with the collection items (the products) within them.

Product

Returns either a track or a product object. You can access these from either the People’s Music Store catalogue, or a specific store’s catalogue. The data set is the same, but the latter provides the data in the store’s context.

curl http://peoplesmusicstore.com/catalogue_items/69622.xml

or

curl http://peoplesmusicstore.com/coupde/catalogue_items/69622.xml

Track

A representation of the track object, with some meta information, a url for the product on the site, and the preview url.

<?xml version="1.0" encoding="UTF-8"?>
<track>
  <artist>chezny hawks</artist>
  <explicit type="boolean" nil="true"></explicit>
  <genres>Experimental</genres>
  <id type="integer">69622</id>
  <isrc></isrc>
  <release-id type="integer">69621</release-id>
  <set-number type="integer">1</set-number>
  <title>rolf wank track</title>
  <track-number type="integer">1</track-number>
  <length type="integer">325</length>
  < preview-url>http://preview.peoplesmusicstore.com/0000/0000/0006/9622/69622.mp3</ preview-url>
  <url>http://peoplesmusicstore.com/coupde/catalogue_items/69622</url>
</track>

Release

A release has a one to many relationship with tracks. Usually this means it is an album, but it can be an EP with a couple of tracks, or even only one track. Every track belongs to one release.

<?xml version="1.0" encoding="UTF-8"?>
<release>
  <artist>Amon Tobin</artist>
  <catalogue-number>ZENDL121</catalogue-number>
  <explicit type="boolean">false</explicit>
  <id type="integer">26622</id>
  <label-name>Ninja Tune</label-name>
  <live type="boolean" nil="true"></live>
  <title>Foley Room</title>
  <upc>625978112120</upc>
  <url>http://peoplesmusicstore.com/coupde/catalogue_items/26622</url>
  <tracks type="array">
    <track>
      <artist>Amon Tobin</artist>
      <explicit type="boolean">false</explicit>
      <genres>Electronic</genres>
      <id type="integer">26623</id>
      <isrc>GBCFB0601500</isrc>
      <release-id type="integer">26622</release-id>
      <set-number type="integer">1</set-number>
      <title>Bloodstone</title>
      <track-number type="integer">1</track-number>
      <length type="integer">253</length>
      < preview-url>http://preview.peoplesmusicstore.com/0000/0000/0002/6623/26623.mp3</ preview-url>
      <url>http://peoplesmusicstore.com/coupde/catalogue_items/26623</url>
    </track>
  </tracks>
</release>

Preview files

You can get a 32 bit mono MP3 of any 30 seconds of any track, using the preview file mp3 provided in the track object.
To offset the starting point, pass it the parameter start with the number of seconds.

http://preview.peoplesmusicstore.com/0000/0000/0006/9622/69622.mp3?start=50

Search

The search API can search all of People’s Music Store releases, tracks and stores.

Search parameters

There are two parameters you can add to the get request:

type

This defines what you are searching, options are:

  • release
  • track
  • store

The default search type is release.

q

This is the string search query sent to our search engine. A simple phrase will search all relevant fields, but you can also do more advanced searches by searching for a particular field. The fields available to each type (release, track and store) are listed under each category below. To use this, use the format

@field(value)

For instance, to search for just the artist field, you do:

http://peoplesmusicstore.com/search.xml?q=@artist("Aphex+Twin")

We support various extended query syntaxes, such as ‘&’, ‘|’ and ‘!’ for AND, OR and NOT respectively. there is very details documentation at The sphinx search docs

page

Obviously, we won’t return all the results at once, we paginate them. You can choose which page using the page parameter which you pass an integer.

sort

By default, we will return results by relevance, but you can override this with the sort parameter. For stores, you can sort by ‘created_at’ for when they were created. For releases and track you can sort by:

  • title
  • artist
  • label_name

dir

Sets the direction of the sort, can be:

  • asc
  • desc

Searching Releases

Returns an array of release objects.

Advanced searching fields

  • title: The release title
  • artist: The artist of the release
  • label_name: The name of the label the release was released on. (‘label’ is an alias of this)
  • catalogue_number: The record label’s catalogue number.
  • ref: The supplier reference number. The unique identifier the supplier of this content uses.
  • upc: The universal unique identifier of this release, it’s barcode. More info
  • tag: Usually the genre and sub-genres the supplier has categorised this release as, eg ‘Electronica’
  • track_artists: Searching for the artist of one or more of the tracks on a release.
  • track_title. Searching for the titles of the tracks within a release

Searching Tracks

Returns an array of track objects.

Advanced searching fields

  • title: The track title
  • artist: The artist of the track
  • label_name: The name of the label the track was released on. (‘label’ is an alias of this)
  • ref: The supplier reference number. The unique identifier the supplier of this content uses.
  • isrc: The universal unique identifier of this track. More info
  • tag: Usually the genre and sub-genres the supplier has categorised this track as, eg ‘Electronica’

Searching Stores

Returns an array of store objects.

Advanced searching fields

  • name: The store name.
  • tag: What the store owner has tagged their store with.
  • description: The store description text.
  • title: The title of any of the releases or tracks added to their store.
  • artist: The artist of any of the releases or tracks added to their store.
  • label: The label name of any of the releases or tracks added to their store.
Add a custom footer
Add a custom sidebar
Clone this wiki locally