Click here to skip to this page's main content.

New to the Open Library? — Learn how it works
Last edited by Anand Chitipothu
October 12, 2010 | History

Subjects API

This API is experimental. Please be aware that this may change in future.

Get works of a subject

Sample Request:

GET /subjects/love.json

Sample Response:

{
    "key": "/subjects/love",
    "name": "love"
    "subject_type": "subject",
    "work_count": 4918,
    "works": [
        {
            "key": "/works/OL66534W",
            "title": "Pride and prejudice",
            "edition_count": 752,
            "authors": [
                {
                    "name": "Jane Austen",
                    "key": "/authors/OL21594A"
                }
            ],
            "has_fulltext": true,
            "ia": "mansfieldparknov03aust",
            ...
        },
        ...
    ]
}

All details of a subject

When query parameter details=true is passed, related subjects, prominent publishers, prolific authors and publishing_history are also included in the response.

Sample Request:

GET /subjects/love.json?details=true

Sample Response:

{
    "key": "/subjects/love",
    "name": "Love",
    "subject_type": "subject",
    "work_count": 4918,
    "ebook_count": 497,
    "works": [
        {
            "key": "/works/OL66534W",
            "title": "Pride and prejudice",
            "edition_count": 752,
            "authors": [
                {
                    "name": "Jane Austen",
                    "key": "/authors/OL21594A"
                }
            ],
            "has_fulltext": true,
            "ia": "mansfieldparknov03aust",
            ...
        },
        ...
    ],
    "authors": [
        {
            "count": 28,
            "name": "Plato",
            "key": "/authors/OL12823A"
        },
        {
            "count": 21,
            "name": "Ruoquan Wu",
            "key": "/authors/OL5638565A"
        },
        ...
    ],
    "publishers": [
        {
            "count": 54,
            "name": "Sine nomine"
        },
        {
            "count": 44,
            "name": "Bantam Books"
        },
        ...
    ],
    "subjects": [
        {
            "count": 914,
            "name": "Religious aspects of Love",
            "key": "/subjects/religious_aspects_of_love"
        },
        {
            "count": 887,
            "name": "Christianity",
            "key": "/subjects/christianity"
        },
        ...
    ],
    "people": [
        {
            "count": 44,
            "name": "Jesus Christ",
            "key": "/subjects/person:jesus_christ"
        },
        {
            "count": 42,
            "name": "Plato",
            "key": "/subjects/person:plato"
        },
        ...
    ],
    "places": [
        {
            "count": 80,
            "name": "United States",
            "key": "/subjects/place:united_states"
        },
        {
            "count": 36,
            "name": "France",
            "key": "/subjects/place:france"
        },
        ...
    ],
    "times": [
        {
            "count": 54,
            "name": "20th century",
            "key": "/subjects/time:20th_century"
        },
        ...
    ]
    "publishing_history": [
        [1492, 2],
        [1494, 1],
        ...,
        [2009, 119],
        [2010, 56]
    ]
}

Supported Query Parameters

details: When details=true is passed, related subjects, prominent publishers, prolific authors and publishing_history is also included in the response.

ebooks: When ebooks=true is passed, only the works which have an e-book are included in the response.

published_in: Support for filter on published year range. For example:

http://openlibrary.org/subjects/love.json?published_in=1500-1600

limit: Number of works to include in the response.

offset: starting offset in the total works. Used for pagination.

History Created October 12, 2010 · 3 revisions

October 12, 2010 Edited by Anand Chitipothu Edited without comment.
October 12, 2010 Edited by Anand Chitipothu removed extra heading
October 12, 2010 Created by Anand Chitipothu Subjects API