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

New to the Open Library? — Learn how it works
Is Open Library useful to you? Chip in to keep it growing. Your gift will be matched today!   Donate
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