mixcloud-fetch
Advanced tools
Node module for fetching Mixcloud resources.
Note: mixcloud-fetch does not support user login, so you won't be able to fetch exclusive content or access account-specific features.
npm i mixcloud-fetch --save
import mcfetch from 'mixcloud-fetch';
// Get shows matching the 'ambient' and 'lounge' tags
const shows = await mcfetch.tag(['ambient', 'lounge']).getShows();
// Search for tags matching 'jazz funk'
const tags = await mcfetch.search('jazz funk').getTags();
Here, mcfetch is the default MixcloudFetch instance exported by mixcloud-fetch. The MixcloudFetch class defines methods for accessing the underlying APIs.
MixcloudFetch#tag(slug | slug[])Returns a TagAPI instance targeting the tag given by slug, or multiple tags given by slug[].
A tag is used to discover shows and is identified by its slug. To access the Tag API, call the tag() method of a MixcloudFetch instance, passing into it the slug of the target tag.
const slug = 'jazz';
const tag = mcfetch.tag(slug);
To target multiple tags, put their slugs into an array and pass the array into tag():
const slugs = [
'jazz',
'funk'
];
const tag = mcfetch.tag(slugs);
You can then call methods provided by TagAPI.
TagAPI#getInfo()Fetches information about the target tag(s).
Returns
Promise:
null.TagAPI#getShows([params])Fetches Cloudcasts matching the target tag(s).
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
orderBy | (string) trending | popular | latest. Default: trending |
country | (string) Country code - only supported when If specified, return Cloudcasts originating from If not specified, the default value will be determined by Mixcloud. |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
null.| Property | Description |
|---|---|
items | (Array) The list of Cloudcast items fetched. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
selectedTags | (Array) The Tag items representing the target tags. |
params | (object) Sanitized version of params used to request data from Mixcloud. |
TagAPI#getFeatured([params])Fetches featured Cloudcasts matching the target tag(s).
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
orderBy | (string) popular | latest. Default: latest |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise:
null.| Property | Description |
|---|---|
items | (Array) The list of Cloudcast items fetched. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
selectedTags | (Array) The Tag items representing the target tags. |
params | (object) Sanitized version of params used to request data from Mixcloud. |
MixcloudFetch#user(username)Returns a UserAPI instance targeting the user given by username.
A user is identified by username. To access the User API, call the user() method of a MixcloudFetch instance, passing into it the username of the target user:
const username = 'jazzcat';
const user = mcfetch.user(username);
You can then call methods provided by UserAPI.
UserAPI#getInfo()Fetches information about the target user.
Returns
Promise resolving to User, or null if target user does not exist.
UserAPI#getShows([params])Fetches Cloudcasts uploaded by the target user.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
orderBy | (string) 'trending' | 'popular' | 'latest' | 'oldest'. Default: latest |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise:
null.| Property | Description |
|---|---|
items | (Array) The list of Cloudcast items fetched. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
params | (object) Sanitized version of params used to request data from Mixcloud. |
UserAPI#getPlaylists()Fetches playlists owned by the target user.
Returns
Promise:
null.UserAPI#getLiveStream()Fetches the target user's live stream.
Note: it is possible that the live stream has ended. Check the
statusproperty to ascertain.
Returns
Promise:
null.MixcloudFetch#playlist(playlistID)Returns a PlaylistAPI instance targeting the playlist given by playlistID.
A playlist is identified by its ID. To access the Playlist API, call the playlist() method of a MixcloudFetch instance, passing into it the ID of the target playlist:
const playlistId = 'UGxheWxpc3Q6MTM5NDM2MA==';
const playlist = mcfetch.playlist(playlistId);
You can then call methods provided by PlaylistAPI.
PlaylistAPI#getInfo()Fetches information about the target playlist.
Returns
Promise resolving to Playlist, or null if target playlist does not exist.
PlaylistAPI#getShows([params])Fetches Cloudcasts in the target playlist.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise:
null.| Property | Description |
|---|---|
items | (Array) The list of Cloudcast items fetched. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
MixcloudFetch#cloudcast(cloudcastID)Returns a CloudcastAPI instance targeting the Cloudcast given by cloudcastID.
A Cloudcast is identified by its ID. To access the Cloudcast API, call the cloudcast() method of a MixcloudFetch instance, passing into it the ID of the target Cloudcast:
const cloudcastId = 'Q2xvdWRjYXN0OjE1MDg0MzQzNA==';
const cloudcast = mcfetch.cloudcast(cloudcastId);
You can then call methods provided by CloudcastAPI.
CloudcastAPI#getInfo()Fetches information about the target Cloudcast.
Returns
Promise resolving to Cloudcast, or null if target Cloudcast does not exist.
MixcloudFetch#search(keywords)Returns a SearchAPI instance targeting the keywords to search for.
mixcloud-fetch supports searching Tags, Shows and Users. To access the Search API, call the search() method of a MixcloudFetch instance, passing into it the keywords you would like to search for.
const keywords = 'ambient lounge';
const search = mcfetch.search(keywords);
You can then call methods provided by SearchAPI.
SearchAPI#getTags([params])Searches for tags matching the target keywords.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise resolving to an object with the following properties:
| Property | Description |
|---|---|
items | (Array) The list of Tag items found. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
params | (object) Sanitized version of params used to request data from Mixcloud. |
SearchAPI#getShows([params])Searches for Cloudcasts matching the target keywords.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
dateUploaded | (string) pastWeek | pastMonth | pastYear | anyTime. Default: anyTime |
requireTimeStamp | (boolean) If true, only return Cloudcasts that are timestamped. Default: false |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise resolving to an object with the following properties:
| Property | Description |
|---|---|
items | (Array) The list of Cloudcast items found. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
params | (object) Sanitized version of params used to request data from Mixcloud. |
SearchAPI#getUsers([params])Searches for users matching the target keywords.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
dateJoined | (string) pastWeek | pastMonth | pastYear | anyTime. Default: anyTime |
userType | (string) uploader | listener | any. Default: any |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise resolving to an object with the following properties:
| Property | Description |
|---|---|
items | (Array) The list of User items found. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
params | (object) Sanitized version of params used to request data from Mixcloud. |
MixcloudFetch#liveStreamReturns a LiveStreamAPI isntance.
The LiveStream API allows you to fetch Mixcloud live streams.
For fetching the live stream of a user, call UserAPI#getLiveStream() instead.
LiveStreamAPI#getCurrent([params])Fetches the current live streams on Mixcloud.
Params
params: (object) (optional and all properties optional)
| Property | Description |
|---|---|
orderBy | (string) popular | mostRecent. Default: popular |
category | (string) If specified, return live streams in For the list of values you can specify, call |
limit | (number) Number of items to fetch (max: 100). Default: 20 |
pageToken | (string) Continuation token for fetching the next batch of items following the previous fetch. |
Returns
Promise resolving to an object with the following properties:
| Property | Description |
|---|---|
items | (Array) The list of LiveStream items fetched. |
nextPageToken | (string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available. To fetch the next batch of items, pass the token as |
params | (object) Sanitized version of params used to request data from Mixcloud. |
LiveStreamAPI#getCategories()Fetches the available live stream categories.
Returns
Promise resolving to an Array of strings. Each array element is the name of a live stream category.
MixcloudFetch#miscReturns a MiscAPI instance.
The Miscellaneous API provides methods for obtaining values that can be used in other API methods.
MiscAPI#getCategories()Fetches the list of Mixcloud categories. See Usage below for example of fetching Cloudcasts belonging to a specific category.
Returns
Promise resolving to a CategoryBundle. A bundle is an object with the following structure:
{
bundle1: Category[],
bundle2: Category[]
}
A Category is an object wih the following key properties:
| Property | Description |
|---|---|
name | (string) Category name |
slug | (string) Category identifier |
Usage
Say we have the following category bundle obtained from getCategories():
{
music: [
{ name: 'Ambient', slug: 'ambient' },
{ name: 'Bass', slug: 'bass' }
...
],
talk: [
{ name: 'Business', slug: 'business' },
{ name: 'Comedy', slug: 'comedy' }
...
]
}
To obtain Cloudcasts belonging to the 'Ambient' category, use its slug property in conjunction with the Tag API:
const tag = mcfetch.tag(bundle['music'][0]['slug']);
const showsInAmbientCategory = await tag.getShows();
MiscAPI#getCountries()Fetches the list of countries available on Mixcloud. See Usage below for example of fetching Cloudcasts originating from a specific country.
Returns
Promise resolving to a CountryBundle. A bundle is an object with the following properties:
| Property | Description |
|---|---|
default | (object) The default country |
available | (Array) The list of available countries |
Each Country is an object with the following properties:
| Property | Description |
|---|---|
code | (string) Country code |
name | (string) Country name |
Usage
Say we have the following countries returned by getCountries():
{
default: { code: 'HKG', name: 'Hong Kong' },
available: [
{ code: 'GLOBAL', name: 'Global' },
{ code: 'AUS', name: 'Australia' },
{ code: 'CAN', name: 'Canada' },
...
]
}
To obtain Cloudcasts matching the 'jazz' tag and originating from Canada:
const tag = mcfetch.tag('jazz');
const jazzShowsFromCanada = await tag.getShows({
country: 'CAN' // Use the country code
});
Fetch requests are rate limited by default. Rate limiting is useful when you need to make a large number of queries and don't want to run the risk of getting rejected by the server for making too many requests within a short time interval.
The library uses Bottleneck for rate limiting. You can configure the rate limiter like this:
mcfetch.limiter.setOptions({
maxConcurrent: 10, // default: 5
minTime: 100 // default: 200
});
setOptions() is just a passthrough function to Bottleneck's updateSettings(). Check the Bottleneck doc for the list of options you can set.
To check if the rate limiter is enabled:
mcfetch.limiter.isEnabled()
To disable the rate limiter:
mcfetch.limiter.setEnabled(false);
The library maintains an in-memory cache for storing results of fetch requests. You can access the cache functions as follows:
// Set the expiry time of cache entries (seconds)
mcfetch.cache.setTTL(500); // Default: 300
// Set the maximum number of entries that can be stored in the cache
// Specify a negative value (e.g -1) for unlimited entries.
mcfetch.cache.setMaxEntries(20); // Default: 10
// Clears the cache
mcfetch.cache.clear();
1.0.2
PlaylistAPI#getShows() missing params1.0.1
Playlist: fix wrong type for name property1.0.0
0.1.1:
MIT
FAQs
Node module for fetching Mixcloud resources
The npm package mixcloud-fetch receives a total of 7 weekly downloads. As such, mixcloud-fetch popularity was classified as not popular.
We found that mixcloud-fetch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket and Seal Security collaborate to fix a critical npm overrides bug, resolving a three-year security issue in the JavaScript ecosystem's most popular package manager.
Security News
TypeScript is porting its compiler to Go, delivering 10x faster builds, lower memory usage, and improved editor performance for a smoother developer experience.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.