-
Create a list
-
Add/delete a seed from a list
-
Delete a list
-
Update a list -- not implemented
-
Get a user's lists
-
Get lists containing a seed
-
Get seeds of a list
-
Get editions of a list (for works use the seeds API above)
-
Get subjects of a list
- Search lists
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:
-
http://openlibrary.org/books/OL1M/lists.json
-
http://openlibrary.org/works/OL1W/lists.json
-
http://openlibrary.org/authors/OL1A/lists.json
- http://openlibrary.org/subjects/place:san_francisco/lists.json
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
- limited to 100 results for performance reasons
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
- create an empty list (no book seed)
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
- create a list with book seed(s)
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
- Add seed(s) to 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}
- Delete seed(s) 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
- 17 revisions
| 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 |