Node module for fetching Mixcloud resources
npm install mixcloud-fetchNode 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.
#### Access method
#### MixcloudFetch#tag(slug | slug[])
Returns a TagAPI instance targeting the tag given by slug, or multiple tags given by slug[].
#### Description
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.
#### API methods
TagAPI#getInfo()
Fetches information about the target tag(s).
Returns
Promise:
- If none of the target tag(s) exist, the Promise resolves to null.
- Otherwise, the Promise resolves to an Array of Tag items. Only tags that exist will be included in the Array.
---
TagAPI#getShows([params])
Fetches Cloudcasts matching the target tag(s).
Params
params: (object) (optional and all properties optional)
| Property | Description | (string) Country code - only supported when
|---------------|---------------------------|
| orderBy | (string) trending \| popular \| latest. Default: trending |country
| | orderBy is trending.
If specified, return Cloudcasts originating from country. For the list of values you can specify, call MiscAPI#getCountries().
If not specified, the default value will be determined by Mixcloud.
| | (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
- If none of the target tag(s) exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to an object with the following properties:| 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.pageToken in the next call to this method.
| 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:
- If none of the target tag(s) exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to an object with the following properties:| 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.pageToken in the next call to this method.
| selectedTags | (Array) The Tag items representing the target tags. |
| params | (object) Sanitized version of params used to request data from Mixcloud. |---
User API
#### Access method
####
MixcloudFetch#user(username)Returns a UserAPI instance targeting the user given by
.#### Description
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
.#### API methods
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:
- If target user does not exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to an object with the following properties:| 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.pageToken in the next call to this method.
| params | (object) Sanitized version of params used to request data from Mixcloud. |---
UserAPI#getPlaylists()
Fetches playlists owned by the target user.
Returns
Promise:
- If target user does not exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to an Array of Playlist items.---
UserAPI#getLiveStream()
Fetches the target user's live stream.
> Note: it is possible that the live stream has ended. Check the
status property to ascertain.Returns
Promise:
- If there is no live stream, or target user does not exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to a LiveStream item.---
Playlist API
#### Access method
####
MixcloudFetch#playlist(playlistID)Returns a PlaylistAPI instance targeting the playlist given by
.#### Description
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
.#### API methods
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:
- If target playlist does not exist, the Promise resolves to
null.
- Otherwise, the Promise resolves to an object with the following properties:| 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.pageToken in the next call to this method.---
Cloudcast API
#### Access method
####
MixcloudFetch#cloudcast(cloudcastID)Returns a CloudcastAPI instance targeting the Cloudcast given by
.#### Description
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
.#### API methods
CloudcastAPI#getInfo()
Fetches information about the target Cloudcast.
Returns
Promise resolving to Cloudcast, or
null if target Cloudcast does not exist.---
Search API
#### Access method
####
MixcloudFetch#search(keywords)Returns a SearchAPI instance targeting the
to search for.#### Description
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
.#### API methods
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.pageToken in the next call to this method.
| 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.pageToken in the next call to this method.
| 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
| | (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.pageToken in the next call to this method.
| params | (object) Sanitized version of params used to request data from Mixcloud. |---
LiveStream API
#### Access property
####
MixcloudFetch#liveStreamReturns a LiveStreamAPI isntance.
#### Description
The LiveStream API allows you to fetch Mixcloud live streams.
#### API methods
> For fetching the live stream of a user, call UserAPI#getLiveStream() instead.
LiveStreamAPI#getCurrent([params])
Fetches the current live streams on Mixcloud.
Params
: (object) (optional and all properties optional)| Property | Description |
|---------------|---------------------------|
|
orderBy | (string) popular \| mostRecent. Default: popular |
| category | (string) If specified, return live streams in
category.For the list of values you can specify, call
getCategories() of this API. |
| 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.pageToken in the next call to this method.
| 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.
---
Miscellaneous API
#### Access property
####
MixcloudFetch#miscReturns a MiscAPI instance.
#### Description
The Miscellaneous API provides methods for obtaining values that can be used in other API methods.
#### 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 |
|-------------------|--------------------------------|
|
| (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
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 |
|-------------------|--------------------------------|
|
| (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
});
---
Rate Limiting
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
});
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);
Caching
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();
Changelog
1.0.3
- LiveStream API: fix
ignored in getCurrent()1.0.2
- Fix regression:
missing params1.0.1
-
Playlist: fix wrong type for name` property1.0.0
- Migrate to Typescript; package as ESM + CJS hybrid module
- Add support for fetching live streams
0.1.1:
- Fix fetch errors due to Mixcloud changing their GraphQL URL.
MIT