The Jam API

API Documentation

Depending on your preferred language, you may want to use an API library.

Methods

Person

Overview

Returns information about the requested person, along with their current jam (if any).

Likes

Returns a list of liked jams. Takes the optional parameter ‘show’, which specifies whether to include only current or past (expired) jams.

Jams

Returns a list of the person’s jams. Optional parameter ‘show’ can be set to only show past (expired) jams.

Following

Returns a list of people that a particular person is following. order=followedDate orders by date followed; order=affinity currently orders by number of likes from the requested person; order=name orders by name alphabetically.

Followers

Returns a list of people that a particular person is followers. order=followedDate orders by date followed; order=affinity currently orders by number of likes from the requested person; order=name orders by name alphabetically.

Jam

Overview

Retrieve a single jam by ID.

Likes

Returns a list of the people who liked a particular jam.

Comments

Returns a list of the comments that have been added to a jam.

Comments

Get a single comment

Retrive a single comment by ID.

Search

Note: these haven’t been changed yet to search thru archived jams/songs, so will return nothing. We may fix this soon if time permits.

Searching by artist will return jams by or similar to the requested artist. Genre search is powered by Last.fm tag search. Hashtag support is experimental (no pagination, may be slow).

People search

You can either search for people by name, artist and track. Searching by name returns people with the search string in their username, full name or Twitter name. Searching by artist returns people who have posted tracks by artists (fuzzy) matching the search string. Searching by track returns people who have posted a particular track (strict, case-insensitive matching).

API Basics

Versioning

Our API is currently in version 1. The version number must be present in the URL, e.g. http://api.thisismyjam.com/1/IFTFOM.json

Formats

We currently only support JSON.

Authentication

API calls that create or modify user data require POST requests with OAuth 1.0-style parameters included. Authentication is so much fun that we gave it its own special page with more detail.

Pagination

Lists of items are returned in a paginated fashion, with 60 items per page. Each paged response contains a ‘list’ structure: 

    "list": {
        "next": "http://api.thisismyjam.com/IFTFOM/likes.json?page=2",
        "hasMore": true
    }

On the last page this structure will contain:

    "list": {
        "next": null,
        "hasMore": false
    }

JSONP

The API supports JSONP calls. jQuery example:

    $.getJSON("http://api.thisismyjam.com/1/IFTFOM.json?callback=?",
        function(data) {
            console.log(data);
        });

Request Errors

Requests for missing resources, e.g. http://api.thisismyjam.com/1/idontexist.json return 404.

Invalid requests, e.g. http://api.thisismyjam.com/1/IFTFOM.json?badparameter=bad return 400, along with a message explaining what went wrong.

HTTPS

SSL is enabled for the API. Images URLs are still returned as http links, but we are working on getting them over HTTPS as well.


API Documentation Contents