Open Library logo
We redesigned our Book Pages — can you share feedback?
Last edited by Drini
October 12, 2019 | History

Upcoming Lists API

This is a draft of upcoming lists API. This is still under development, and could change at any time.

 

Get Lists of a user

Request:

GET http://openlibrary.org/people/george08/lists.json

Response:

{
    "links": {
        "self": "/people/george08/lists.json",
        "next": "/people/george08/lists.json?limit=5&offset=5"
    },
    "size": 12,
    "entries": [
        {
            "url": "/people/george08/lists/OL13L",
            "full_url": "/people/george08/lists/OL13L/Various_Seeds_for_Testing",
            "name": "Various Seeds for Testing",
            "last_update": "2010-12-21T00:46:17.712513",
            "seed_count": 13,
            "edition_count": 13181
        },
        {
            "url": "/people/george08/lists/OL97L",
            "full_url": "/people/george08/lists/OL97L/Time_Travel",
            "name": "Time Travel",
            "last_update": "2010-12-17T18:27:14.781336",
            "seed_count": 5,
            "edition_count": 838
        },
        ...
    ]
}

 

Get lists of a seed

URL Format:

Sample Request:

GET http://openlibrary.org/works/OL8721462W/lists.json

Response:

{
    "size": 1,
    "links": {
        "self": "/works/OL8721462W/lists.json"
    },
    "entries": [
        {
            "url": "/people/george08/lists/OL43L",
            "full_url": "/people/george08/lists/OL43L/Top_100_Works_in_World_Literature_(in_progress)",
            "name": "Top 100 Works in World Literature (in progress)",
            "last_update": "2010-12-21T04:17:33.140325",
            "seed_count": 28,
            "edition_count": 2105
        }
    ]
}

 

Search Lists

Request:

GET http://openlibrary.org/search/lists.json?q=book&limit=20&offset=0

Response:

{
    "start": 0,
    "docs": [
        {
        "seed_count": 1,
        "edition_count": 0,
        "url": "/people/rosey1234/lists/OL68457L",
        "last_update": "2019-10-12T17:05:09.130806",
        "full_url": "/people/rosey1234/lists/OL68457L/book",
        "name": "book"
        },
        {
        "seed_count": 1,
        "edition_count": 0,
        "url": "/people/alebuitrago/lists/OL69449L",
        "last_update": "2019-10-12T17:05:09.130806",
        "full_url": "/people/alebuitrago/lists/OL69449L/book",
        "name": "book"
        },
        ...
    ]
}

 

Create a List

Request:

POST /people/anand/lists HTTP/1.1
Content-Type: application/json
{
    "name": "18th Century Architecture",
    "description": "Studies of architectural practice, mainly English works",
    "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
    "seeds": [
        "/books/OL1M",
        "/subjects/gothic_architecture"
    ]
}

Response:

HTTP/1.1 201 Created
Location: http://openlibrary.org/user/anand/lists/OL1L

 

Read a list

Request:

GET http://openlibrary.org/people/george08/lists/OL97L.json

Response:

{
    "links": {
        "editions": "/people/george08/lists/OL97L/editions",
        "self": "/people/george08/lists/OL97L",
        "seeds": "/people/george08/lists/OL97L/seeds",
        "subjects": "/people/george08/lists/OL97L/subjects"
    },
    "meta": {
        "last_modified": "2010-12-17T18:54:58.115370",
        "revision": 5,
        "created": "2010-12-17T18:50:35.064318"
    },
    "name": "Time Travel",
    "description": "Happy to lose myself in reading about that.",
    "seed_count": 5,
    "edition_count": 838
}

 

Update a list

This is not yet implemented!

Request:

