Difference between revisions of "Using the Open Opus API"

From Open Opus
Jump to navigation Jump to search
Line 1: Line 1:
The Open Opus API is a very straightforward RESTful web service which returns data in JSON format. It's completely free to use and it requires no registration at all. You can use it in any website, HTTPS or not - but we strongly suggest you to serve your web app over HTTPS. You also can use the Open Opus API in any non-web application.  
+
The Open Opus API is a very straightforward RESTful web service which returns data in JSON format. It's completely free to use and it requires no registration at all. You can use it in any website, HTTPS or not - but we strongly suggest you to serve your web app over HTTPS. You can also use the Open Opus API in any non-web application.  
  
 
== Base URI ==
 
== Base URI ==

Revision as of 16:13, 10 November 2019

The Open Opus API is a very straightforward RESTful web service which returns data in JSON format. It's completely free to use and it requires no registration at all. You can use it in any website, HTTPS or not - but we strongly suggest you to serve your web app over HTTPS. You can also use the Open Opus API in any non-web application.

Base URI

All endpoints begin with

https://api.openopus.org

Endpoints

The Open Opus API has four main endpoint groups: composers, genres, works and performers.

Composers

List popular composers

GET /composer/list/pop.json

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 23,
        "processingtime": 0.0017228126525878906,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "pop",
        "item": "1"
    },
    "composers": [
        {
            "id": "87",
            "name": "Bach",
            "complete_name": "Johann Sebastian Bach",
            "birth": "1685-01-01",
            "death": "1750-01-01",
            "epoch": "Baroque",
            "portrait": "https://assets.openopus.org/portraits/12091447-1568084857.jpg"
        },
        {
            "id": "145",
            "name": "Beethoven",
            "complete_name": "Ludwig van Beethoven",
            "birth": "1770-01-01",
            "death": "1827-01-01",
            "epoch": "Early Romantic",
            "portrait": "https://assets.openopus.org/portraits/55910756-1568084860.jpg"
        }
    ]
}

List essential composers

GET /composer/list/rec.json

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 77,
        "processingtime": 0.0025510787963867188,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "rec",
        "item": "1"
    },
    "composers": [
        {
            "id": "149",
            "name": "Adams",
            "complete_name": "John Adams",
            "birth": "1947-01-01",
            "death": null,
            "epoch": "21st Century",
            "portrait": "https://assets.openopus.org/portraits/74462091-1568084854.jpg"
        },
        {
            "id": "87",
            "name": "Bach",
            "complete_name": "Johann Sebastian Bach",
            "birth": "1685-01-01",
            "death": "1750-01-01",
            "epoch": "Baroque",
            "portrait": "https://assets.openopus.org/portraits/12091447-1568084857.jpg"
        }
    ]
}

List composers by first letter

GET /composer/list/name/a.json

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 6,
        "processingtime": 0.0013890266418457031,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "name",
        "item": "a"
    },
    "composers": [
        {
            "id": "149",
            "name": "Adams",
            "complete_name": "John Adams",
            "birth": "1947-01-01",
            "death": null,
            "epoch": "21st Century",
            "portrait": "https://assets.openopus.org/portraits/74462091-1568084854.jpg"
        },
        {
            "id": "130",
            "name": "Adès",
            "complete_name": "Thomas Adès",
            "birth": "1971-01-01",
            "death": null,
            "epoch": "21st Century",
            "portrait": "https://assets.openopus.org/portraits/31194505-1568084855.jpg"
        }
    ]
}

List composers by period

GET /composer/list/epoch/Early Romantic.json

