It looks like you're offline.
Open Library logo
additional options menu
Last edited by raybb
October 15, 2023 | History

Lists API

 

Get a user's lists

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 containing 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": "Empty List",
    "description": "This is an empty list with no books added yet.",
}

Response:

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

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
}

 

Delete a list

Request:

POST /people/anand/list/OL1L/delete.json
Content-Type: application/json

 

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"
            }
        },
        ...
    ]
}

 

Add/delete a seed from a list

Request:

POST /people/anand/list/OL1L/seeds HTTP/1.1
Content-Type: application/json
{
    "add": [
        {key: "/books/OL25083437M"},
        {key: "/books/OL24375501M"}
    ]
}

Response:

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

Request:

POST /people/anand/lists/OL1L/seeds HTTP/1.1
Content-Type: application/json
{
    "add": [
        "/subjects/gothic_architecture"
    ],
    "remove": [
        "/works/OL1958650W"
    ]
}

Response:

200 OK HTTP/1.1
Content-Type: application/json
{"ok": "true"}

 

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 15, 2023 Edited by raybb note about getting works
March 15, 2023 Edited by Mek Edited without comment.
March 13, 2023 Edited by Drini Fix formatting of some sections
March 13, 2023 Edited by Drini Removing incoming from title
September 24, 2010 Created by Anand Chitipothu Upcoming Lists API