Data Extraction

What does the Data Extraction Endpoint do?

The Data Extraction Endpoint retrieves Hoopla title metadata by calling to check a library’s metadata fields—including title, author, format, and many others instantaneously. 

Using this endpoint boosts the quality of patron discoverability by ensuring that your catalog is up to date with the most detailed title information. This improved discoverability connects your patrons to titles that serve many interests or lifestyles when visiting your library’s website.

Using the Data Extraction Endpoint

Checking whether a certain title is active at a given library is an effective use case for calling the Data Extraction Endpoint. It is important to keep in mind that metadata is provided by the publisher, so not all titles will automatically contain data in every field. 

Data Extraction Endpoint Documentation

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

Response Class: (Status 200)

Model Schema

DataExtractionResponse2 {
  nextStartToken (integer, optional),
  titles (Array[Content], optional)
}
Content {
  id (integer, optional),
  titleId (integer, optional),
  active (boolean, optional),
  title (string, optional),
  subtitle (string, optional),
  titleTitle (string, optional),
  series (string, optional),
  season (integer, optional),
  episode (integer, optional),
  upc (string, optional),
  isbn (string, optional),
  duration (string, optional),
  pa (boolean, optional),
  demo (boolean, optional),
  profanity (boolean, optional),
  synopsis (string, optional),
  year (integer, optional),
  rating (string, optional),
  abridged (boolean, optional),
  edited (boolean, optional),
  children (boolean, optional),
  url (string, optional),
  coverImageUrl (string, optional),
  segments (Array[Segment], optional),
  kind (string, optional),
  publisher (string, optional),
  language (string, optional),
  subtitleLanguage (string, optional),
  dubtitleLanguage (string, optional),
  artist (string, optional),
  artists (Array[Artist], optional),
  genres (Array[string], optional),
  price (number, optional),
  pages (integer, optional),
  fiction (boolean, optional),
  purchaseModel (string, optional)
}
Segment {
  segmentNumber (integer, optional),
  name (string, optional),
  seconds (integer, optional)
}
Artist {
  name (string, optional),
  relationship (string, optional),
  artistFormal (string, optional)
}

Response Messages

Considerations for using the Data Extraction Endpoint

libraryIDis a unique identifier for each library. It is used to ensure that the collection returned properly reflects any regional and library-specific lending policies, impacting content availability to that library’s patrons.

The content is delivered in batches, a limitation set by a third party, so multiple calls must be performed in order to retrieve the full collection.

The response will include a “nextStartToken”, which should be used in subsequent calls to pick up where you left off. “nextStartToken” will not be present in the last call, indicating that the full catalog has been retrieved.

For deltas, input a unix value of your last call in the startToken field and we will deliver data reflecting any/all changes that have taken place since.

Key Attributes

• “active” - this boolean indicates whether a title is available (T) to those library patrons or not (F)
• “artistFormal” - reflects artist/author name in standard catalog format of lastName, firstName
• “season” / “episode” - television content on hoopla circulates episodically, so we will send a unique record for each episode
  • “id” - for the first episode of a television series, for example, the “id” will always match the “titleId”
  • “titleId” - subsequent episodes will all have a unique “titleId”,whereas the “id” will remain constant

Requests and Responses

Example Request

http://hoopla-api.hoopladigital.com/api/v1/libraries/7/content 
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer b810e81d-55d6-4ea4-aedf-9ed4eb996770' --header 'ws-api: 2.1' 'http://hoopla-api.hoopladigital.com/api/v1/libraries/7/content' 

Example Response

{ 
      "id": 10023346, 
      "titleId": 10023347, 
      "active": false, 
      "title": "Bill Nye the Science Guy®: Earth's Crust", 
      "titleTitle": "Bill Nye the Science Guy - Season 1", 
      "series": "Bill Nye the Science Guy", 
      "season": 1, 
      "episode": 2, 
      "upc": "", 
      "isbn": "", 
      "duration": "26m 0s", 
      "pa": false, 
      "demo": false, 
      "profanity": false, 
      "synopsis": "This episode finds Bill Nye going to the depths of the Earth (literally) to explain how the Earth's surface and its inner mantle differ.", 
      "year": 2002, 
      "rating": "YC", 
      "abridged": false, 
      "edited": false, 
      "children": true, 
      "url": "https://www.hoopladigital.com/title/10023347", 
      "coverImageUrl": "https://cover.hoopladigital.com/dsn_786936796810d_270.jpeg", 
      "segments": [], 
      "kind": "TELEVISION", 
      "publisher": "Disney Educational Productions", 
      "language": "ENGLISH", 
      "artist": "Bill Nye", 
      "artists": [ 
        { 
          "name": "Bill Nye", 
          "relationship": "ACTOR", 
          "artistFormal": "Nye, Bill" 
        }, 
        { 
          "name": "Erren Gottlieb", 
          "relationship": "DIRECTOR", 
          "artistFormal": "Gottlieb, Erren" 
        }, 
        { 
          "name": "James McKenna", 
          "relationship": "DIRECTOR", 
          "artistFormal": "McKenna, James" 
        } 
      ], 
      "genres": [ 
        "Educational", 
        "Family" 
      ], 
      "price": 1.05, 
      "fiction": false, 
      "purchaseModel": "INSTANT" 
    }