Open Library RESTful API

https://openlibrary.org/dev/docs/restful_api
Admin
Open Library provides a RESTful API for accessing and querying its vast collection of books and...
Tokens:1,615
Snippets:5
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Query Data with wget

Source: https://openlibrary.org/dev/docs/restful_api/restful_api

Fetches data from the Open Library API using a JSON query. This example demonstrates querying for editions by author and title, with a limit. Note that this API is not intended for bulk downloads; use dumps for that purpose.

```bash
wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/authors/OL1A", "title": null, "limit": 2}'
```

--------------------------------

### Open Library API Documentation

Source: https://openlibrary.org/dev/docs/restful_api/restful_api

This section details various API functionalities including retrieving object history, listing recent changes, user authentication, and saving data. It provides examples using `curl` and explains parameters for filtering and pagination.

```APIDOC
## History

Change history of any object can be accessed by passing `?m=history` query parameter to the resource url.

```bash
$ curl http://openlibrary.org/books/OL1M.json?m=history
$ curl -H 'Accept: application/json' https://openlibrary.org/books/OL1M?m=history
```

The entries are sorted in descending order of creation time. The number of entries is limited to 20 by default, but a different limit can be specified using the `limit` parameter. An optional `offset` parameter can also be specified to get results starting from an offset. The maximum allowed value for `limit` is 1000 due to performance reasons.

```bash
$ curl http://openlibrary.org/books/OL1M.json?m=history&limit=2&offset=1
```

Support for RSS and Atom formats will be available soon.

## Recent Changes

Recent changes are available in JSON, RSS, and Atom formats.

```bash
$ curl http://openlibrary.org/recentchanges.json
$ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
```

Parameters `type`, `key`, and `author` can be specified to limit the results to modifications of objects of the specified type, specified key, and by a specific author, respectively. Also, `limit` and `offset` can be specified to limit the number of results and set an offset.

```bash
$ curl http://openlibrary.org/recentchanges.json?type=/type/page
$ curl http://openlibrary.org/recentchanges.json?author=/people/anand&offset=20&limit=20
```

Support for RSS and Atom formats will be available soon.

## Login

To log in to Open Library programmatically, a POST request must be sent to `/account/login.json` with your S3 `access` and `secret` keys passed as a JSON dictionary.

```bash
$ curl -i -H 'Content-Type: application/json' -d '{"access": "your access key", "secret": "your secret key"}' https://openlibrary.org/account/login
```

Upon successful login, a `Set-Cookie` header is returned in the response. Include this cookie with subsequent requests. Every Open Library account holder has S3 keys, which can be found at `https://archive.org/account/s3.php`.

## Save

Modifying objects can be done by sending a PUT request to the resource URL with an appropriate `Content-Type` header. The currently supported format is only JSON.

```
TODO: show an example
```

Please note that right now this is only an internal API and works only from localhost.

## Status Codes

### 200 OK

Status code `200 OK` is returned when the request is handled successfully.

### 400 Bad Request

Status code `400 Bad Request` is returned when there is any error in the provided input data. The error message is specified in the response body.

### 403 Forbidden

Status code `403 Forbidden` is returned for PUT/POST requests when the requesting user does not have the required permissions to modify the resource. The request can be repeated by providing the required credentials.

### 404 Not Found

Status code `404 Not Found` is returned when the requested resource is not found.

### 500 Internal Server Error

Status code `500 Internal Server Error` is returned if handling the request causes any internal errors. Debug information about the error may be provided in the response to help trouble-shooting the issue.
```

--------------------------------

### Fetch Content by ID (JSON/RDF)

Source: https://openlibrary.org/dev/docs/restful_api/restful_api

Retrieve content (books, authors) by their unique identifier. Supports specifying format via Accept header or URL extension. JSON format can optionally use a callback parameter.

```APIDOC
GET /<resource_type>/<id>.<format>

- Retrieves data for a specific resource (e.g., authors, books).
- Supported formats: JSON, RDF.
- Example (JSON): http://openlibrary.org/authors/OL1A.json
- Example (RDF): https://openlibrary.org/books/OL6807502M.rdf

Optional Parameters:
- callback: For JSON responses, wraps the output in a JavaScript function call.
  Example: http://openlibrary.org/authors/OL1A.json?callback=process

Accept Header:
- Can be used to specify the desired format, e.g., 'Accept: application/json' or 'Accept: application/rdf+xml'.
```

```shell
$ curl http://openlibrary.org/authors/OL1A.json
$ curl -s -H 'Accept: application/json' https://openlibrary.org/books/OL6807502M.rdf
$ curl http://openlibrary.org/authors/OL1A.json?callback=process
```

```json
{
    "name": "Sachi Rautroy",
    ...
}
```

```rdf
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:bibo="http://purl.org/ontology/bibo/"
         xmlns:dcterms="http://purl.org/dc/terms/"
         xmlns:rdvocab="http://www.rdvocab.info/Elements/">
  <rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
    <dcterms:title>Code and other laws of cyberspace</dcterms:title>
    <dcterms:publisher>Basic Books</dcterms:publisher>
    <dcterms:issued>1999</dcterms:issued>
    <bibo:authorList rdf:parseType="Collection">
      <rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
        <rdf:value>Lawrence Lessig</rdf:value>
      </rdf:Description>
    </bibo:authorList>
  </rdf:Description>
</rdf:RDF>
```

--------------------------------

### Query API: Search and Filter Data

Source: https://openlibrary.org/dev/docs/restful_api/restful_api

The Query API allows searching for objects based on various criteria like type, author, or work. Results can be filtered by requesting specific properties, all properties, or using pagination parameters.

```APIDOC
GET /query.json

- Searches the Open Library system for matching objects.

Query Parameters:
- type: Specifies the type of object to query (e.g., /type/edition, /type/author).
- authors: Filters by author ID (e.g., /authors/OL1A).
- works: Filters by work ID (e.g., /works/OL2040129W).
- <property_name>=: Request a specific property (e.g., title=) to include it in the results.
- *=: Request all available properties for the matching objects.
- limit: Maximum number of results to return (default 20, max 1000).
- offset: Number of results to skip.

Examples:
- Basic query by author: http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A
- Requesting title property: http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title=
- Requesting all properties: http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*= 
- With limit: http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2

Note: Queries can also be specified as a JSON dictionary, but the URL parameter approach is syntactic sugar.
```

```shell
$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A'
$ curl -H 'Accept: application/json' 'https://openlibrary.org/query?type=/type/edition&authors=/authors/OL1A'
$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title='
$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*= 
$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
```

```json
[
    {
        "key": "/books/OL1M"
    },
    {
        "key": "/books/OL4731M"
    },
    ...
]

// Example with title property:
[
    {
        "key": "/books/OL1M",
        "title": "Kabitā."
    },
    ...
]
```

--------------------------------

### List Editions of a Work / Works of an Author

Source: https://openlibrary.org/dev/docs/restful_api/restful_api

Retrieve a list of editions associated with a specific work or a list of works by a specific author. Supports pagination via the `limit` parameter.

```APIDOC
GET /works/<work_id>/editions.json?limit=<count>
GET /authors/<author_id>/works.json

- Retrieves lists of related resources.
- `limit` parameter controls the number of entries returned (default 20, max 1000).
- Example (Editions): http://openlibrary.org/works/OL27258W/editions.json?limit=5
- Example (Author Works): http://openlibrary.org/authors/OL1A/works.json
```

```shell
$ curl 'http://openlibrary.org/works/OL27258W/editions.json?limit=5'
$ curl http://openlibrary.org/authors/OL1A/works.json
```

```json
{
    "size": 19,
    "links": {
        "self": "/works/OL27258W/editions.json?limit=5",
        "work": "/works/OL27258W",
        "next": "/works/OL27258W/editions.json?limit=5&offset=5"
    },
    "entries": [
        {
            "key": "/books/OL17987798M",
            "title": "Neuromantiker",
            ...
        },
        ...
    ]
}
```
Tokens:
Raw