mixcloud-fetch v1.0.3

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)

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:

Example ➔ Output

Params

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

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:

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)

Returns

Promise:

• If target user does not exist, the Promise resolves to null.
• Otherwise, the Promise resolves to an object with the following properties:

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)

Returns

Promise:

• If target playlist does not exist, the Promise resolves to null.
• Otherwise, the Promise resolves to an object with the following properties:

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)

Returns

Promise resolving to an object with the following properties:

Example ➔ Output

Params

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

Returns

Promise resolving to an object with the following properties:

Example ➔ Output

Params

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

Returns

Promise resolving to an object with the following properties:

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)

Returns

Promise resolving to an object with the following properties:

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:

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:

Each Country is an object with the following properties:

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