Options are:

  • Medieval
  • Renaissance
  • Baroque
  • Classical
  • Early Romantic
  • Romantic
  • Late Romantic
  • 20th Century
  • Post-War
  • 21st Century

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 13,
        "processingtime": 0.0015330314636230469,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "epoch",
        "item": "Early Romantic"
    },
    "composers": [
        {
            "id": "145",
            "name": "Beethoven",
            "complete_name": "Ludwig van Beethoven",
            "birth": "1770-01-01",
            "death": "1827-01-01",
            "epoch": "Early Romantic",
            "portrait": "https://assets.openopus.org/portraits/55910756-1568084860.jpg"
        },
        {
            "id": "51",
            "name": "Bellini",
            "complete_name": "Vincenzo Bellini",
            "birth": "1801-01-01",
            "death": "1835-01-01",
            "epoch": "Early Romantic",
            "portrait": "https://assets.openopus.org/portraits/47933748-1568084861.jpg"
        }
    ]
}

Search composers by name

GET /composer/list/search/bruc.json

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 2,
        "processingtime": 0.002309083938598633,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "search",
        "item": "bruc"
    },
    "composers": [
        {
            "id": "184",
            "name": "Bruch",
            "complete_name": "Max Bruch",
            "birth": "1838-01-01",
            "death": "1920-01-01",
            "epoch": "Romantic",
            "portrait": "https://assets.openopus.org/portraits/32995254-1568084867.jpg"
        },
        {
            "id": "2",
            "name": "Bruckner",
            "complete_name": "Anton Bruckner",
            "birth": "1824-01-01",
            "death": "1896-01-01",
            "epoch": "Romantic",
            "portrait": "https://assets.openopus.org/portraits/25478484-1568084868.jpg"
        }
    ]
}

List composers by ID

GET /composer/list/ids/186,52.json

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 2,
        "processingtime": 0.0011899471282958984,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "ids",
        "item": "186,52"
    },
    "composers": [
        {
            "id": "52",
            "name": "Nielsen",
            "complete_name": "Carl Nielsen",
            "birth": "1865-01-01",
            "death": "1931-01-01",
            "epoch": "Late Romantic",
            "portrait": "https://assets.openopus.org/portraits/94573742-1568084926.jpg"
        },
        {
            "id": "186",
            "name": "Sibelius",
            "complete_name": "Jean Sibelius",
            "birth": "1865-01-01",
            "death": "1957-01-01",
            "epoch": "Late Romantic",
            "portrait": "https://assets.openopus.org/portraits/56825570-1568084947.jpg"
        }
    ]
}

Genres

List genres by composer ID

GET /genre/list/composer/2.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 6,
        "processingtime": 0.002276897430419922,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "composer": {
        "id": "2",
        "name": "Bruckner",
        "epoch": "Romantic",
        "complete_name": "Anton Bruckner",
        "birth": "1824-01-01",
        "death": "1896-01-01",
        "portrait": "https://assets.openopus.org/portraits/25478484-1568084868.jpg"
    },
    "genres": [
        "Popular",
        "Recommended",
        "Chamber",
        "Keyboard",
        "Orchestral",
        "Vocal"
    ]
}

Works

List works by composer ID

GET /work/list/composer/129/genre/all.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 160,
        "processingtime": 0.004470109939575195,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "all"
    },
    "composer": {
        "id": "129",
        "name": "Schumann",
        "epoch": "Romantic",
        "birth": "1810-01-01",
        "death": "1856-01-01",
        "complete_name": "Robert Schumann",
        "portrait": "https://assets.openopus.org/portraits/25233320-1568084946.jpg"
    },
    "works": [
        {
            "title": "Carnaval, op. 9",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "1",
            "id": "15091",
            "genre": "Keyboard"
        },
        {
            "title": "Cello Concerto in A minor, op. 129",
            "subtitle": "",
            "searchterms": "",
            "popular": "0",
            "recommended": "1",
            "id": "15105",
            "genre": "Orchestral"
        }
    ]
}

List popular works by composer ID

GET /work/list/composer/129/genre/Popular.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 10,
        "processingtime": 0.0015871524810791016,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "Popular"
    },
    "composer": {
        "id": "129",
        "name": "Schumann",
        "epoch": "Romantic",
        "birth": "1810-01-01",
        "death": "1856-01-01",
        "complete_name": "Robert Schumann",
        "portrait": "https://assets.openopus.org/portraits/25233320-1568084946.jpg"
    },
    "works": [
        {
            "title": "Piano Quintet in E flat major, op. 44",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "1",
            "id": "15111",
            "genre": "Chamber"
        },
        {
            "title": "Arabesque, op. 18",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "0",
            "id": "15138",
            "genre": "Keyboard"
        }
    ]
}

