{"_id":"5810438c98aea40f00afa3a6","version":{"_id":"56d55014075dfa0b00be98e9","__v":16,"project":"56d55013075dfa0b00be98e6","createdAt":"2016-03-01T08:17:24.051Z","releaseDate":"2016-03-01T08:17:24.051Z","categories":["56d55014075dfa0b00be98ea","56d55036c8c687150071efb3","56d55094b939870b005129e2","56d550ae5acf9f0b00f735d0","56d5537ac8c687150071efbf","573cae191000320e00918252","573cbe15f320ae29009dbd94","5792a0baf967f617000d9e77","5792a0c023106419009c4302","58093f2994bc150f00f2fe47","580940f33c22790f00fd1e98","58094c01e5998d0f00d29b5d","58101442c03f0b0f0097f099","581020f07c59d72500b85add","581032c708d8050f00948d2a","5810e6ca08d8050f00948dcf"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Archy","version_clean":"1.0.0","version":"1"},"parentDoc":null,"__v":1,"category":{"_id":"580940f33c22790f00fd1e98","project":"56d55013075dfa0b00be98e6","version":"56d55014075dfa0b00be98e9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-20T22:10:59.106Z","from_sync":false,"order":8,"slug":"experimental-labs-endpoints","title":"Labs / Experiments"},"project":"56d55013075dfa0b00be98e6","githubsync":"","user":"56d54fd3c8c687150071efb0","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-26T05:47:56.647Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","status":200,"name":"","code":"{\n\n    \"Annotations\": \"https://api.archivelab.org/books/<archive_id>/pages/<page>/annotations\",\n    \"BookIAManifest\": \"https://api.archivelab.org/books/<archive_id>/ia_manifest\",\n    \"BookIIIFManifest\": \"https://api.archivelab.org/books/<archive_id>/iiif_manifest\",\n    \"BookMetadata\": \"https://api.archivelab.org/books/<archive_id>\",\n    \"BookPage\": \"https://api.archivelab.org/books/<archive_id>/pages/<page>\",\n    \"BookPages\": \"https://api.archivelab.org/books/<archive_id>/pages\",\n    \"Endpoints\": \"https://api.archivelab.org/books\",\n    \"SearchInside\": \"https://api.archivelab.org/books/<archive_id>/searchinside\",\n    \"WordRegions\": \"https://api.archivelab.org/books/<archive_id>/pages/<page>/ocr\"\n\n}"}]},"settings":"","examples":{"codes":[]},"method":"get","auth":"required","params":[],"url":"/books"},"isReference":false,"order":3,"body":"The experimental Book APIs are an attempt to wrap existing Archive.org services & API endpoints to provide a single, coherent experience which is more intuitive, discoverable, and expressive.\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Retrieving Book Metadata\"\n}\n[/block]\nTo retrieve metadata for a book item, you can use the following URL which does the equivalent of https://archive.org/metadata/:itemid. The difference is, the syntax below allows you to do a lot more than just get metadata. By adding additional arguments to the url, you can search inside the book, get book pages, retrieve annotations, and more!\n\nhttps://api.archivelab.org/books/:itemid\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Searching Inside a Book\"\n}\n[/block]\nThe search API allows you to find where text occurs within a book. This metadata includes the page, the surrounding text / the section of the page which matched, and coordinates detailing the physical region on the book page which exactly matched.\n\nhttps://api.archivelab.org/books/:itemid/searchinside?q=:query\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://api.archivelab.org/books/platowithenglish04platuoft/searchinside?q=plato\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Retrieving Book Pages\"\n}\n[/block]\nQuickly fetch the full resolution book page image as a .jpg for an Archive.org text. Note: If you need the image in a different file format (.gif, .png, .tiff, etc), a different resolution, or if you only want a region of the image (not the whole thing) consider using our experimental IIIF API (http://iiif.archivelab.org/iiif/documentation)\n\nhttps://api.archivelab.org/books/:itemid/pages -- returns a list of all available page numbers\nhttps://api.archivelab.org/books/:itemid/pages/:page -- returns a single page as an image (.jpg)\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Retrieving a Book Page's Annotations\"\n}\n[/block]\nGet all OpenAnnotations for an Archive.org book page using the following endpoint:\n\nhttps://api.archivelab.org/books/:itemid/pages/:page/annotations\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://api.archivelab.org/books/platowithenglish04platuoft/pages/1/annotations\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThe Archive Lab has created an experimental OpenAnnotations service  (see: www.openannotation.org) which allows users to select regions of Archive.org images and book pages and mark/tag them with notes called \"annotations\". An annotation can be thought of as similar to using a sticky note to comment about a region of a work.\n\nThe OpenAnnotation server is located at https://pragma.archivelab.org and the code is available, open source, at https://github.com/ArchiveLabs/pragma.archivelab.org.\n\n**Why Annotate?**\nAnnotations aren't **just** cool because they enable you to comment about an interesting line of a book. They're not just because they can give you a way to contribute a correction to a typo. \nOpen Annotations are also powerful mechanisms which can be used to bring a static image to life. Using annotations, you can single out a country on a map, or a part of a table of contents in a book, and make them interactive by assigning them events. Annotations essentially give you the ability to augment any image or book make to make it as rich and as interactive as a webpage. Imagine being able to click on a quote in a book and having this trigger an action to pull up the book where this quote originated, side by side the book you're reading (i.e. Ted Nelson's idea of \"transclusion\").\n\n**How do I make an annotation?**\nAnnotations can be made in two ways.\n\nThe first method requires manually making a HTTP POST directly to the OpenAnnotation server (as described in the service's documentation at https://github.com/ArchiveLabs/pragma.archivelab.org). \nIIIF OpenAnnotations are specifically created by POSTing to the https://pragma.archivelab.org/annotations endpoint (as opposed to the server root).\n\nThe second method uses a GUI and the Mirador viewer to assist the user in selecting a region, crafting the http request, and automatically associating the annotation with the right book page and saving the annotation in the database.\n\n**Using Mirador to View & Make Annotations*\n\nFirst, open an Archive.org book (e.g. platowithenglish04platuoft) using the Archive Lab's experimental IIIF service endpoint (e.g. https://iiif.archivelab.org/platowithenglish04platuoft). This will open the book using the IIIF-backed Mirador reader. From here, you should see a button on the top-left corner of the interface which looks like a callout bubble. Clicking this will enable you to see what annotations have been made on this page, as well as tools for creating and saving a new annotation.\n\n**Guess What!**\nHere's a fun fact, OpenAnnotations aren't limited to images and book pages. They can also be used to annotate html pages. We're working on an experimental API to save annotated webpages using the Wayback Machine. Interested in helping? Email mek:::at:::archive.org and request an invitation to join the Archive Labs team -- anyone is welcome!\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Retrieving Book Page's OCR\"\n}\n[/block]\nThe following endpoint can be used to retrieve the OCR results for the specified book pages. These OCR results include all the text which appears within the page, as well as the region coordinates where the text occurs within the book page image:\n\nhttps://api.archivelab.org/books/:itemid/pages/:page/ocr\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Retrieving Manifests\"\n}\n[/block]\n**IA Manifests**\nYou can get the archive.org IA Book Manifest through the following shortcut url:\nhttps://api.archivelab.org/books/:itemid/ia_manifest\n\n**IIIF Manifests**\nYou can get the IIIF Manifest for an archive.org book item using the following link or directly through the Archive Labs IIIF API (e.g. https://iiif.archivelab.org/iiif/:itemid/manifest.json):\n\nhttps://api.archivelab.org/books/:itemid/iiif_manifest","excerpt":"","slug":"experimental-book-apis-1","type":"endpoint","title":"Experimental Book APIs"}

