musiXplora: Structured Data Access¶

This documentation provides an overview of structured musiXplora data, that are now persistently accessible on Zenodo utilizing its DOI system. MusiXplora is a linked knowledge base for musicological and organological data developed and maintained by the Research Center DIGITAL ORGANOLOGY at Leipzig University.

Currently, the German versions are available only, but it is planned to extend this data after suitable translations were found.

Code snippets will be provided for Python, JavaScript, and Bash (cURL), in order to assist with accessing the latest available data and retrieve the desired information efficiently.

Rate Limits for Zenodo are listed here.

Available musiXplora-IDs with the corresponding latest DOIs are listed here: musiXplora-Zenodo-Dictionary.

For further questions or requests, please refer to: redaktion@musixplora.de

Version of Documentation: 0.0.1 (11 June, 2024)

Table of Contents¶

musiXplora: Structured Data Access
Table of Contents
Retrieval Example: Python
Retrieval Example: JavaScript
Retrieval Example: Bash (cURL)
Data Fields
- mxp_id
- mxp_link
- title
- birth
- death
- mentioned_first
- mentioned_last
- sectors
- names
- gender
- nationalities
- confessions
- professions
- relations
- places
- events
- sources
- images
- latest_update
- zenodo

Retrieval Example: Python¶

import re
import requests

# Retrieve Latest Dictionary Version
conceptdoi_of_dictionary = "10.5281/zenodo.11581620"
doi_link_of_dictionary = f"https://doi.org/{conceptdoi_of_dictionary}"

r = requests.get(doi_link_of_dictionary)
if r.status_code == 200:
    latest_record_id_of_dictionary = re.search(r'<meta name="citation_abstract_html_url" content="([^"]+)"', str(r.content))
    record_link = latest_record_id_of_dictionary.group(1)
    record_id = record_link.split("/")[-1]
    latest_links_json = f"https://zenodo.org/api/records/{record_id}/files/mxp_ids.json/content"

r_links = requests.get(latest_links_json)
if r_links.status_code == 200:
    mxp_to_json_links = r_links.json()

# Retrieve musiXplora Person Data
mxp_id = "a0007"
target = mxp_to_json_links[mxp_id]
r = requests.get(target)
if r.status_code == 200:
    mxp_data = r.json()

print(f"Title: {mxp_data['title']}")
print(f"Professions (Music-Related): {', '.join(mxp_data['professions']['music_related'])}")

Retrieval Example: JavaScript¶

const conceptdoiOfDictionary = "10.5281/zenodo.11581620";
const doiLinkOfDictionary = `https://doi.org/${conceptdoiOfDictionary}`;

fetch(doiLinkOfDictionary)
  .then(response => response.text())
  .then(htmlContent => {
    const latestRecordIdOfDictionary = htmlContent.match(/<meta name="citation_abstract_html_url" content="([^"]+)"/);
    if (latestRecordIdOfDictionary) {
      const recordLink = latestRecordIdOfDictionary[1];
      const recordId = recordLink.split('/').pop();
      const latestLinksJson = `https://zenodo.org/api/records/${recordId}/files/mxp_ids.json/content`;

      // Retrieve Latest Dictionary Version
      fetch(latestLinksJson)
        .then(response => response.json())
        .then(mxpToJsonLinks => {
          // Retrieve musiXplora Person Data
          const mxpId = "a0007";
          const target = mxpToJsonlLinks[mxpId];

          fetch(target)
            .then(response => response.json())
            .then(mxpData => {
              console.log(`Title: ${mxpData['title']}`);
              console.log(`Professions (Music-Related): ${mxpData['professions']['music_related'].join(', ')}`);
            });
        });
    }
  })
  .catch(error => console.error('Error:', error));

Retrieval Example: Bash (cURL)¶

#!/bin/bash

# Retrieve Latest Dictionary Version
conceptdoi_of_dictionary="10.5281/zenodo.11581620"
doi_link_of_dictionary="https://doi.org/$conceptdoi_of_dictionary"

# Fetch the page content and parse to get the latest record link
record_link=$(curl -s $doi_link_of_dictionary | grep -oP '<meta name="citation_abstract_html_url" content="\K[^"]+')
record_id="${record_link##*/}"
latest_links_json="https://zenodo.org/api/records/${record_id}/files/mxp_ids.json/content"

# Fetch the JSON links
mxp_to_json_links=$(curl -s $latest_links_json)