List essential works by composer ID

GET /work/list/composer/129/genre/Recommended.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 17,
        "processingtime": 0.002140045166015625,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "Recommended"
    },
    "composer": {
        "id": "129",
        "name": "Schumann",
        "epoch": "Romantic",
        "birth": "1810-01-01",
        "death": "1856-01-01",
        "complete_name": "Robert Schumann",
        "portrait": "https://assets.openopus.org/portraits/25233320-1568084946.jpg"
    },
    "works": [
        {
            "title": "Piano Quartet in E flat major, op. 47",
            "subtitle": "",
            "searchterms": "",
            "popular": "0",
            "recommended": "1",
            "id": "15062",
            "genre": "Chamber"
        },
        {
            "title": "Piano Quintet in E flat major, op. 44",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "1",
            "id": "15111",
            "genre": "Chamber"
        }
    ]
}

List works by composer ID and genre

GET /work/list/composer/2/Orchestral.json

Options are:

  • Chamber
  • Keyboard
  • Orchestral
  • Stage
  • Vocal

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 13,
        "processingtime": 0.0018169879913330078,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "Orchestral"
    },
    "composer": {
        "id": "2",
        "name": "Bruckner",
        "epoch": "Romantic",
        "birth": "1824-01-01",
        "death": "1896-01-01",
        "complete_name": "Anton Bruckner",
        "portrait": "https://assets.openopus.org/portraits/25478484-1568084868.jpg"
    },
    "works": [
        {
            "title": "Symphony no. 4 in E flat major, WAB 104, \"Romantic\"",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "1",
            "id": "27",
            "genre": "Orchestral"
        },
        {
            "title": "Symphony no. 5 in B flat major, WAB 105",
            "subtitle": "",
            "searchterms": "",
            "popular": "0",
            "recommended": "1",
            "id": "68",
            "genre": "Orchestral"
        }
    ]
}

Search works by composer ID and title

GET /work/list/composer/196/genre/all/search/Sonata.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 81,
        "processingtime": 0.01688218116760254,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "all",
        "search": "Sonata"
    },
    "composer": {
        "id": "196",
        "name": "Mozart",
        "epoch": "Classical",
        "birth": "1756-01-01",
        "death": "1791-01-01",
        "complete_name": "Wolfgang Amadeus Mozart",
        "portrait": "https://assets.openopus.org/portraits/21459195-1568084925.jpg"
    },
    "works": [
        {
            "title": "Piano Sonata no. 11 in A major, K.331, \"Alla turca\"",
            "subtitle": "",
            "searchterms": "",
            "popular": "1",
            "recommended": "1",
            "id": "23512",
            "genre": "Keyboard"
        },
        {
            "title": "Violin Sonata no. 21 in E minor, K.304",
            "subtitle": "",
            "searchterms": "",
            "popular": "0",
            "recommended": "1",
            "id": "23563",
            "genre": "Chamber"
        }
    ]
}

Search works by composer ID, genre and title

GET /work/list/composer/145/genre/Chamber/search/Cello Sonata.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 6,
        "processingtime": 0.006963014602661133,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "genre",
        "item": "Chamber",
        "search": "Cello Sonata"
    },
    "composer": {
        "id": "145",
        "name": "Beethoven",
        "epoch": "Early Romantic",
        "birth": "1770-01-01",
        "death": "1827-01-01",
        "complete_name": "Ludwig van Beethoven",
        "portrait": "https://assets.openopus.org/portraits/55910756-1568084860.jpg"
    },
    "works": [
        {
            "title": "Cello Sonata no. 4 in C major, op. 102, no. 1",
            "subtitle": "",
            "searchterms": "",
            "popular": "0",
            "recommended": "1",
            "id": "16300",
            "genre": "Chamber"
        },
        {
            "title": "Cello Sonata in E flat major, op. 64",
            "subtitle": "Version for cello and piano of the String Trio, op. 3 (tr. unknown)",
            "searchterms": "",
            "popular": "0",
            "recommended": "0",
            "id": "16429",
            "genre": "Chamber"
        }
    ]
}

Detail work by ID

GET /work/detail/15076.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "processingtime": 0.0012171268463134766,
        "api": "Open Opus-cache",
        "version": "1.19.10"
    },
    "composer": {
        "id": "129",
        "name": "Schumann",
        "complete_name": "Robert Schumann",
        "epoch": "Romantic"
    },
    "work": {
        "genre": "Keyboard",
        "title": "Fantasy in C major, op. 17",
        "subtitle": "",
        "searchterms": [
            "op 17"
        ],
        "id": "15076",
        "searchmode": "catalogue",
        "catalogue": "op",
        "catalogue_number": "17"
    }
}

List works by ID

GET /work/list/ids/15076,24963.json

Response:

{
    "status": {
        "success": "true",
        "source": "db",
        "rows": 2,
        "processingtime": 0.0019631385803222656,
        "api": "Open Opus-dyn",
        "version": "1.19.10"
    },
    "request": {
        "type": "ids",
        "item": "15076,24963"
    },
    "works": {
        "w:15076": {
            "composer": {
                "id": "129",
                "name": "Schumann",
                "complete_name": "Robert Schumann",
                "epoch": "Romantic"
            },
            "id": "15076",
            "title": "Fantasy in C major, op. 17",
            "subtitle": "",
            "genre": "Keyboard"
        },
        "w:24963": {
            "composer": {
                "id": "202",
                "name": "Poulenc",
                "complete_name": "Francis Poulenc",
                "epoch": "20th Century"
            },
            "id": "24963",
            "title": "Concerto in G minor for Organ, Strings, and Timpani, FP93",
            "subtitle": "",
            "genre": "Orchestral"
        }
    },
    "abstract": {
        "composers": {
            "portraits": [
                "https://assets.openopus.org/portraits/25233320-1568084946.jpg",
                "https://assets.openopus.org/portraits/94859063-1568084931.jpg"
            ],
            "names": [
                "Schumann",
                "Poulenc"
            ],
            "rows": 2
        },
        "works": {
            "rows": 2
        }
    }
}

Performers

List roles by names

POST /dyn/performer/list

Header:

names ["Herbert von Karajan", "Sviatoslav Richter", "Berliner Philharmoniker"]

Response:

{
    "status": {
        "version": "1.19.10",
        "success": "true",
        "source": "db",
        "rows": 3,
        "processingtime": 0.0017321109771728516,
        "api": "Open Opus-dyn"
    },
    "request": {
        "type": "names",
        "item": [
            "Herbert von Karajan",
            "Sviatoslav Richter",
            "Berliner Philharmoniker"
        ]
    },
    "performers": {
        "readable": [
            {
                "name": "Herbert von Karajan",
                "role": "Conductor"
            },
            {
                "name": "Sviatoslav Richter",
                "role": "Piano"
            },
            {
                "name": "Berliner Philharmoniker",
                "role": "Orchestra"
            }
        ],
        "digest": {
            "herbert-von-karajan": "Conductor",
            "sviatoslav-richter": "Piano",
            "berliner-philharmoniker": "Orchestra"
        }
    }
}

The Status object

The Open Opus API always returns a 200 OK success code. Errors and stats are reported in the status object instead:

version 1.19.10 The Open Opus version
success true "true" if there are results for the query, "false" otherwise
error No works found "No [items] found" if good query with no results or "Bad request" if bad formed query
source db "db" if no external APIs were consumed, "external" otherwise
rows 2 Number of results
processingtime 0.0018379688262939453 Response time in seconds
api Open Opus-dyn "Open Opus-cache" if showing a cached result, "Open Opus-dyn" otherwise