getExperimental Book APIs


Definition

{{ api_url }}{{ page_api_url }}

Result Format


Documentation

The experimental Book APIs are an attempt to wrap existing Archive.org services & API endpoints to provide a single, coherent experience which is more intuitive, discoverable, and expressive. [block:api-header] { "type": "get", "title": "Retrieving Book Metadata" } [/block] To retrieve metadata for a book item, you can use the following URL which does the equivalent of https://archive.org/metadata/:itemid. The difference is, the syntax below allows you to do a lot more than just get metadata. By adding additional arguments to the url, you can search inside the book, get book pages, retrieve annotations, and more! https://api.archivelab.org/books/:itemid [block:api-header] { "type": "get", "title": "Searching Inside a Book" } [/block] The search API allows you to find where text occurs within a book. This metadata includes the page, the surrounding text / the section of the page which matched, and coordinates detailing the physical region on the book page which exactly matched. https://api.archivelab.org/books/:itemid/searchinside?q=:query [block:code] { "codes": [ { "code": "curl https://api.archivelab.org/books/platowithenglish04platuoft/searchinside?q=plato", "language": "curl" } ] } [/block] [block:api-header] { "type": "get", "title": "Retrieving Book Pages" } [/block] Quickly fetch the full resolution book page image as a .jpg for an Archive.org text. Note: If you need the image in a different file format (.gif, .png, .tiff, etc), a different resolution, or if you only want a region of the image (not the whole thing) consider using our experimental IIIF API (http://iiif.archivelab.org/iiif/documentation) https://api.archivelab.org/books/:itemid/pages -- returns a list of all available page numbers https://api.archivelab.org/books/:itemid/pages/:page -- returns a single page as an image (.jpg) [block:api-header] { "type": "get", "title": "Retrieving a Book Page's Annotations" } [/block] Get all OpenAnnotations for an Archive.org book page using the following endpoint: https://api.archivelab.org/books/:itemid/pages/:page/annotations [block:code] { "codes": [ { "code": "curl https://api.archivelab.org/books/platowithenglish04platuoft/pages/1/annotations", "language": "text" } ] } [/block] The Archive Lab has created an experimental OpenAnnotations service (see: www.openannotation.org) which allows users to select regions of Archive.org images and book pages and mark/tag them with notes called "annotations". An annotation can be thought of as similar to using a sticky note to comment about a region of a work. The OpenAnnotation server is located at https://pragma.archivelab.org and the code is available, open source, at https://github.com/ArchiveLabs/pragma.archivelab.org. **Why Annotate?** Annotations aren't **just** cool because they enable you to comment about an interesting line of a book. They're not just because they can give you a way to contribute a correction to a typo. Open Annotations are also powerful mechanisms which can be used to bring a static image to life. Using annotations, you can single out a country on a map, or a part of a table of contents in a book, and make them interactive by assigning them events. Annotations essentially give you the ability to augment any image or book make to make it as rich and as interactive as a webpage. Imagine being able to click on a quote in a book and having this trigger an action to pull up the book where this quote originated, side by side the book you're reading (i.e. Ted Nelson's idea of "transclusion"). **How do I make an annotation?** Annotations can be made in two ways. The first method requires manually making a HTTP POST directly to the OpenAnnotation server (as described in the service's documentation at https://github.com/ArchiveLabs/pragma.archivelab.org). IIIF OpenAnnotations are specifically created by POSTing to the https://pragma.archivelab.org/annotations endpoint (as opposed to the server root). The second method uses a GUI and the Mirador viewer to assist the user in selecting a region, crafting the http request, and automatically associating the annotation with the right book page and saving the annotation in the database. **Using Mirador to View & Make Annotations* First, open an Archive.org book (e.g. platowithenglish04platuoft) using the Archive Lab's experimental IIIF service endpoint (e.g. https://iiif.archivelab.org/platowithenglish04platuoft). This will open the book using the IIIF-backed Mirador reader. From here, you should see a button on the top-left corner of the interface which looks like a callout bubble. Clicking this will enable you to see what annotations have been made on this page, as well as tools for creating and saving a new annotation. **Guess What!** Here's a fun fact, OpenAnnotations aren't limited to images and book pages. They can also be used to annotate html pages. We're working on an experimental API to save annotated webpages using the Wayback Machine. Interested in helping? Email mek@archive.org and request an invitation to join the Archive Labs team -- anyone is welcome! [block:api-header] { "type": "get", "title": "Retrieving Book Page's OCR" } [/block] The following endpoint can be used to retrieve the OCR results for the specified book pages. These OCR results include all the text which appears within the page, as well as the region coordinates where the text occurs within the book page image: https://api.archivelab.org/books/:itemid/pages/:page/ocr [block:api-header] { "type": "get", "title": "Retrieving Manifests" } [/block] **IA Manifests** You can get the archive.org IA Book Manifest through the following shortcut url: https://api.archivelab.org/books/:itemid/ia_manifest **IIIF Manifests** You can get the IIIF Manifest for an archive.org book item using the following link or directly through the Archive Labs IIIF API (e.g. https://iiif.archivelab.org/iiif/:itemid/manifest.json): https://api.archivelab.org/books/:itemid/iiif_manifest

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}