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
}

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
    }
}

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.idea		.idea
src		src
.gitignore		.gitignore
README.md		README.md
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

OpenLibrary.org Client for Kotlin

Installation

Usage

Basic Usage

Authentication

More Examples

Book Search

Profile Search (My)

Works Search

Authors Search

Subjects Search

Partners Search

Changes Search

Lists

Update Lists

About

Releases 1

Packages

Languages

official-wizard/openlibrary-kotlin

Folders and files

Latest commit

History

Repository files navigation

OpenLibrary.org Client for Kotlin

Installation

Usage

Basic Usage

Authentication

More Examples

Book Search

Profile Search (My)

Works Search

Authors Search

Subjects Search

Partners Search

Changes Search

Lists

Update Lists

About

Topics

Resources

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages