songkick-js v1.2.1

Songkick JS

A javascript wrapper library to work with the Songkick API.

Getting Started

Install

Install with npm or include the script located on the dist folder (SongkickJS.min.js)

$ npm i --save-dev songkick-js

Initializing

Create a new instance of the SongkickJS class passing as parameters a string with your API key, and a boolean indicating if the API should be requested via https. You can request an API key here.

// if installed via npm
// import the library as es6 module
import SongkickJS from 'songkick-js';
// or common js
const SongkickJS = require('songkick-js');

// create an instance of SongkickJS
const songkick = new SongkickJS('your-api-key', true);

How it works

All methods makes an AJAX request to the Songkick API and returns a promise with a JSON object containing the response data.

Example calling the getUpcomingEvents method:

songkick
  .getUpcomingEvents({
    from: 'artists',
    id: '379603' // id for Rolling Stones
  })
  .then(data => {
    console.log(data);
  });

Logs the response data:

{
  "status": "ok",
  "results": {
    "event": [
      {
        "type": "Concert",
        "popularity": 0.473291,
        "displayName": "The Rolling Stones at Mercedes-Benz Arena (June 30, 2018)",
        "status": "ok",
        "performance": [
          {
            "displayName": "The Rolling Stones",
            "billingIndex": 1,
            "billing": "headline",
            "artist": {
              "displayName": "The Rolling Stones",
              "identifier": [
                {
                  "href": "http://api.songkick.com/api/3.0/artists/mbid:b071f9fa-14b0-4217-8e97-eb41da73f598.json",
                  "mbid": "b071f9fa-14b0-4217-8e97-eb41da73f598"
                },
                {
                  "href": "http://api.songkick.com/api/3.0/artists/mbid:a52940ca-3ec9-4a2b-89e4-ad358f64c8f7.json",
                  "mbid": "a52940ca-3ec9-4a2b-89e4-ad358f64c8f7"
                }
              ],
              "uri": "http://www.songkick.com/artists/379603-rolling-stones?utm_source=48647&utm_medium=partner",
              "id": 379603
            },
            "id": 63462749
          }
        ],
        "ageRestriction": null,
        "start": {
          "datetime": null,
          "time": null,
          "date": "2018-06-30"
        },
        "location": {
          "city": "Stuttgart, Germany",
          "lat": 48.7908464,
          "lng": 9.2313422
        },
        "uri": "http://www.songkick.com/concerts/32988509-rolling-stones-at-mercedesbenz-arena?utm_source=48647&utm_medium=partner",
        "id": 32988509,
        "venue": {
          "displayName": "Mercedes-Benz Arena",
          "lat": 48.7908464,
          "lng": 9.2313422,
          "metroArea": {
            "displayName": "Stuttgart",
            "country": {
              "displayName": "Germany"
            },
            "uri": "http://www.songkick.com/metro_areas/28591-germany-stuttgart?utm_source=48647&utm_medium=partner",
            "id": 28591
          },
          "uri": "http://www.songkick.com/venues/508341-mercedesbenz-arena?utm_source=48647&utm_medium=partner",
          "id": 508341
        }
      },
      (...)
    ]
  },
  "perPage": 50,
  "page": 1,
  "totalEntries": 3
}

Methods

getUpcomingEvents

This method returns the upcoming events from an artist, a venue, a metro area or an user.

songkick
  .getUpcomingEvents({
    from: 'metro_areas',
    id: '7644', // id for New York, NY, US
    optionalParams: {
      min_date: '2018/06/01',
      max_date: '2018/12/31',
      page: 1,
      per_page: 20,
      order: 'asc'
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

getPastEvents

This method returns the past events from an artist or an user.

songkick
  .getPastEvents({
    from: 'artists',
    id: '379603', // id for Rolling Stones
    optionalParams: {
      min_date: '2018/06/01',
      max_date: '2018/12/31',
      page: 1,
      per_page: 20,
      order: 'asc'
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

getDetails

This method returns details from an artist, an event or a venue.

songkick
  .getDetails({
    from: 'artists',
    id: '379603' // id for Rolling Stones
  })
  .then(data => {
    // do something with the response data
  });

Parameters

getUserTrackings

This method returns the artists or metro_areas that an user is tracking.

songkick
  .getUserTrackings({
    username: 'username',
    trackingObject: 'metro_areas',
    optionalParams: {
      page: 1,
      per_page: 20,
      fields: 'id,displayName',
      created_after: '2018-02-28T13:37:00Z'
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

getUserMutedArtists

This method returns the artists which the user once tracked but has subsequently untracked.

songkick
  .getUserMutedArtists({
    username: 'username',
    optionalParams: {
      page: 1,
      per_page: 20,
      fields: 'id,displayName',
      created_after: '2018-02-28T13:37:00Z'
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

isUserTracking

This method check if the user is tracking a metro area, an artist or an event. If the user is tracking the metro area or artist, returns a tracking. Otherwise a 404 response is returned. If the user is attending or did attend the event, returns a tracking with its attendance (im_going|i_might_go). Otherwise a 404 response is returned.

songkick
  .isUserTracking({
    username: 'username',
    trackingObject: 'artist',
    id: '379603' // id for Rolling Stones
  })
  .then(data => {
    // do something with the response data
  });

Parameters

getSimilarArtists

This methods returns a list of artists similar to a given artist, based on Songkick's tracking and attendance data.

songkick
  .getSimilarArtists({
    id: '379603', // id for Rolling Stones
    optionalParams: {
      page: 1,
      per_page: 20
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

searchEvents

This methods returns a list of events based on the search parameters.

songkick
  .searchEvents({
    searchBy: {
      artist_name: 'rolling+stones'
    },
    optionalParams: {
      type: 'Concert',
      page: 1,
      per_page: 20,
      min_date: '2018/06/01',
      max_date: '2018/12/31'
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

** only one parameter is allowed on the "searchBy" object ("artist_name" or "location").

The options below can be used in the "location" parameter to specify how the content returned should be localised:

searchArtists

This methods returns a list of artists based on the search query. This method searches by the artist's name.

songkick
  .searchArtists({
    query: 'rolling+stones',
    optionalParams: {
      page: 1,
      per_page: 20
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

searchVenues

This methods returns a list of venues based on the search query. This method searches by the venue's name.

songkick
  .searchVenues({
    query: 'madison+square+garden',
    optionalParams: {
      page: 1,
      per_page: 20
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

searchLocations

This methods returns a list of cities and its metro areas based on the search parameters.

songkick
  .searchLocations({
    searchBy: {
      location: 'clientip'
    },
    optionalParams: {
      page: 1,
      per_page: 20
    }
  })
  .then(data => {
    // do something with the response data
  });

Parameters

** only one parameter is allowed on the "searchBy" object ("query" or "location").

The options below can be used in the "location" parameter to specify how the content returned should be localised: