Read API
Infogami provides an API to query the database for objects matching particular criteria or to get an object from the database. All the requests take input either as part of the URL or query string. You can try sample requests and practice building requests in the API sandbox.
- Querying for Objects (/things)
- Getting an Object (/get)
- Queries for Versions (/versions)
- Search queries (/search)
The database structure, developed by the Open Library, is called infogami. Infogami stores a collection of objects, called "things". For example, on the Open Library site, each page, book, author, and user is a thing in the database. Each thing then has a series of arbitrary key-value pairs as properties. For example, a book thing may have the key "title" with the value "A Heartbreaking Work of Staggering Genius" and the key "genre" with the value "Memoir". Each collection of key-value pairs is stored as a version, along with the time it was saved and the person who saved it.
Because in infogami everything is an object, you can query for any object in infogami space, such as templates, editions, authors, or individual infogami fields in any page type. Each object has an object type. (List of types.) For example, there is /type/edition which represents all of the information about a book, and type/edition/isbn_10 which is the property for the 10-character ISBN in the edition record.
Querying for Objects (/things)
To find objects matching a particular query, send a GET request to http://openlibrary.org/api/things with query as parameter. In this documentation we use curl as a simple command line query client; any software that supports http GET can be used.
The query must use JSON dictionary syntax.
This query searches for all editions with a particular ISBN value, and returns the keys of all matching records. Since there can be only one book with the any ISBN, the result contains only one key. (In practice unfortunately you will see publishers have reused an ISBN for otherwise unrelated works.)
var request = {
"type": "/type/edition",
"isbn_10": "0789312239",
};
var response = {
"status": "ok",
"result": [
"\/b\/OL3315616M"
]
};
query(request, response);
A curl request for the above, then, would read as follows:
$ curl -G --data-urlencode 'query={"type":"\/type\/edition", "isbn_10":"0789312239"}' \
http://openlibrary.org/api/things
Pattern matching
The API supports querying for objects based of string matching.
Here is an example to get all object with key starting from /about/.
var request = {
"key~": "/about/*"
};
var response = {
"status": "ok",
"result": [
"\/about\/architecture",
"\/about\/banned",
"\/about\/calendar",
"\/about\/catalog",
"\/about\/contact",
"\/about\/faq",
"\/about\/help",
"\/about\/help\/libraries",
"\/about\/help\/oclc",
"\/about\/help\/upload",
"\/about\/infogami-dc",
"\/about\/jobs",
"\/about\/lib",
"\/about\/ol_info_sheet",
"\/about\/olmeeting2008",
"\/about\/oln",
"\/about\/pagelist",
"\/about\/people",
"\/about\/performance",
"\/about\/press",
"\/about\/publishers",
"\/about\/relnote",
"\/about\/sample_publisher_letter",
"\/about\/schema",
"\/about\/tech",
"\/about\/vision"
]
};
query(request, response);
Due to performance reasons, * is allowed only at the end of a string.
The Sort Directive
The sort directive can be used to tell Infogami to sort the results of a query before returning.
The following query gives the list of all documents sorted in the order of their keys.
var request = {
"type": "/type/doc",
"sort": "key"
};
var response = {
"status": "ok",
"result": [
"\/dev\/docs\/api",
"\/dev\/docs\/infogami",
"\/dev\/docs\/ui"
]
};
query(request, response);
By default sort operation returns the results in the ascending order. To reverse that order, prepend minus (-) to the value of sort directive.
var request = {
"type": "/type/doc",
"sort": "-key"
};
var response = {
"status": "ok",
"result": [
"\/dev\/docs\/ui",
"\/dev\/docs\/infogami",
"\/dev\/docs\/api"
]
};
query(request, response);
Limiting Queries
By default every results of every query are limited to 100 values. Alternate limit can be specified by using the limit directive.
Here is an example to get first 10 templates.
var request = {
"type": "/type/template",
"sort": "key",
"limit": 10
};
var response = {
"status": "ok",
"result": [
"/templates/advanced_search.tmpl",
"/templates/backlinks.tmpl",
"/templates/default_diff.tmpl",
"/templates/default_edit.tmpl",
"/templates/default_input.tmpl",
"/templates/default_ref.tmpl",
"/templates/default_repr.tmpl",
"/templates/default_view.tmpl",
"/templates/deleted.tmpl",
"/templates/diff.tmpl"
]
};
query(request, response);
The offset directive can be used to ask infogami to give results from a specific offset.
The following query gives the next 10 templates.
var request = {
"type": "/type/template",
"sort": "key",
"limit": 10,
"offset": 10
};
var response = {
"status": "ok",
"result": [
"\/templates\/editpage.tmpl",
"\/templates\/forgot_password.tmpl",
"\/templates\/fullsearch.tmpl",
"\/templates\/history.tmpl",
"\/templates\/i18n.tmpl",
"\/templates\/imageupload.tmpl",
"\/templates\/login.tmpl",
"\/templates\/login_preferences.tmpl",
"\/templates\/notfound.tmpl",
"\/templates\/password_mailer.tmpl"
]
};
query(request, response);
Expression AND in queries
All the keys in the query other than special directives (sort, limit, offset) are implicitly ANDed.
For example, the following query finds all objects having type as /type/edition and author as Mark Twain (/a/OL18319A).
var request = {
"type": "/type/edition", "authors": "/a/OL18319A", "sort": "key", "limit": 5 };var response = {
"status": "ok", "result": [ "/b/OL1001932M", "/b/OL1016757M", "/b/OL1017798M", "/b/OL1045540M", "/b/OL105166M" ] };query(request, response)
Getting an Object (/get)
In Infogami, every object is identified by a unique key. In the example above, we queried the database on an ISBN and were returned the unique key for the edition that matches that ISBN. We can then retrieve the edition with a get command:
$ curl http://openlibrary.org/api/get?key=/b/OL1001932M
This returns:
{ "status": "ok", "result": { "subject_place": [ "Venice (Italy)"], "lc_classifications": [ "DG674.2 .S3 2005" ], "latest_revision": 1, "genres": [ "Juvenile literature."], "title": "This is Venice", "languages": [ { "key": "\/l\/eng" }], "subjects": [ "Venice (Italy) -- Description and travel -- Juvenile literature."], "publish_country": "nyu", "by_statement": "M. Sasek.","type": { "key": "\/type\/edition" }, "revision": 1, publishers": [ "Universe"], "last_modified": "2008-04-01T03:28:50.625462", "key": "\/b\/OL3315616M", "authors": [ { "key": "\/a\/OL1396639A" } ], "publish_places": [ "New York, NY" ], "pagination": "56 p. :", "lccn": [ "2004110229" ], "notes": "\"A children's classic\"--Cover.\nOriginally published: New York : Macmillan, 1961.", "number_of_pages": 56, "isbn_10": [ "0789312239" ], publish_date": "2005" }}
Because this string is hard to read, you may want to add the parameter "prettyprint=true" when you are testing your queries.
$ curl http://openlibrary.org/api/get?key=/b/OL1001932M&prettyprint=true
This returns a more eye-readable version of the same string.
# response
{
"status": "ok",
"result": {
"subject_place":
"Venice (Italy)",
"lc_classifications":
"DG674.2 .S3 2005",
"latest_revision": 1,
"genres": [
"Juvenile literature."
],
"title": "This is Venice",
"languages": [
{
"key": "\/l\/eng"
}
],
"subjects": [
"Venice (Italy) -- Description and travel -- Juvenile literature."
],
"publish_country": "nyu",
"by_statement": "M. Sasek.",
"type": {
"key": "\/type\/edition"
},
"revision": 1,
"publishers": [
"Universe"
],
"last_modified": "2008-04-01T03:28:50.625462",
"key": "\/b\/OL3315616M",
"authors": [
{
"key": "\/a\/OL1396639A"
}
],
"publish_places": [
"New York, NY"
],
"pagination": "56 p. :",
"lccn": [
"2004110229"
],
"notes": "\"A children's classic\"--Cover.\nOriginally published: New York : Macmillan, 1961.",
"number_of_pages": 56,
"isbn_10": [
"0789312239"
],
"publish_date": "2005"
}
}
The following example gets the page /pagelist using the API.
$ curl http://openlibrary.org/api/get?key=/pagelist?prettyprint=true
{
"status": "ok",
"result": {
"body": "{{PageList(\"\/\")}}",
"title": "Page List",
"last_modified": "2008-04-18T09:19:56.978194",
"latest_revision": 1,
"key": "\/pagelist",
"type": {"key": "\/type\/page"},
"revision": 1
}
}
Since the response is in JSON format, the Content-Type is set to application/json, which may not be displayed by the browsers as text. To enable that text=true must be passed in the query string.
Queries for Versions (/versions)
In Infogami, modification of every object creates a new version of that object.
To find versions matching a particular query, send a GET request to http://openlibrary.org/api/versions with query as parameter. The query must be a JSON dictionary, just like the things query. The sort and limit directives work similar to the things query.
For example the following query finds the most 10 versions of / object.
# Query
{
"key": "/",
"limit": 3,
"sort": "-created"
}
| ⇒ | # Response |
Search queries (/search)
This search API is deprecated and not maintained now. The Open Library Books API can be used for searching for ISBNs or other identifiers. We are working on a new work search API to replace this.
A search API query is a JSON dictionary passed as the "q" http parameter. The dictionary just one meaningful entry, "query". The response is a json object containing a list of openlibrary id's. The optional argument "prettyprint" http parameter controls formatting of the response, as above. In the example below, the query is
http://openlibrary.org/api/search?q={"query":"Felix Klein"}&prettyprint=true
# Query
{
"query": "Felix Klein",
}
| ⇒ | # Response |
"/b/OL5888524M",
"/b/OL6088137M",
"/b/OL6088190M",
"/b/OL6272774M"
]
}
Performance Issues
To have a bound on the amount of resources consumed by a query, the runtime of each query is limited to 60 sec. Any query that takes longer is aborted.
History
- Created May 21, 2009
- 7 revisions
| September 5, 2022 | Edited by mheiman | Fixed the formatting that was making a lot of the examples invisible |
| March 2, 2022 | Edited by jachamp | Remove reference to missing red arrow image |
| September 2, 2010 | Edited by Anand Chitipothu | layout fixes |
| September 2, 2010 | Edited by Anand Chitipothu | copy |
| May 21, 2009 | Created by Anand Chitipothu | JSON API |