Search

What does the Search Endpoint do?

The Search endpoint allows you to retrieve real-time search results from Hoopla, based on a specific search term, i.e. what a patron may search for in a library catalog. This endpoint replicates searching on the Hoopla platform.

Using the Seach Endpoint

Checking the results for a patron catalog search is the most common use case for this endpoint. You are able to enter anything in the search term field – a topic, a title, an author, a publisher, etc. You can also narrow the results by kind (format), limit the number of search results, choose a purchase model (license type), and also see results with kids' mode enabled or disabled.

Search Endpoint Documentation

GET: /api/v1/libraries/{libraryId}/search

Response Class (Status 200)

Model Schema

{ 
  "found": 0, 
  "titles": [ 
    { 
      "titleId": 0, 
      "title": "string", 
      "subtitle": "string", 
      "synopsis": "string", 
      "kind": "string", 
      "artist": "string", 
      "demo": true, 
      "pa": true, 
      "edited": true, 
      "year": 0, 
      "duration": 0, 
      "pages": 0, 
      "children": true, 
      "readAlong": true, 
      "fiction": true, 
      "abridged": true, 
      "profanity": true, 
      "upc": "string", 
      "isbn": "string", 
      "language": "string", 
      "subtitleLanguage": "string", 
      "dubLanguage": "string", 
      "purchaseModel": "string", 
      "fixedLayout": true, 
      "series": "string", 
      "rating": "string", 
      "publisher": "string", 
      "url": "string", 
      "coverImageUrl": "string", 
      "episodes": [ 
        { 
          "id": "string", 
          "episode": 0, 
          "title": "string", 
          "synopsis": "string", 
          "duration": 0 
        } 
      ], 
      "segments": [ 
        { 
          "segmentNumber": 0, 
          "name": "string", 
          "seconds": 0 
        } 
      ], 
      "genres": [ 
        { 
          "name": "string" 
        } 
      ], 
      "artists": [ 
        { 
          "name": "string", 
          "relationship": "string", 
          "artistFormal": "string" 
        } 
      ] 
    } 
  ] 
} 

Response Messages

HTTP Status CodeReason
401expected response when requesting search results with an invalid Authorization header

Example Requests and Responses

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/search?q=Harry%20Potter%20and%20the%20Goblet%20of%20Fire&offset=0&limit=2 

curl -X GET --header 'Accept: application/json' --header 'kids-mode: false' --header 'Authorization: Bearer e42fe129-cdd9-4e6a-a33b-91f56ab6d8c5' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/search?q=Harry%20Potter%20and%20the%20Goblet%20of%20Fire&offset=0&limit=2'

Example Response

