https://github.com/official-wizard/openlibrary-kotlin
A client for accessing openlibrary.org to query books in their database!
https://github.com/official-wizard/openlibrary-kotlin
openlibrary openlibrary-api
Last synced: 8 months ago
JSON representation
A client for accessing openlibrary.org to query books in their database!
- Host: GitHub
- URL: https://github.com/official-wizard/openlibrary-kotlin
- Owner: official-wizard
- License: agpl-3.0
- Created: 2024-08-21T07:18:49.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-12-31T06:46:42.000Z (over 1 year ago)
- Last Synced: 2025-08-23T09:22:30.341Z (8 months ago)
- Topics: openlibrary, openlibrary-api
- Language: Kotlin
- Homepage: https://openlibrary.org
- Size: 474 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
OpenLibrary.org Client for Kotlin
## Installation
To begin, import the library using jitpack.io.
You can include jitpack in your `pom.xml` by adding the following jitpack repository:
```xml
jitpack.io
https://www.jitpack.io
```
Then add this `openlibrary-kotlin` dependency to your `pom.xml` project!
```xml
com.github.official-wizard
openlibrary-kotlin
1.0.0
```
## Usage
### Basic Usage
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryClient = OpenLibraryClient(identifier).api
// access the api interface in `api`
```
### Authentication
Some endpoints require you to be authenticated, e.g. the ones for creating lists.
You can easily authenticate your client by doing the following.
```kotlin
// create client instance
val client = OpenLibraryClient(Identifier()).api
// send the authentication request
val authentication: NetworkResponse =
client.authenticate(username = "", password = "")
// an error occurred
if (authentication !is NetworkResponse.Success) {
if (authentication is NetworkResponse.ServerError) {
// the credentials you provided are most likely invalid, refer to response code for further
// information
}
if (authentication is NetworkResponse.UnknownError) {
// an unknown error occurred while authenticating, handle [authentication] result
}
// ...
return
}
val authenticationResponse: Login.Response = authentication.body
if (authenticationResponse.authenticated) {
// we've authenticated our [client], this only needs to be done once per instance
}
```
## More Examples
### Book Search
Query
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------------------------------|:----------------------|----------|
| query | String | The query you'd like to search for. | The Lord of The Rings | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchBooksByQuery(query = "The Lord of the Rings")
if (search is NetworkResponse.Success) {
val searchResult: SearchBooks.Response = search.body
// handle [searchResult] as you wish
}
```
Title
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------------------------------|:----------------------|----------|
| title | String | The title you'd like to search for. | The Lord of The Rings | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchBooksByTitle(title = "The Lord of the Rings")
if (search is NetworkResponse.Success) {
val searchResult: SearchBooks.Response = search.body
// handle [searchResult] as you wish
}
```
Author
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------------------------------|:------------|----------|
| author | String | The author you'd like to search for. | J K Rowling | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchBooksByAuthor(author = "J K Rowling")
if (search is NetworkResponse.Success) {
val searchResult: SearchBooks.Response = search.body
// handle [searchResult] as you wish
}
```
---
### Profile Search (My)
Want To Read Books
| Name | Type | Description | Example | required |
|:---------|:-------|:----------------------------------------------------------------|:--------|----------|
| username | String | The username you'd like to search for. | mokBot | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchMyWantToReadBooks(username = "mokBot")
if (search is NetworkResponse.Success) {
val searchResult: SearchMyBooks.Response = search.body
// handle [searchResult] as you wish
}
```
Currently Reading Books
| Name | Type | Description | Example | required |
|:---------|:-------|:----------------------------------------------------------------|:--------|----------|
| username | String | The username you'd like to search for. | mokBot | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchMyCurrentlyReadingBooks(username = "mokBot")
if (search is NetworkResponse.Success) {
val searchResult: SearchMyBooks.Response = search.body
// handle [searchResult] as you wish
}
```
Already Read Books
| Name | Type | Description | Example | required |
|:---------|:-------|:----------------------------------------------------------------|:--------|----------|
| username | String | The username you'd like to search for. | mokBot | yes |
| sort | String | How you'd like to sort the query, by default it uses relevancy. | new | no |
| lang | String | The users language as a two letter (ISO 639-1) language code. | en | no |
| offset | Long | offset the list by the provided amount. | 50 | no |
| page | Long | The page you'd like to traverse to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchMyAlreadyReadBooks(username = "mokBot")
if (search is NetworkResponse.Success) {
val searchResult: SearchMyBooks.Response = search.body
// handle [searchResult] as you wish
}
```
---
### Works Search
Works
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------|:--------|----------|
| olid | String | the OLID to the works. | OL01W | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchWorks(olid = "OL01W")
if (search is NetworkResponse.Success) {
val searchResult: SearchWorks.Response = search.body
// handle [searchResult] as you wish
}
```
Editions
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------|:--------|----------|
| olid | String | the OLID to the works. | OL01W | yes |
| offset | Long | offset the list by the provided amount. | 50 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchWorksEditions(olid = "OL01W")
if (search is NetworkResponse.Success) {
val searchResult: SearchWorksEditions.Response = search.body
// handle [searchResult] as you wish
}
```
Bookshelves
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------|:--------|----------|
| olid | String | the OLID to the works. | OL01W | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchWorksBookshelves(olid = "OL01W")
if (search is NetworkResponse.Success) {
val searchResult: SearchWorksBookshelves.Response = search.body
// handle [searchResult] as you wish
}
```
Ratings
| Name | Type | Description | Example | required |
|:-------|:-------|:----------------------------------------|:--------|----------|
| olid | String | the OLID to the works. | OL01W | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchWorksRatings(olid = "OL01W")
if (search is NetworkResponse.Success) {
val searchResult: SearchWorksRatings.Response = search.body
// handle [searchResult] as you wish
}
```
Isbn
| Name | Type | Description | Example | required |
|:-----|:-------|:-----------------------|:--------|----------|
| isbn | String | the isbn to the works. | 0000 | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchWorksIsbn(isbn = "0000")
if (search is NetworkResponse.Success) {
val searchResult: SearchIsbn.Response = search.body
// handle [searchResult] as you wish
}
```
---
### Authors Search
Authors
| Name | Type | Description | Example | required |
|:------|:-------|:----------------------------------------|:------------|----------|
| query | String | author's query you'd like to serch for. | J K Rowling | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchAuthors(query = "")
if (search is NetworkResponse.Success) {
val searchResult: SearchAuthors.Response = search.body
// handle [searchResult] as you wish
}
```
---
### Subjects Search
Subject
| Name | Type | Description | Example | required |
|:-----------------|:--------|:--------------------------------------|:----------|----------|
| subject | String | The subject you'd like to search for. | Love | yes |
| details | Boolean | Include details about the subject. | True | no |
| publishedInRange | String | Date range for punishments. | 2008-2010 | no |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchSubjects(subject = "love")
if (search is NetworkResponse.Success) {
val searchResult: SearchSubjects.Response = search.body
// handle [searchResult] as you wish
}
```
---
### Partners Search
Partner
| Name | Type | Description | Example | required |
|:-----------------|:--------|:--------------------------------------|:-------------|----------|
| partner | Partner | A supported partner to query with. | Partner.isbn | yes |
| partnerId | String | The partner ID to query with. | 01a0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchPartner(partner = Partner.isbn, partnerId = "01s3")
if (search is NetworkResponse.Success) {
val searchResult: SearchPartner.Response = search.body
// handle [searchResult] as you wish
}
```
Partners
| Name | Type | Description | Example | required |
|:------------|:-------|:--------------------------------------------------|:--------------------------------------------------|----------|
| requestList | String | List of partners and the IDs you'd like to query. | id:1;lccn:50006784\|olid:OL6179000M;lccn:55011330 | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchPartners(requestList = "id:1;lccn:50006784|olid:OL6179000M;lccn:55011330")
if (search is NetworkResponse.Success) {
val searchResult: Map
= search.body
// handle [searchResult] as you wish
}
```
---
### Changes Search
Recent
| Name | Type | Description | Example | required |
|:-------|:--------|:--------------------------------------|:--------|----------|
| bot | Boolean | Ignore changes made by bots. | True | no |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse, ErrorResponse.Response>
= api.searchRecentChanges()
if (search is NetworkResponse.Success) {
val searchResult: List
= search.body
// handle [searchResult] as you wish
}
```
Type
| Name | Type | Description | Example | required |
|:-------|:-------------------|:--------------------------------------|:--------------------------------|----------|
| query | SearchChangesQuery | Change type. | SearchChangesQuery(year = 2008) | yes |
| bot | Boolean | Ignore changes made by bots. | True | no |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse, ErrorResponse.Response>
= api.searchChanges(query = SearchChangesQuery(year = 2008))
if (search is NetworkResponse.Success) {
val searchResult: List
= search.body
// handle [searchResult] as you wish
}
```
---
### Lists
User
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| username | String | Open Library Username | mekBot | yes |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchUsersList(username = "mekBot")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
User (OLID)
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| username | String | Open Library Username | mekBot | yes |
| olid | String | The OLID to query. | OL1AW | yes |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchUsersList(username = "mekBot", olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUserOlidList.Response = search.body
// handle [searchResult] as you wish
}
```
Seeds
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| username | String | Open Library Username | mekBot | yes |
| olid | String | The OLID to query. | OL1AW | yes |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchUsersSeedList(username = "mekBot", olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersSeedList.Response = search.body
// handle [searchResult] as you wish
}
```
Editions
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| username | String | Open Library Username | mekBot | yes |
| olid | String | The OLID to query. | OL1AW | yes |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchUsersEditionList(username = "mekBot", olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersEditionList.Response = search.body
// handle [searchResult] as you wish
}
```
Subjects
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| username | String | Open Library Username | mekBot | yes |
| olid | String | The OLID to query. | OL1AW | yes |
| limit | Int | Limit the amount of results to return | 50 | no |
| offset | Int | Offset the results to jump to. | 0 | no |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchUsersSubjectsList(username = "mekBot", olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersSubjectsList.Response = search.body
// handle [searchResult] as you wish
}
```
OLID Books
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| olid | String | The OLID to query. | OL1AW | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchOlidBooksList(olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
Works
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| olid | String | The OLID to query. | OL1AW | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchOlidWorksList(olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
Authors
| Name | Type | Description | Example | required |
|:---------|:-------|:--------------------------------------|:--------|----------|
| olid | String | The OLID to query. | OL1AW | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchOlidAuthorsList(olid = "OL01L")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
Place (location)
| Name | Type | Description | Example | required |
|:---------|:-------|:----------------------------|:--------------|----------|
| location | String | The location to search for. | san_francisco | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchSubjectsPlaceList(location = "san_francisco")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
Query
| Name | Type | Description | Example | required |
|:------|:-------|:-------------------------|:--------|----------|
| query | String | The query to search for. | book | yes |
**Example**
```kotlin
val identifier: Identifier = Identifier("")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse
= api.searchQueryList(query = "book")
if (search is NetworkResponse.Success) {
val searchResult: SearchUsersList.Response = search.body
// handle [searchResult] as you wish
}
```
### Update Lists
Create List
> A call to `createList` in this manner will will update a pre-existing list with the details provided!
> **NOTE** You must have the client authenticated to do this!
**Available Parameters**
| Name | Type | Description | Example |
|:-----------|:-------------------|:-----------------------------------------------------|:---------|
| username | String | The username authenticated for the session | username |
| olid | String | The OLID (Open Library ID) of the list | OL01L |
| createList | CreateList.Request | The request object with details to create list with. | N/A |
**Example**
```kotlin
// create client instance
val client = OpenLibraryClient(Identifier()).api
// send the authentication request
val authentication: NetworkResponse =
client.authenticate(username = "", password = "")
// an error occurred
if (authentication !is NetworkResponse.Success) {
if (authentication is NetworkResponse.ServerError) {
// the credentials you provided are most likely invalid, refer to response code for further
// information
}
if (authentication is NetworkResponse.UnknownError) {
// an unknown error occurred while authenticating, handle [authentication] result
}
// ...
return
}
val authenticationResponse: Login.Response = authentication.body
if (authenticationResponse.authenticated) {
// we've authenticated our [client], this only needs to be done once per instance
// make sure we have a valid username to work with
val username = authenticationResponse.username
if (username != null) {
// send request to server
val createList = client.createList(
username = username,
createList = CreateList.Request(
"",
""
)
)
if (createList !is NetworkResponse.Success) {
// handle errors
return
}
// handle our result
val result: CreateList.Response = createList.body
}
}
```