It looks like you're offline.
Donate
English
Open Library logo

Open Library RESTful API → Diff

Added
Modified
Removed
Not changed
Revision 5 by Anand Chitipothu March 12, 2009
Revision 21 by jachamp September 1, 2023
body
0 <div class="alert">
1 <code class="normal">
2 **WARNING:** This document explains the upcoming RESTful API. The examples given below may not work now.
3 </code>
4 </div>
5
6 <style type="text/css"> 0 <style type="text/css">
7 pre { background-color:#F0F0F0; border:1px solid #CCCBBA; padding: 10px 10px 10px 20px; } 1 pre { background-color:#F0F0F0; border:1px solid #CCCBBA; padding: 10px 10px 10px 20px; }
8 </style> 2 </style>
9 3
10 Open Library provides RESTful API for accessing resources in multiple formats. 4 Open Library provides a RESTful API for accessing resources in multiple formats.
11 5
12 * [[#content|Content]] 6 <ul>
13 * [[#query|Query]] 7  <li><a href="#content">Content</a></li>
14 * [[#history|History]] 8  <li><a href="#query">Query</a></li>
15 * [[#save|Save]] 9  <li><a href="#history">History</a></li>
16 * [[#status_codes|Status Codes]] 10  <li><a href="#recent_changes">Recent Changes</a></li>
17 11  <li><a href="#login">Login</a></li>
18 <a name="content"></a> 12  <li><a href="#save">Save</a></li>
13  <li><a href="#status_codes">Status Codes</a></li>
14 </ul>
15
16 <a name="content">&nbsp;</a>
19 ## Content 17 ## Content
20 18
21 To request any content, the requested format can be specified using `Accept:` header or as part of the URL. 19 To request any content, the requested format can be specified using `Accept:` header or as part of the URL.
22 The currently available formats are JSON and RDF. 20 The currently available formats are JSON and RDF.
23 21
24    $ curl http://openlibrary.org/a/OL1A.json 22    $ curl http://openlibrary.org/authors/OL1A.json
25    { 23    {
26        "name": "Sachi Rautroy", 24        "name": "Sachi Rautroy",
27        ... 25        ...
28    } 26    }
29    $ curl -s -H 'Accept: application/json' http://openlibrary.org/b/OL1M 27    $ curl -s -H 'Accept: application/json' https://openlibrary.org/books/OL1M
30    { 30    {
... ...
36 36
37    $ curl http://openlibrary.org/a/OL1A.json?callback=process 35    $ curl http://openlibrary.org/authors/OL1A.json?callback=process
38    process({ 36    process({
39        "name": "Sachi Rautroy", 37        "name": "Sachi Rautroy",
40        ... 38        ...
41    }); 39    });
42     40    
43 The RDF format is still under development and not ready for serious use. 41 The RDF format is available for books and for authors.
44 42
45    $ curl http://openlibrary.org/a/OL1A.rdf 43    $ curl https://openlibrary.org/books/OL6807502M.rdf
46    <?xml version="1.0" encoding="utf-8"?> 44    <rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
47    <rdf:RDF 45    <!-- authors -->
48      xmlns:ol='http://openlibrary.org/type/author' 46    <bibo:authorList rdf:parseType="Collection">
49    > 47      <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
50        <ol:name>Sachi Rautroy</ol:name> 48         <rdf:value>Lawrence Lessig</rdf:value>
51        ... 49      </rdf:Description>
50    </bibo:authorList>
51        <!-- bibliographic description -->
52        <dcterms:title>Code and other laws of cyberspace</dcterms:title>
53        <dcterms:publisher>Basic Books</dcterms:publisher>
54        <rdvocab:placeOfPublication>New York</rdvocab:placeOfPublication>
55        <dcterms:issued>1999</dcterms:issued>
56        <dcterms:extent>xii, 297 p. :</dcterms:extent>
57       ....
52    </rdf:RDF> 58    </rdf:RDF>
53    $ curl -H 'Accept: application/rdf+xml' http://openlibrary.org/a/OL1A 59    $ curl -H 'Accept: application/rdf+xml' https://openlibrary.org/books/OL6807502M.rdf
54    <?xml version="1.0" encoding="utf-8"?> 60    <rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
55    <rdf:RDF 61    <!-- authors -->
56      xmlns:ol='http://openlibrary.org/type/author' 62    <bibo:authorList rdf:parseType="Collection">
57    > 63      <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
58        <ol:name>Sachi Rautroy</ol:name> 64         <rdf:value>Lawrence Lessig</rdf:value>
59        ... 65      </rdf:Description>
66    </bibo:authorList>
67       <!-- bibliographic description -->
68        <dcterms:title>Code and other laws of cyberspace</dcterms:title>
60    </rdf:RDF> 69    </rdf:RDF>
61     70
62 <a name="query"></a> 71 Open Library also allows accessing editions of a work and works of an author using a simple URL format.
72
73    $ curl 'http://openlibrary.org/works/OL27258W/editions.json?limit=5'
74    {
75        "size": 19,
76        "links": {
77            "self": "/works/OL27258W/editions.json?limit=5",
78            "work": "/works/OL27258W",
79            "next": "/works/OL27258W/editions.json?limit=5&offset=5"
80        },
81        "entries": [{
82            "key": "/books/OL17987798M",
83            "title": "Neuromantiker",
84            ...
85        }, ...]
86    }
87
88    $ curl http://openlibrary.org/authors/OL1A/works.json
89    {
90        "size": 16,
91        "links": {
92            "self": "/authors/OL1A/works.json",
93            "author": "/authors/OL1A"}
94        },
95        "entries": [{
96            "key": "/works/OL14930760W",
97            "title": "Satchidananda Raut Roy",
98            ...
99        }, ...]
100    }
101    
102 <a name="query">&nbsp;</a>
63 ## Query 103 ## Query
64 104
65 The Query API allows querying the Open Library system for matching objects. 105 The Query API allows querying the Open Library system for matching objects.
66 106
67    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A' 107    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A'
68    [ 108    [
69        { 109        {
70            "key": "/b/OL1M" 110            "key": "/books/OL1M"
71        }, 111        },
72        { 112        {
73            "key": "/b/OL4731M" 113            "key": "/books/OL4731M"
74        }, 114        },
75        ... 115        ...
76    ] 116    ]
77    $ curl -H 'Accept: application/json' 'http://openlibrary.org/query?type=/type/edition&authors=/a/OL1A' 117    $ curl -H 'Accept: application/json' 'https://openlibrary.org/query?type=/type/edition&authors=/authors/OL1A'
78    [ 118    [
79        { 119        {
80            "key": "/b/OL1M" 120            "key": "/books/OL1M"
81        }, 121        },
82        { 122        {
83            "key": "/b/OL4731M" 123            "key": "/books/OL4731M"
84        }, 124        },
85        ... 125        ...
86    ]     126    ]    
127    $ curl 'http://openlibrary.org/query.json?type=/type/edition&works=/works/OL2040129W'
128    [
129        {
130            "key": "/books/OL9770407M"
131        },
132        {
133            "key": "/books/OL21857767M"
134        },
135        ...
136    ]    
87 137
88 Additional properties of each object can be requested by passing a query parameter with empty value. 138 Additional properties of each object can be requested by passing a query parameter with empty value.
89 139
90    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&title=' 140    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title='
91    [ 141    [
92        { 142        {
93            "key": "/b/OL1M", 143            "key": "/books/OL1M",
94            "title": "Kabit\u0101." 144            "title": "Kabit\u0101."
95        }, 145        },
96        { 146        {
97            "key": "/b/OL4731M", 147            "key": "/books/OL4731M",
98            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304." 98            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
... ...
104 104
105    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&*=' 155    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*='
106    [ 106    [
... ...
111            ... 111            ...
112            "key": "/b/OL1M", 162            "key": "/books/OL1M",
113            ... 163            ...
114        }, 164        },
115        ... 165        ...
116    ] 166    ]
117 167
118 Optional `limit` and `offset` parameters can be passed to limit the number of requests and offset in the results respectively. 168 Optional `limit` and `offset` parameters can be passed to limit the number of requests and offset in the results respectively. Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of `limit` is 1000 due to performance reasons.
119 Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of `limit` is 1000 due to performance reasons. 169
120 170    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
121    $ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&limit=2' 171    [
122    [ 172        {
123        { 173            "key": "/books/OL1M"
124            "key": "/b/OL1M" 174        },
125        }, 175        {
126        { 176            "key": "/books/OL4731M"
127            "key": "/b/OL4731M"
128        } 177        }
129    ] 178    ]
130 179
131 Queries can also be specified by passing the query as JSON dictionary. 180 Queries can also be specified by passing the query as JSON dictionary. The above mentioned approach is just a syntactic-sugar for this.
132 The above mentioned approach is just a syntactic-sugar for this.
133 181
134    # curl fails because it doesn't escape query parameter 182    # curl fails because it doesn't escape query parameter
135    $ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/a/OL1A", "title": null, "limit": 2}' 183    $ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/authors/OL1A", "title": null, "limit": 2}'
136    [ 184    [
137        { 185        {
138            "key": "/b/OL1M", 186            "key": "/books/OL1M",
139            "title": "Kabit\u0101." 187            "title": "Kabit\u0101."
140        }, 188        },
141        { 189        {
142            "key": "/b/OL4731M", 190            "key": "/books/OL4731M",
143            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304." 191            "title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
144        } 192        }
145    ] 193    ]
146 194
147 Please note that this API should not be used for bulk downloads. 195 *Please note that this API should not be used for bulk downloads.* [[/developers/dumps|Dumps of all data]] are provided at regular intervals and they should be used for bulk access.
148 Dumps of the entire data are provided at regular intervals and they can be used for bulk access. 196
149 197 <a name="history">&nbsp;</a>
150 <a name="history"></a>
151 ## History 198 ## History
152 199
153 Change history of any object can be accessed by passing `?m=history` query parameter to the resource url. 200 Change history of any object can be accessed by passing `?m=history` query parameter to the resource url.
154 201
155    $ curl http://openlibrary.org/b/OL1M.json?m=history 202    $ curl http://openlibrary.org/books/OL1M.json?m=history
156    [ 156    [
... ...
163    ] 163    ]
164    $ curl -H 'Accept: application/json' http://openlibrary.org/b/OL1M?m=history 211    $ curl -H 'Accept: application/json' https://openlibrary.org/books/OL1M?m=history
165    [ 165    [
... ...
173     173    
221
174 The entries are sorted in the descending order of created time. 222 The entries are sorted in the descending order of created time.
175 The number of entries are limited to 20 by default and a different limit can be specified by passing `limit` parameters. 223 The number of entries are limited to 20 by default and a different limit can be specified by passing `limit` parameters.
176 Optional `offset` parameter can also be specified to get results starting from an offset. 224 Optional `offset` parameter can also be specified to get results starting from an offset.
177 Maximum allowed value of `limit` is 1000 due to performance reasons. 225 Maximum allowed value of `limit` is 1000 due to performance reasons.
178 226
179    $ curl http://openlibrary.org/b/OL1M.json?m=history&limit=2&offset=1 227    $ curl http://openlibrary.org/books/OL1M.json?m=history&limit=2&offset=1
180    [ 180    [
... ...
194 194
243 <a name="recent_changes">&nbsp;</a>
195 ## Recent Changes 195 ## Recent Changes
... ...
206    ] 206    ]
207    $ curl -H 'Accept: application/json' http://openlibrary.org/recentchanges 256    $ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
208    [ 208    [
... ...
215     215    
216 Parameters, `type`, `key` and `author` can be specified to limit the results to modifications to objects of specified type, specified key and by an author respectively. 265 Parameters, `type`, `key` and `author` can be specified to limit the results to modifications to objects of specified type, specified key and by an author respectively. Also `limit` and `offset` can be specified to limit number of results and offset.
217 Also `limit` and `offset` can be specified to limit number of results and offset.
218 266
219    $ curl http://openlibrary.org/recentchanges.json?type=/type/page 267    $ curl http://openlibrary.org/recentchanges.json?type=/type/page
220    ... 268    ...
221    $ curl http://openlibrary.org/recentchanges.json?author=/user/anand&offset=20&limit=20 269    $ curl http://openlibrary.org/recentchanges.json?author=/people/anand&offset=20&limit=20
222 270
223 Support for RSS and Atom formats will be available soon. 271 Support for RSS and Atom formats will be available soon.
224 272
225 <a name="login"></a> 273 <a name="login">&nbsp;</a>
226 ## Login 274 ## Login
227 275
228 To login to Open Library programatically, a POST request must be send to `/account/login` with `username` and `password` must be passed as a JSON dictionary. 276 To login to Open Library programatically, a POST request must be send to `/account/login.json` with your S3 `access` and `secret` keys passed as a JSON dictionary.
229 277
230    $ curl -i -H 'Content-Type: application/json' -d '{"username": "joe", "password": "secret"}' http://openlibrary.org/account/login 278    $ curl -i -H 'Content-Type: application/json' -d '{"access": "your access key", "secret": "your secret key"}' https://openlibrary.org/account/login
231    HTTP/1.1 200 OK 279    HTTP/1.1 200 OK
232    Set-Cookie: ol_session="/user/joe%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/ 280    Set-Cookie: session="/user/username%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/
233     281    
234 Upon successful login, a set-cookie header is returned in the response. 282 Upon successful login, a set-cookie header is returned in the response. Include this cookie with subsequent requests.
235 283
236 <a name="save"></a> 284 Every Open Library account holder has S3 keys. You can find yours <a href="https://archive.org/account/s3.php">here</a>.
285
286 <a name="save">&nbsp;</a>
237 ## Save 287 ## Save
238 288
239 Modifying objects can be done by sending a PUT request to the resource url with appropriate `Content-Type` header. 289 Modifying objects can be done by sending a PUT request to the resource url with appropriate `Content-Type` header. The currently supported format is only JSON.
240 The currently supported format is only JSON.
241 290
242    TODO: show an example 291    TODO: show an example
243     292    
244 Please note that right now this only an internal API and works only from the localhost. 293 Please note that right now this only an internal API and works only from the localhost.
245 294
246 <a name="status_codes"></a> 295 <a name="status_codes">&nbsp;</a>
247 ## Status codes 247 ## Status codes
... ...
271 Debug information about the error may be provided in the response to help trouble-shooting the issue. 271 Debug information about the error may be provided in the response to help trouble-shooting the issue.
m edit