{ 
  "found": 246, 
  "titles": [ 
    { 
      "titleId": 17028426, 
      "title": "Harry Potter and the Goblet of Fire", 
      "synopsis": "Stephen Fry brings the richness of these magical stories to life in the original British recordings, available for the first time in the United States and Canada.\n\n'There will be three tasks, spaced throughout the school year, and they will test the champions in many different ways ... their magical prowess - their daring - their powers of deduction - and, of course, their ability to cope with danger.'\n\n\n\nTreat your ears to a performance so rich and captivating you'll imagine yourself in the halls of Hogwarts. Wherever you listen, the unmistakable voice of Stephen Fry is guaranteed to guide you ever more deeply into this magical story and transport you to the heart of the adventure.\n\nThe Triwizard Tournament is to be held at Hogwarts. Only wizards who are over seventeen are allowed to enter - but that doesn't stop Harry dreaming that he will win the competition. Then at Hallowe'en, when the Goblet of Fire makes its selection, Harry is amazed to find his name is one of those that the magical cup picks out. He will face death-defying tasks, dragons and Dark wizards, but with the help of his best friends, Ron and Hermione, he might just make it through - alive!\n\nTheme music composed by James Hannigan.\n\n\n\nHaving become classics of our time, the Harry Potter stories never fail to bring comfort and escapism. With their message of hope, belonging and the enduring power of truth and love, the story of the Boy Who Lived continues to delight generations of new listeners.", 
      "kind": "AUDIOBOOK", 
      "artist": "J. K. Rowling", 
      "demo": false, 
      "pa": false, 
      "edited": false, 
      "year": 2024, 
      "duration": 75300, 
      "children": true, 
      "readAlong": false, 
      "fiction": true, 
      "abridged": false, 
      "profanity": false, 
      "isbn": "9781789392364", 
      "language": "ENGLISH", 
      "purchaseModel": "INSTANT", 
      "fixedLayout": false, 
      "series": "Harry Potter Narrated by Stephen Fry", 
      "rating": "", 
      "publisher": "Pottermore Publishing", 
      "url": "https://www.hoopladigital.com/title/17028426", 
      "coverImageUrl": "https://cover.hoopladigital.com/csp_9781789392364_270.jpeg", 
      "episodes": [], 
      "genres": [ 
        { 
          "name": "Action & Adventure" 
        }, 
        { 
          "name": "Children's Fiction" 
        } 
      ], 
      "artists": [ 
        { 
          "name": "J. K. Rowling", 
          "relationship": "AUTHOR", 
          "artistFormal": "Rowling, J. K." 
        }, 
        { 
          "name": "Stephen Fry", 
          "relationship": "READER", 
          "artistFormal": "Fry, Stephen" 
        }, 
        { 
          "name": "J. K. Rowling", 
          "relationship": "AUTHOR", 
          "artistFormal": "Rowling, J. K." 
        }, 
        { 
          "name": "Stephen Fry", 
          "relationship": "READER", 
          "artistFormal": "Fry, Stephen" 
        } 
      ] 
    }, 
    { 
      "titleId": 13169863, 
      "title": "Harry Potter and the Goblet of Fire", 
      "synopsis": "'There will be three tasks, spaced throughout the school year, and they will test the champions in many different ways ... their magical prowess - their daring - their powers of deduction - and, of course, their ability to cope with danger.'\n\nThe Triwizard Tournament is to be held at Hogwarts. Only wizards who are over seventeen are allowed to enter - but that doesn't stop Harry dreaming that he will win the competition. Then at Hallowe'en, when the Goblet of Fire makes its selection, Harry is amazed to find his name is one of those that the magical cup picks out. He will face death-defying tasks, dragons and Dark wizards, but with the help of his best friends, Ron and Hermione, he might just make it through - alive!", 
      "kind": "EBOOK", 
      "artist": "J. K. Rowling", 
      "demo": false, 
      "pa": false, 
      "edited": false, 
      "year": 2015, 
      "duration": 0, 
      "pages": 752, 
      "children": true, 
      "readAlong": false, 
      "fiction": true, 
      "abridged": false, 
      "profanity": false, 
      "isbn": "9781781100523", 
      "language": "ENGLISH", 
      "purchaseModel": "INSTANT", 
      "fixedLayout": false, 
      "series": "Harry Potter", 
      "rating": "", 
      "publisher": "Pottermore Publishing", 
      "url": "https://www.hoopladigital.com/title/13169863", 
      "coverImageUrl": "https://cover.hoopladigital.com/csp_9781781100523_270.jpeg", 
      "episodes": [], 
      "genres": [ 
        { 
          "name": "Fantasy" 
        }, 
        { 
          "name": "Action & Adventure" 
        }, 
        { 
          "name": "Children's Fiction" 
        } 
      ], 
      "artists": [ 
        { 
          "name": "J. K. Rowling", 
          "relationship": "AUTHOR", 
          "artistFormal": "Rowling, J. K." 
        }, 
        { 
          "name": "J. K. Rowling", 
          "relationship": "AUTHOR", 
          "artistFormal": "Rowling, J. K." 
        } 
      ] 
    } 
  ] 
} 

← Return home