songkick-api-node
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;songkickApi;songkickApi;
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;songkickApi;songkickApi;
getArtistSimilar(artistId)
Returns a list of artists similar to a given artist.
Required Parameters:
artistId
- The ID of the artist.
Example:
songkickApi;
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;songkickApi;
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;songkickApi;songkickApi;
getEventDetails(eventId)
Returns detailed event information, including venue information.
Required Parameters:
eventId
- The ID of the event.
Example:
songkickApi;
getEventSetlist(eventId)
Returns the setlist for a specific event.
Required Parameters:
eventId
- The ID of the event.
Example:
songkickApi;
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;songkickApi;songkickApi;songkickApi;songkickApi;
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;songkickApi;
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;
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;songkickApi;songkickApi;
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;songkickApi;songkickApi;
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;songkickApi;songkickApi;
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;
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;
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;songkickApi;
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;songkickApi;songkickApi;
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;songkickApi;songkickApi;
Venue API
getVenue(venueId)
Returns details about a given venue.
Required Parameters:
venueId
- The ID of the venue.
Example:
songkickApi;
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;songkickApi;
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;songkickApi;