### 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 //. - 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 Code and other laws of cyberspace Basic Books 1999 Lawrence Lessig ``` -------------------------------- ### 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). - =: 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//editions.json?limit= GET /authors//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", ... }, ... ] } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.