PUT /people/anand/list/OL1L HTTP/1.1
Content-Type: application/json
{
    "name": "18th Century Architecture",
    "description": "Studies of architectural practice, mainly English works",
    "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
    "seeds": [
        "subject:gothic_architecture"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{"key": "/people/anand/list/OL1L", "revision": 3}

Get seeds of a list

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/seeds.json

Response:

{
    "size": 5,
    "links": {
        "self": "/people/george08/lists/OL97L/seeds",
        "list": "/people/george08/lists/OL97L"
    },
    "entries": [
        {
            "url": "/books/OL24331810M",
            "full_url": "/books/OL24331810M/The_Time_Machine",
            "type": "edition",
            "title": "The Time Machine",
            "last_update": "2010-12-17T18:27:14.781336",
            "work_count": 1,
            "edition_count": 1,
            "ebook_count": 1,
            "picture": {
                "url": "http://covers.openlibrary.org/b/id/6570017-S.jpg"
            }
        },
        {
            "url": "/books/OL22864669M",
            "full_url": "/books/OL22864669M/A_Connecticut_Yankee_in_King_Arthur's_Court",
            "type": "edition",
            "title": "A Connecticut Yankee in King Arthur's Court",
            "last_update": "2010-09-06T02:05:15.820687",
            "work_count": 1,
            "edition_count": 1,
            "ebook_count": 7,
            "picture": {
                "url": "http://covers.openlibrary.org/b/id/6031475-S.jpg"
            }
        },
        ...
    ]
}

 

Get editions of a list

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/editions.json?limit=2

Response:

{
    "links": {
        "self": "/people/george08/lists/OL97L/editions.json?limit=2",
        "next": "/people/george08/lists/OL97L/editions.json?limit=2&offset=2",
        "list": "/people/george08/lists/OL97L"
    },
    "size": 838,
    "entries": [
        {
            "number_of_pages": 216,
            "table_of_contents": [...],
            "series": ["Buckram series"],
            "covers": [6570017],
            "lc_classifications": ["PZ3.W465 Ti"],
            "latest_revision": 6,
            "ocaid": "timemachineinven00well",
            "subtitle": "an invention",
            "source_records": ["ia:timemachineinven00well"],
            "title": "The Time Machine",
            "languages": [
                {
                    "key": "/languages/eng"
                }
            ],
            "publish_country": "nyu",
            "by_statement": "by H. G. Wells",
            "oclc_numbers": [
                "002345875"
            ],
            "type": {
                "key": "/type/edition"
            },
            "revision": 6,
            "publishers": [
                "H. Holt and Company"
            ],
            "last_modified": {
                "type": "/type/datetime",
                "value": "2010-12-17T18:27:14.781336"
            },
            "key": "/books/OL24331810M",
            "authors": [
                {
                    "key": "/authors/OL13066A"
                }
            ],
            "publish_places": [
                "New York"
            ],
            "pagination": "vii, 216 p.",
            "classifications": {},
            "created": {
                "type": "/type/datetime",
                "value": "2010-08-12T15:25:20.784688"
            },
            "lccn": [
                "08036642"
            ],
            "identifiers": {},
            "publish_date": "1895",
            "works": [
                {
                    "key": "/works/OL52267W"
                }
            ]
        },
        {
            ...
        }
    ]
}

 

Get subjects of a list

Request:

GET http://openlibrary.org/people/george08/lists/OL97L/subjects.json?limit=5

Response:

{
    "links": {
        "self": "/people/george08/lists/OL97L/subjects",
        "list": "/people/george08/lists/OL97L"
    },
    "subjects": [
        {
            "count": 256,
            "url": "/subjects/general_relativity_(physics)",
            "name": "General relativity (Physics)"
        },
        ...
    ],
    "places": [
        {
            "count": 1,
            "url": "/subjects/place:great_britain",
            "name": "Great Britain"
        },
        ...
    ],
    "people": [
        {
            "count": 1,
            "url": "/subjects/person:mark_twain_(1835-1910)",
            "name": "Mark Twain (1835-1910)"
        },
        ...
    ],
    "times": [
        {
            "count": 1,
            "url": "/subjects/time:19th_century",
            "name": "19th century"
        }
    ]
}

History

October 12, 2019 Edited by Drini fix toc
October 12, 2019 Edited by Drini fix anchor tags
October 12, 2019 Edited by Drini fix toc
October 12, 2019 Edited by Drini addes TOC + search endpoint docs
September 24, 2010 Created by Anand Chitipothu Upcoming Lists API