# Retrieve musiXplora Person Data
mxp_id="a0007"
# Extract the target URL for the specific mxp_id using jq
target=$(echo $mxp_to_json_links | jq -r ."$mxp_id")

# Fetch the target URL to get musiXplora Person Data
mxp_data=$(curl -s $target)

# Extract and print desired data using jq
title=$(echo $mxp_data | jq -r '.title')
professions=$(echo $mxx_data | jq -r '.professions.music_related | join(", ")')

echo "Title: $title"
echo "Professions (Music-Related): $professions"

Data Fields¶

`mxp_id`¶

Type: string
Description: Unique musiXplora Identifier.
Example: "mxp_id": "b1316"

`mxp_link`¶

Type: string
Description: URL that is directing to the musiXplora entry.
Example: "mxp_link": "https://musixplora.de/mxp/b1316"

`title`¶

Type: string
Description: Title of the Zenodo record, consisting of the primary name and surname with the musiXplora-ID in parentheses.
Example: "title": "Johann Sebastian Bach (b1316)"

`birth`¶

Type: array of objects
Description: Each object contains the date and place of a birth-related event specified by the attribute. This event may be, for example, the birth or baptism.
Structure:
date (str): The date of the birth-related event following ISO 8601.
place (str): The place of the birth-related event.
attribute (str): Specification of the birth-related event type (e.g., birth, baptism etc.).

Example:

[
    {
        "date": "1685-03-21",
        "place": "Eisenach",
        "attribute": "birth"
    }
]

`death`¶

Type: array of objects
Description: Each object contains the date and place of a death-related event specified by the attribute. This event may be, for example, the death or funeral.
Structure:
date (str): The date of the death-related event following ISO 8601.
place (str): The place of the death-related event.
attribute (str): Specification of the death-related event type (e.g., death, funeral etc.).

Example:

[
    {
        "date": "1750-07-28",
        "place": "Leipzig",
        "attribute": "death"
    }
]

`mentioned_first`¶

Type: string
Description: The earliest date of the earliest recorded mention of the individual.
Example: "mentioned_first": "1700-05-21"

`mentioned_last`¶

Type: string
Description: The date of the most recent recorded mention of the individual, which defaults to zeros, mostly if the date of death is known.
Example: "mentioned_last": "1749-03-11"

`sectors`¶

Type: array of strings
Description: Sectors or areas in which the individual was active or noted.
Example: "sectors": ["Chor", "Hof", "Kirche", "Schule", "Stadt"]

`names`¶

Type: array of objects
Description: List of names of the individual, including surnames, given names, pseudonyms, and any other variants, which are specified as the type. The variant_idx field specifies the sequence index of a name variant, ranking names from the most common (normative) to the least common, including names in foreign languages.
Structure:
surname (str): The surname of one person.
name (str): The name of one person.
type (str): The type of a name entry, for example, if it is the given name, pseudonym, or royal name etc.

Example:

[
    {
        "surname": "Bach",
        "name": "Johann Sebastian",
        "type": "Normansetzung",
        "variant_idx": "1"
    }
]

`gender`¶

Type: string
Description: Gender of the individual, without any abbreviation, while "non-binary" is an option.
Example: "gender": "männlich"

`nationalities`¶

Type: array of strings
Description: List of nationalities associated with the individual. This field can be empty if not clearly known.
Example: "nationalities": ["de", "it"]

`confessions`¶

Type: array of strings
Description: Religious affiliations or denominations of the individual, without any abbreviations. Multiple values are possible.
Example: "confessions": ["evangelisch-lutherisch"]

`professions`¶

Type: object -> array of strings
Description: Lists containing terms of historical, music_related and other professions. Historical professions mostly contain the exact terms that were found in literature, or those that did not fit into the controlled vocabulary of the other lists.
Structure:
historical ([str]):
music_related ([str]):
other ([str]):

Example:

{
    "historical": [
        "Capellmeister",
        "Königlich Pohlnischer und Chur Saechssischer Hoff-Compositeur",
        "Director Chori Musici Lipsiensis"
    ],
    "music_related": [
        "Komponist",
        "Organist",
        "Chorleiter",
        "Kapellmeister",
        "Klavierlehrer",
        "Cembalist",
        "Kompositionslehrer",
        "Musikpädagoge"
    ],
    "other": ["Lehrer"]
}

`relations`¶

