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

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

Upcoming Lists API

This is a draft of upcoming lists API. This is still under development.

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
        }
    ]
}

List

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

Add/delete a seed from a list:

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 Created September 24, 2010 · 6 revisions

December 21, 2010 Edited by Anand Chitipothu Edited without comment.
December 21, 2010 Edited by Anand Chitipothu Provides uniform interface accessing and updating for seeds.
December 21, 2010 Edited by Anand Chitipothu Updated Lists API.
September 27, 2010 Edited by Anand Chitipothu API changes
September 24, 2010 Created by Anand Chitipothu Upcoming Lists API