Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

A client for accessing openlibrary.org to query books in their database!

License

Notifications You must be signed in to change notification settings

official-wizard/openlibrary-kotlin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

History

41 Commits

Repository files navigation

OpenLibrary API Icon

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:

<repository>
 <id>jitpack.io</id>
 <url>https://www.jitpack.io</url>
</repository>

Then add this openlibrary-kotlin dependency to your pom.xml project!

<dependency> 
 <groupId>com.github.official-wizard</groupId> 
 <artifactId>openlibrary-kotlin</artifactId> 
 <version>1.0.0</version>
</dependency>

Usage

Basic Usage

val identifier: Identifier = Identifier("<client user agent>")
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.

// create client instance
val client = OpenLibraryClient(Identifier()).api
// send the authentication request
val authentication: NetworkResponse<Login.Response, Unit> =
 client.authenticate(username = "<email>", password = "<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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchBooks.Response, SearchBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchBooks.Response, SearchBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchBooks.Response, SearchBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchMyBooks.Response, SearchMyBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchMyBooks.Response, SearchMyBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchMyBooks.Response, SearchMyBooks.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchWorks.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchWorksEditions.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchWorksBookshelves.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchWorksRatings.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchIsbn.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchAuthors.Response, SearchAuthors.Response>
 = api.searchAuthors(query = "<author 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchSubjects.Response, SearchSubjects.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchPartner.Response, SearchPartner.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchPartner.Response, SearchPartner.Response>
 = api.searchPartners(requestList = "id:1;lccn:50006784|olid:OL6179000M;lccn:55011330")
if (search is NetworkResponse.Success) {
 val searchResult: Map<String, SearchPartner.Response> 
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<List<SearchChanges.Response>, ErrorResponse.Response>
 = api.searchRecentChanges()
if (search is NetworkResponse.Success) {
 val searchResult: List<SearchChanges.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<List<SearchChanges.Response>, ErrorResponse.Response>
 = api.searchChanges(query = SearchChangesQuery(year = 2008))
if (search is NetworkResponse.Success) {
 val searchResult: List<SearchChanges.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUserOlidList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersSeedList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersEditionList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersSubjectsList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

val identifier: Identifier = Identifier("<client user agent>")
val api: OpenLibraryInterface = OpenLibraryClient(identifier).api
val search: NetworkResponse<SearchUsersList.Response, ErrorResponse.Response>
 = 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

// create client instance
val client = OpenLibraryClient(Identifier()).api
// send the authentication request
val authentication: NetworkResponse<Login.Response, Unit> =
 client.authenticate(username = "<email>", password = "<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(
 "<new name>",
 "<new description>"
 )
 )
 if (createList !is NetworkResponse.Success) {
 // handle errors
 return
 }
 
 // handle our result
 val result: CreateList.Response = createList.body
 }
}

About

A client for accessing openlibrary.org to query books in their database!

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

AltStyle によって変換されたページ (->オリジナル) /