imslp-api

Access composer and work data directly from the IMSLP API. JSON is stored in an array of objects for convenience.

Stats

StarsIssuesVersionUpdatedCreatedSize
imslp-api
1012.0.3a year ago2 years agoMinified + gzip package size for imslp-api in KB

Readme

npm version GitHub release Github all releases Maintenance GitHub issues Node.js CI

IMSLP API

Get data from the IMSLP API without having to deal with their horrible JSON format yourself! Get easy access to a massive list of composers and works, along with all the linked metadata and links related to them.

Information

The International Music Score Library Project, also known as the Petrucci Music Library after publisher Ottaviano Petrucci, is a subscription-based project for the creation of a virtual library of public-domain music scores.
As of May 21, 2020 at 9:46 AM Eastern Standard Time, ISMLP stands at an index of:
159,144 works · 18,825 composers · 539 performers
515,993 scores · 10,474,167+ pages · 61,121 recordings

Tutorial

GET Composers

To get the JSON list of composers, you need to run the composers(<start>, <amount>) function.
Note that amount should stay a relatively reasonable number due to JavaScript's throttling.
Example:

// Import API
const api = require("imslp-api");

// GET Composers
// Here are two examples
api.composers(6, 1);
// This will return index 6 on the list
api.composers(0, 2);
// This will return 2 composers starting from index 0

Let's take a look at what api.composers(1, 5) returns:

[
  {
    id: "Category:A",
    name: "A",
    link: "https://imslp.org/wiki/Category:A",
  },
  {
    id: "Category:A Far Cry",
    name: "A Far Cry",
    link: "https://imslp.org/wiki/Category:A_Far_Cry",
  },
  {
    id: "Category:.q, Wulfi",
    name: ".q, Wulfi",
    link: "https://imslp.org/wiki/Category:.q,_Wulfi",
  },
  {
    id: "Category:(van Luiken) Bakker, Jeroen",
    name: "(van Luiken) Bakker, Jeroen",
    link: "https://imslp.org/wiki/Category:(van_Luiken)_Bakker,_Jeroen",
  },
  {
    id: "Category:A Fary Cry",
    name: "A Fary Cry",
    link: "https://imslp.org/wiki/Category:A_Fary_Cry",
  },
];

GET Works

To get the JSON list of works, you need to run the works(<start>, <amount>) function.
Note that amount should stay a relatively reasonable number due to JavaScript's throttling.
Example:

// Import API
const api = require("imslp-api");

// GET Works
// Here are two examples
api.works(4, 1);
// This will return index 4 on the list
api.works(8, 3);
// This will return 2 works starting from index 8

Let's take a look at what api.works(8, 3) returns:

[
  {
    id: "'A calamita (Von Calged, Kosta)",
    composer: "Von Calged, Kosta",
    title: "'A calamita",
    links: {
      work: "https://imslp.org/wiki/'A_calamita_(Von_Calged,_Kosta)",
      composer: "https://imslp.org/wiki/Category:Von_Calged,_Kosta",
    },
  },
  {
    id: "'A calamita (Von Calged, Kosta)",
    composer: "Von Calged, Kosta",
    title: "'A calamita",
    links: {
      work: "https://imslp.org/wiki/'A_calamita_(Von_Calged,_Kosta)",
      composer: "https://imslp.org/wiki/Category:Von_Calged,_Kosta",
    },
  },
  {
    id: "'A calamita (Von Calged, Kosta)",
    composer: "Von Calged, Kosta",
    title: "'A calamita",
    links: {
      work: "https://imslp.org/wiki/'A_calamita_(Von_Calged,_Kosta)",
      composer: "https://imslp.org/wiki/Category:Von_Calged,_Kosta",
    },
  },
];

API Structure

The following tables contain the tags for the API and Package JSON.
API Object ID is the ID corresponding to certain information served directly from ISMLP. You'll probably never have to use it, unless you're trying to tweak this package.
Package Object ID is the ID corresponding to the information that the package will return to you based on the function you're using. You can check what kind of data they return in the return codeembeds up in the GET Works section.
Use / Value is the description of what the data is used for in the API.

Composers

API Object ID Package Object ID Use / Value
data.id id Category name of the composer.
Used in the IMSLP link.
data.type - Type of the data. Can be either composer
or work. (1 and 2 respectively)
data.parent - Parent of the composer category.
Is empty.
data.intvals - Extra data, only used in works.
Is empty.
data.permlink link Link to the composer category.

Works

API Object ID Package Object ID Use / Value
data.id id Category name of the work.
Used in the IMSLP link.
data.type - Type of the data. Can be either composer
or work. (1 and 2 respectively)
data.parent composer Parent of the composer category.
Is empty.
data.intvals links.<work/composer> Subcategory containing work name and
composer name in the API.
Contains links in the package.
data.permlink - Link to the composer category.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.