Type: object
Description: Describes the relationships between the individual with persons or entities including media. Each relationship object includes the role of the individual, its position in relation to the other person or entity, the related musiXplora-ID, its type, and the name or all available titles of the related person or entity.\ Possible relations are listed in mXp-5001408.
Structure:
entities ([object]):
persons ([object]):
Relation Object Structure:
role (str): The role of one person in relation to another or an entity.
position (str): Position of one person in relation to another or an entity, either "major" or "minor".
related_mxp_id (str): musiXplora-ID of the related person or entity.
related_type (str): Entities only. Type of an entity, for example, if its a title, an institution, an object or something else.
related_titles ([str]): Available titles of the related entity or the primary name of a person.

Example:

{
    "entities": [
        {
            "role": "ParentEntity",
            "position": "major",
            "related_mxp_id": "3010598",
            "related_type": "Institutionen",
            "related_titles": ["Thomasschule zu Leipzig", "Schola Thomana"]
        },
        {
            "role": "Komponist",
            "position": "major",
            "related_mxp_id": "5001102",
            "related_type": "Titel/Medien",
            "related_titles": [
                "Willst Du dein Herz mir schenken. Aria di Giovannini. BWV 518. aus dem Notenbüchlein der Anna Magdalena Bach. Nr. 37"
            ]
        }
    ],
    "persons": [
        {
                "role": "Schwiegersohn",
                "position": "minor",
                "related_mxp_id": "b1315",
                "related_title": [
                    "Johann Michael Bach (b1315)"
                ],
                "group": "Schwiegereltern",
                "class": "Schwägerschaft",
                "category": "Netzwerke"
        },
        {
                "role": "Widmungsempfänger",
                "position": "major",
                "related_mxp_id": "m0772",
                "related_title": [
                    "Lorenz Christoph Mizler von Kolof (m0772)"
                ],
                "group": "WidmungsempfängerInnen",
                "class": "Widmung",
                "category": "Werkbeziehungen"
        }
    ]
}

`places`¶

