Skip to content

A full-fledged Songkick API wrapper/enhancer for Node.js.

License

Notifications You must be signed in to change notification settings

schnogz/songkick-api-node

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

18 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

songkick-api-node

NPM Version Dependencies Contributions Welcome

A full-fledged Songkick API wrapper/enhancer for Node.js.

Overview

The Songkick API limits requests to a single page with 50 results. This library adds the ability to fetch all results in a single call as well increase the page size above 50.

Usage

You will first need to request a Songkick API key before using this library. Once obtained, simply require this library and instantiate.

  const Songkick = require('songkick-api-node');
  const songkickApi = new Songkick('YourApiKey');

All requests to the library will be returned a promise and when resolved the response will be JSON. If you would like XML responses, simply construct the library as follows:

const songkickApi = new Songkick('YourApiKey', { returnXML: true });

Artists API

getArtistUpcomingEvents(artistId, params)

Returns events an artist has performed in in the past.

Required Parameters:
  • artistId - The ID of the artist.
Optional Parameters:
  • order - The order you want the events returned in. Either 'asc' or 'desc'. Defaults is 'asc'.
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getArtistUpcomingEvents(253846);
songkickApi.getArtistUpcomingEvents(253846, { order: 'desc' });
songkickApi.getArtistUpcomingEvents(253846, { order: 'desc', page: 4, per_page: 25 });

getArtistPastEvents(artistId, params)

Returns events an artist has performed in in the past.

Required Parameters:
  • artistId - The ID of the artist.
Optional Parameters:
  • order - The order you want the events returned in. Either 'asc' or 'desc'), defaults is 'asc'.
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getArtistPastEvents(253846);
songkickApi.getArtistPastEvents(253846, { order: 'desc' });
songkickApi.getArtistPastEvents(253846, { order: 'desc', page: 4, per_page: 25 });

getArtistSimilar(artistId)

Returns a list of artists similar to a given artist.

Required Parameters:
  • artistId - The ID of the artist.
Example:
songkickApi.getArtistSimilar(253846);

searchArtists(params)

Returns a list of artists based on search string.

Required Parameters:
  • query - The searched string.
Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Example:
songkickApi.searchArtists({ query: 'Radiohead' });
songkickApi.searchArtists({ query: 'Radiohead', page: 6 });

Events API

searchEvents(params)

Returns a list of events based on search params.

Required Parameters:
  • artist_name - The name of an artist to search for.
  • location - The location of the event.

Note: Requires either artist_name or location but not both.

Optional Parameters:
  • min_date- The earliest date of events to return (YYYY-MM-DD).
  • max_date- The latest date of events to return (YYYY-MM-DD).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).

Note: If using either of the date options, both min_date and max_date are then required.

Examples:
songkickApi.searchEvents({ artist_name: 'Radiohead' });
songkickApi.searchEvents({ location: 'geo:44.9325881,-93.26754419999999' });
songkickApi.searchEvents({ location: 'sk:35130' });

getEventDetails(eventId)

Returns detailed event information, including venue information.

Required Parameters:
  • eventId - The ID of the event.
Example:
songkickApi.getEventDetails(11129128);

getEventSetlist(eventId)

Returns the setlist for a specific event.

Required Parameters:
  • eventId - The ID of the event.
Example:
songkickApi.getEventSetlist(11129128);

Location API

searchLocations(params)

Returns a list of locations based on search params.

Required Parameters:
  • query - The name of an location to search for.
  • location - The lat/lng, ip, or clientip of the location.

Note: Requires either query or location but not both.

Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.searchLocations({ query: 'New York City' });
songkickApi.searchLocations({ query: 'New York City', page: 4, per_page: 25 });
songkickApi.searchLocations({ location: 'geo:44.9325881,-93.26754419999999' });
songkickApi.searchLocations({ location: 'ip:127.0.0.1' });
songkickApi.searchLocations({ location: 'clientip:127.0.0.1' });

getLocationUpcomingEvents(metroAreaId, params)

Returns upcoming events for a metro location.

Required Parameters:
  • metroAreaId - The ID of the metro area to get upcoming events for.
Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getLocationUpcomingEvents(35130);
songkickApi.getLocationUpcomingEvents(35130, { page: 5, per_page: 25 });

User API

getUserArtistTracking(username, artistId)

Returns tracking information for a single artist a user has tracked.

