mixcloud-fetch

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.

Installation

npm i mixcloud-fetch --save

Usage

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.

Tag API

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

Example ➔ Output

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.

Example ➔ Output

Params

params: (object) (optional and all properties optional)

| Property | Description | |---------------|---------------------------| | orderBy | (string) trending | popular | latest. Default: trending | | country | (string) Country code - only supported when 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. | | 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

• 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. |

Example ➔ Output

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 username.

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 UserAPI.

API methods

Example ➔ Output

Returns

Promise resolving to User, or null if target user does not exist.

Example ➔ Output

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. |

Example ➔ Output

Returns

Promise:

• If target user does not exist, the Promise resolves to null.
• Otherwise, the Promise resolves to an Array of Playlist items.

Example ➔ Output

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 playlistID.

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 PlaylistAPI.

API methods

Example ➔ Output

Returns

Promise resolving to Playlist, or null if target playlist does not exist.

Example ➔ Output

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 cloudcastID.

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 CloudcastAPI.

API methods

Example ➔ Output

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 keywords 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 SearchAPI.

API methods

Example ➔ Output

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. |

Example ➔ Output

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. |

Example ➔ Output

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.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#liveStream

Returns 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.

Example ➔ Output

Params

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. |

Example ➔ Output

Returns

Promise resolving to an Array of strings. Each array element is the name of a live stream category.

Miscellaneous API

Access property

MixcloudFetch#misc

Returns a MiscAPI instance.

Description

The Miscellaneous API provides methods for obtaining values that can be used in other API methods.

API methods

Example ➔ Output

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(); 

Example ➔ Output

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
});

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
});

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);

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 pageToken ignored in getCurrent()

1.0.2

• Fix regression: PlaylistAPI#getShows() missing params

1.0.1

• Playlist: fix wrong type for name property

1.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.

License

MIT