Type: array of objects
Description: Each object represents a geographical location associated with the individual, containing details about the normative name, attribute, place terminology, hierarchy and coordinates. The encoded information is based on musiXplora: LOCI.
Structure:
name (str: The normative name of the place.
attribute (str): Attribute of the place (e.g., place of birth, place of activity, main place of activity etc.).
term (str): Defines the type of geographical unit (e.g., city, town, market etc.).
hierarchy (str): Specifies the classification scheme used to prioritize or standardize place names, mostly for musiXplora-internal use cases.
x (str): The latitude of the location. Partially incomplete.
y (str): The longitude of the location. Partially incomplete.
zoom (str): Zoom level for maps, typically set to show detailed or broad views depending on context. Partially incomplete.

Example:

{
    "name": "Eisenach",
    "attribute": "Geburtsort",
    "term": "Ortsgemeinde",
    "hierarchy": "Normansetzung",
    "x": "49.851667",
    "y": "6.508889",
    "zoom": "0"
},
{
    "name": "Arnstadt",
    "attribute": "Wirkungsort",
    "term": "Stadt",
    "hierarchy": "BMLO Vorzugsansetzung",
    "x": "50.825889",
    "y": "10.802939",
    "zoom": "0"
}

`events`¶

Type: object
Description: Each key within this object groups different types of events associated with the individual. These events are categorized into several specific areas such as documentation, personal events, production activities, provenance details, public appearances, and other miscellaneous events. Each category may contain arrays of event objects detailing specific activities or occurrences.
Structure:
documentation (object): Groups events related to the documenting of activities including analysis, archival work, digital formats, and other documentation types.
- analysis ([object]): Specific instances of analytical, mostly object-analytical work.
- archival ([object]): Events involving archival activities, especially museal activities regarding the inventory.
- digital ([object]): Digital documentation, digitization and virtualization processes.
- other ([object]): Other types of documentation not categorized above.
modification ([object]): Modifications or changes made, detailed by specific events.
personal (object): Personal events subdivided by type such as communication, education, institutions, and places.
- communication ([object]): Details the instances of communications such as letters, emails, or other correspondence related to the individual.
- education ([object]): Lists educational events, including schooling, lectures, workshops, and other formative experiences.
- institution ([object]): Captures the individual's interactions with institutions, such as employment, memberships, or other formal associations.
- places ([object]): Specifies location-dependent events, mostly associated with personal events like visits or person relocations.
production (object): Production-related activities, separated into media production and object creation.
- media ([object]): Contains details about media productions involving the individual, such as compositions, digital twins, recordings, photographies, prints, editions or technical drawings.
- object ([object]): Describes objects that the individual has manufactured, produced or been significantly involved with, including inventions, replica and conceptual works.
provenance (object): The history of ownership and transfer of items, including acquisition, loss, and transfer events.
- acquisition ([object]): Documents the acquisition of items by the individual, whether purchased, gifted, confiscated or otherwise obtained.
- loss ([object]): Notes instances where an object was generally lost completely or partially, either via war damages or other reasons of losses.
- transfer ([object]): Records the transfer of complete or partial items from the individual to other parties, which can be sales, donations, confiscations, consor inheritances, repatriations and more.
public (object): Public appearances or events, categorized into concerts, exhibitions, and presentations.
- concert ([object]): Details performances in which the individual participated or which they organized, highlighting key concerts, including premieres.
- exhibition ([object]): Describes exhibitions that the individual curated or in which their work or related items were featured, including opening events.
- presentation ([object]): Lists presentations given by or involving the individual, including talks, seminars, and public lectures.
other ([object]): Miscellaneous events not categorized in other sections.
Event Object Structure:
mxp_id (str): Unique musiXplora Identifier.
type (str): Type of the event.
role (str): Role of the person in the event.
place (str): Place where the event occurred or is associated with.
date_earliest (str): Earliest date (ISO 8601) of the event.
date_earliest_attr (str): Additional attribute to the earliest date, either "circa", "after" or "before".
date_latest (str): Latest date (ISO 8601) of the event.
date_latest_attr (str): Additional attribute to the latest date, either "circa", "after" or "before".
related (object): Contains classes of persons or entities related to the event.
- events ([object]): Other events that are related to the event object.
- institutions ([object]): Institutions related to the event object.
- items ([object]): Items/Information related to the event object, in the sense of musiXplora: RES.
- media ([object]): Titles and Media related to the event object.
- objects/works ([object]): Objects and physical works related to the event object.
- persons ([object]): Other persons related to the event object.
- places ([object]): Places and locations related to the event object.
latest_update (str): Date (ISO 8601) of latest event data update at musiXplora.
Related Object Structure:
mxp_id (str): Unique musiXplora Identifier of the related entity.
title (str): Title of the related entity.
descriptions ([str]): List of strings resulting in a description of the related entity.
Example:
```
                               
```
href="#__codelineno-9-1">"documentation": { "analysis": [], "archival": [ { "mxp_id": "6022019", "type": "Begutachtung", "role": "Gutachter", "place": "Leipzig", "date_earliest": "1744-00-00", "date_earliest_attr": "circa", "date_latest": "0000-00-00", "date_latest_attr": "", "related": { "objects/works": [ { "mxp_id": "4010262", "title": "Spieltisch der Leipziger Spitalkirche", "descriptions": [] } ], "persons": [ { "mxp_id": "h2962", "title": "Zacharias Hildebrandt (h2962)", "descriptions": [] } ] }, "latest_update": "2023-12-30" } ] }

`sources`¶

Type: object
Description: Organizes various types of source information and external identifiers relevant to the data. This comprehensive structure allows for detailed citation of different types of resources such as internal databases, authoritative registries, bibliographic entries, biographical details, catalog data, and media contents, each categorized into specific arrays of objects.
Structure:
mxp_internal ([object]): Contains sources internal to musiXplora, detailing more specific data or metadata.
- title (str): Title of the source.
- source_idx (str): Index or identifier within musiXplora's internal source system.
authorities ([object]): Official databases or registries recognized as authoritative sources for factual and standardized information.
bibliographies ([object]): Collections of bibliographic entries related to the subject matter.
biographies ([object]): Detailed accounts and biographies of individuals or entities relevant to the data.
catalogs ([object]): Listings or catalog entries that provide organizational and classification details.
collections ([object]): Assembles grouped items or documents related to specific subjects or themes.
literature ([object]): Scholarly works and other literary sources that provide context or analysis.
media ([object]): Audiovisual materials, digitized and digitally archived media relevant to the data.
topographies ([object]): Geographic and demographical data sources that offer locational insights.
Source Object Structure:
name (str): Name or title of the source,.
type (str): Category or nature of the source (e.g., biography, bibliography).
link (str): URL or web link to the source, providing direct access for further details, requests or queries.

Example:

"authorities": [
    {
        "name": "Normdatei der Spanischen Nationalbibliothek",
        "type": "Normdateien",
        "link": "http://datos.bne.es/resource/XX992838"
    },
    {
        "name": "International Standard Name Identifier",
        "type": "Normdateien",
        "link": "http://isni.oclc.nl/DB=1.2/PPN=122764157/PPNSET"
    }
],
"bibliographies": [
    {
        "name": "Bibliographie des Musikschrifttums Online",
        "type": "Bibliographien",
        "link": "http://www.musikbibliographie.de/ACT=SRCHA/IKT=8549/TRM=2225131/CMD"
    },
    {
        "name": "Choral Public Domain Library",
        "type": "Bibliographien",
        "link": "http://www3.cpdl.org/wiki?curid=10744"
    }
],
"biographies": [
    {
        "name": "Anton Bruckner-Lexikon online",
        "type": "Biographien/Karrieren",
        "link": "http://www.bruckner-online.at/?page_id=1433&id=d1e273"
    },
    {
        "name": "Bach Digital",
        "type": "Biographien/Karrieren",
        "link": "https://www.bach-digital.de/receive/BachDigitalPerson_agent_00000809"
    }
],
"collections": [
    {
        "name": "Forschungsbibliothek Gotha der Universität Erfurt – Handschriften",
        "type": "Archive, Museen, Sammlungen, Nachlässe",
        "link": "http://pergamon.uni-erfurt.de/cgi-bin/gotha/hans.pl?t_idn=zka:p4052"
    },
    {
        "name": "International Music Score Library Project",
        "type": "Archive, Museen, Sammlungen, Nachlässe",
        "link": "http://imslp.org/?curid=1452"
    }
]

`images`¶

Type: object
Description: This contains links to images that are publicly accessible, currently utilizing Wikimedia only.
Structure:
other ([object]): Other image sources.
wikimedia ([object]): Wikimedia image sources.
- source (str): Definition of the Wikimedia source.
- link (str): Direct URL to the image file.

Example:

"images": {
    "other": [],
    "wikimedia": [
        {
            "source": "Wikimedia Commons",
            "link": "https://upload.wikimedia.org/wikipedia/commons/6/6a/Johann_Sebastian_Bach.jpg"
        }
    ]
}

`latest_update`¶

Type: string
Description: Date (ISO 8601) of the latest data update at musiXplora.
Example: "latest_update": "2015-08-12"

`zenodo`¶

Type: object
Description: This represents a structured object detailing the Zenodo record versions associated with the dataset of a person or entity. Zenodo is an open-access repository developed under the European OpenAIRE program and operated by CERN. It is used to share and preserve research outputs across all fields of science. This field captures detailed versioning information, changes, and publication specifics for each record, using a structured format that leverages semantic versioning to track iterations of data or documents stored within.
Structure:
versions (object): Contains available versions of Zenodo records.
- version (object): Defines the version of the Zenodo record using Semantic Versioning.
Version Object Structure:
changelog (str): Changelog of the Zenodo record version.
date (str): Publishing date (ISO 8601) of the Zenodo record version.
description (str): Zenodo description of the version including HTML. This might get updated even if the version itself did not change, but not in case the data implemented in the description was changed.
doi (str): Digital Object Identifier (DOI) of the version.
languages ([str]): List of affected or introduced languages using language codes (ISO 639).

Example:

"zenodo": {
    "versions": {
        "0.0.1": {
            "changelog": "Initial Upload.",
            "date": "2024-06-07",
            "description": "<u>Name</u>: Johann Sebastian Bach<br><u>musiXplora-ID</u>: b1316<br><u>musiXplora-URI</u>: <a href=\"https://musixplora.de/mxp/b1316\">https://musixplora.de/mxp/b1316</a><br>[...]",
            "doi": "10.5281/zenodo.11252259",
            "languages": [
                "de"
            ]
        }
    }
}

musiXplora: Structured Data Access¶

Table of Contents¶

Retrieval Example: Python¶

Retrieval Example: JavaScript¶

Retrieval Example: Bash (cURL)¶

Data Fields¶

mxp_id¶

mxp_link¶

title¶

birth¶

death¶

mentioned_first¶

mentioned_last¶

sectors¶

names¶

gender¶

nationalities¶

confessions¶

professions¶

relations¶

places¶

events¶

sources¶

images¶

latest_update¶

zenodo¶

`mxp_id`¶

`mxp_link`¶

`title`¶

`birth`¶

`death`¶

`mentioned_first`¶

`mentioned_last`¶

`sectors`¶

`names`¶

`gender`¶

`nationalities`¶

`confessions`¶

`professions`¶

`relations`¶

`places`¶

`events`¶

`sources`¶

`images`¶

`latest_update`¶

`zenodo`¶