Required Parameters:
  • username - The username of the user.
  • artistId - The ID of the artist.
Example:
songkickApi.getUserArtistTracking('user_123', 253846);

getUserTrackedArtists(username, params)

Returns artists the user is tracking.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • created_after- Return artists tracked after given date (ISO8601 formatted).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserTrackedArtists('user_123');
songkickApi.getUserTrackedArtists('user_123', { created_after: '2012-02-29T13:37:00Z' });
songkickApi.getUserTrackedArtists('user_123', { created_after: '2012-02-29T13:37:00Z', page: 3, per_page: 25 });

getUserMutedArtists(username, params)

Returns a list of artists the user used to track but is no longer.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • created_after- Return artists stopped tracking after given date (ISO8601 formatted).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserMutedArtists('user_123');
songkickApi.getUserMutedArtists('user_123', { created_after: '2012-02-29T13:37:00Z' });
songkickApi.getUserMutedArtists('user_123', { created_after: '2012-02-29T13:37:00Z', page: 3, per_page: 25 });

getUserTrackedMetroAreas(username, params)

Returns a list of metro areas a user is tracking.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • created_after- Return metro areas tracked after given date (ISO8601 formatted).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserTrackedMetroAreas('user_123');
songkickApi.getUserTrackedMetroAreas('user_123', { created_after: '2012-02-29T13:37:00Z' });
songkickApi.getUserTrackedMetroAreas('user_123', { created_after: '2012-02-29T13:37:00Z', page: 3, per_page: 25 });

getUserMetroAreaTracking(username, metroAreaId)

Returns a tracking object for a metro area that the user is tracking.

Required Parameters:
  • username - The username of the user.
  • metroAreaId - The ID of the metro area.
Optional Parameters:
  • created_after- Return artists stopped tracking after given date (ISO8601 formatted).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Example:
songkickApi.getUserMetroAreaTracking('user_123', 35130);

getUserEventTracking(username, eventId)

Returns a tracking object for an event the user has tracked.

Required Parameters:
  • username - The username of the user.
  • eventId - The ID of the metro area.
Example:
songkickApi.getUserEventTracking('user_123', 11129128);

getUserCalendar(username, params)

Returns a list of calendar entries with events for a user’s tracked artists in their tracked metro areas.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserCalendar('user_123');
songkickApi.getUserCalendar('user_123', { page: 3, per_page: 25 });

getUserUpcomingEvents(username, params)

Returns a list of events the user is planning to attend.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • attendance- The status of a user's event attendance. Options include 'all', 'im_going', 'i_might_go'. Defaults to 'im_going'.
  • created_after- Return artists stopped tracking after given date (ISO8601 formatted).
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserUpcomingEvents('user_123');
songkickApi.getUserUpcomingEvents('user_123', { attendance: 'all', page: 3, per_page: 25 });
songkickApi.getUserUpcomingEvents('user_123', { attendance: 'i_might_go', created_after: '2012-02-29T13:37:00Z' });

getUserPastEvents(username, params)

Returns a list of events the user has attended in the past.

Required Parameters:
  • username - The username of the user.
Optional Parameters:
  • order- The order you want the events returned in. Either 'asc' or 'desc'. Defaults is 'asc'.
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getUserPastEvents('user_123');
songkickApi.getUserPastEvents('user_123', { order: 'desc' });
songkickApi.getUserPastEvents('user_123', { order: 'desc', page: 4, per_page: 25 });

Venue API

getVenue(venueId)

Returns details about a given venue.

Required Parameters:
  • venueId - The ID of the venue.
Example:
songkickApi.getVenue(17522);

getVenueUpcomingEvents(venueId, params)

Returns upcoming events for a given venue.

Required Parameters:
  • venueId - The ID of the venue.
Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.getVenueUpcomingEvents(17522);
songkickApi.getVenueUpcomingEvents(17522, { page: 5, per_page: 10 });

searchVenues(params)

Returns a list of venues based on search params.

Required Parameters:
  • query - The searched venue string.
Optional Parameters:
  • page- The offset for paginated results (first page = 1).
  • per_page- The number of results for paginated results (max 50).
Examples:
songkickApi.searchVenues({ query: 'First Avenue' });
songkickApi.searchVenues({ query: '7th Street Entry', page: 5, per_page: 25 });

About

A full-fledged Songkick API wrapper/enhancer for Node.js.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages