Global Contents
What does the Global Contents Endpoint do?
The Global Contents Endpoint retrieves paginated Hoopla records, and all title-specific metadata, for all records or country-specific records. This endpoint is not library-specific, so it is ideal for an initial Hoopla ingestion or a catalog refresh. You are also able to either call for the full dataset or a delta. The latter allows for catalog additions or removals since the last sync, or for a certain timeframe.
This endpoint is used in tandem with the Library Entitlements endpoint and will allow a partner to call the Hoopla Partner API for only the content they need rather than calling the API daily for millions of titles.
Using the Global Contents Endpoint
When a library decides to turn on their Hoopla API catalog integration, their catalog partner will likely run a full title ingestion using the Global Contents 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.
When it comes to the license type field, instant titles will show up as PPU(pay-per-use) and flex titles will show up as PERPETUAL.
Global Contents Endpoint Documentation
GET: /api/v1/global-contents
Response Class: (Status 200)
Model Schema
{
"metadata": {
"totalCount": 1073741824,
"nextStartToken": "string",
"warnings": [
"string"
]
},
"data": {
"additionalProp1": [
{
"id": 9007199254740991,
"titleId": 9007199254740991,
"format": "string",
"title": "string",
"subtitle": "string",
"seriesName": "string",
"seriesNumber": 1073741824,
"seasonNumber": 1073741824,
"episodeNumber": 1073741824,
"upc": "string",
"isbn": "string",
"isParentalAdvisory": true,
"isDemo": true,
"containsProfanity": true,
"duration": "string",
"synopsis": "string",
"releaseYear": "string",
"isAbridged": true,
"isEdited": true,
"isForChildren": true,
"language": "string",
"subtitleLanguage": "string",
"dubLanguage": "string",
"artist": "string",
"publisher": "string",
"pages": 1073741824,
"url": "string",
"coverImageUrl": "string",
"products": [
{
"productId": 9007199254740991,
"licenseType": "string"
}
],
"ratings": [
{
"countryCode": "string",
"ratingValue": "string"
}
],
"ppuPrices": [
{
"countryCode": "string",
"ppuPrice": 0
}
],
"isFiction": true,
"countryCodes": [
"string"
],
"genres": [
"string"
],
"segments": [
{
"segmentNumber": 1073741824,
"name": "string",
"seconds": 1073741824
}
],
"artists": [
{
"name": "string",
"relationship": "string",
"artistFormal": "string"
}
]
}
],
"additionalProp2": [
{
"id": 9007199254740991,
"titleId": 9007199254740991,
"format": "string",
"title": "string",
"subtitle": "string",
"seriesName": "string",
"seriesNumber": 1073741824,
"seasonNumber": 1073741824,
"episodeNumber": 1073741824,
"upc": "string",
"isbn": "string",
"isParentalAdvisory": true,
"isDemo": true,
"containsProfanity": true,
"duration": "string",
"synopsis": "string",
"releaseYear": "string",
"isAbridged": true,
"isEdited": true,
"isForChildren": true,
"language": "string",
"subtitleLanguage": "string",
"dubLanguage": "string",
"artist": "string",
"publisher": "string",
"pages": 1073741824,
"url": "string",
"coverImageUrl": "string",
"products": [
{
"productId": 9007199254740991,
"licenseType": "string"
}
],
"ratings": [
{
"countryCode": "string",
"ratingValue": "string"
}
],
"ppuPrices": [
{
"countryCode": "string",
"ppuPrice": 0
}
],
"isFiction": true,
"countryCodes": [
"string"
],
"genres": [
"string"
],
"segments": [
{
"segmentNumber": 1073741824,
"name": "string",
"seconds": 1073741824
}
],
"artists": [
{
"name": "string",
"relationship": "string",
"artistFormal": "string"
}
]
}
],
"additionalProp3": [
{
"id": 9007199254740991,
"titleId": 9007199254740991,
"format": "string",
"title": "string",
"subtitle": "string",
"seriesName": "string",
"seriesNumber": 1073741824,
"seasonNumber": 1073741824,
"episodeNumber": 1073741824,
"upc": "string",
"isbn": "string",
"isParentalAdvisory": true,
"isDemo": true,
"containsProfanity": true,
"duration": "string",
"synopsis": "string",
"releaseYear": "string",
"isAbridged": true,
"isEdited": true,
"isForChildren": true,
"language": "string",
"subtitleLanguage": "string",
"dubLanguage": "string",
"artist": "string",
"publisher": "string",
"pages": 1073741824,
"url": "string",
"coverImageUrl": "string",
"products": [
{
"productId": 9007199254740991,
"licenseType": "string"
}
],
"ratings": [
{
"countryCode": "string",
"ratingValue": "string"
}
],
"ppuPrices": [
{
"countryCode": "string",
"ppuPrice": 0
}
],
"isFiction": true,
"countryCodes": [
"string"
],
"genres": [
"string"
],
"segments": [
{
"segmentNumber": 1073741824,
"name": "string",
"seconds": 1073741824
}
],
"artists": [
{
"name": "string",
"relationship": "string",
"artistFormal": "string"
}
]
}
]
}
} Response Messages
| HTTP Status Code | Reason |
|---|---|
| 401 | expected response when requesting an access token with an invalid Authorization header |
Considerations for using the Global Contents Endpoint
The Global Contents endpoint is best used in tandem with the Library Entitlements endpoint. The partner can call the Hoopla Partner API the content they need, specifying the country the library services, calling for additions and/or removals since the last time they used this specific endpoint (calling for a delta), etc. The main focus of the Global Contents endpoint is allowing the partner have access to everything Hoopla has to offer and then only formally request what they need.
There are no required fields in this endpoint request.
Response Key Attributes
- id: Unique content identifier
- titleId: Reference identifier for the title
- url: Content URL or web reference
- coverImageUrls: Country-specific cover image URLs
- format: Content type (e.g., movie, ebook), formerly kind
- artist: Primary artist; author, musician, etc
- artists: Detailed artist information; narrator, illustrator, etc
- licenseType: License type, formerly purchaseModel
- countryCodes: Supported country codes
Requests and Responses
Example Request
https://hoopla-api.hoopladigital.com/api/v1/global-contents?limit=1
curl -X 'GET' \
'https://hoopla-api.hoopladigital.com/api/v1/global-contents?limit=1' \
-H 'accept: application/json' \
-H 'Authorization: Bearer 86b62419-762b-4b21-8c29-2331873a8169' Example Response
{
"id": 10023563,
"titleId": 10023563,
"format": "AUDIOBOOK",
"title": "Clifford the Big Red Dog",
"seriesName": "Clifford the Big Red Dog (French)",
"upc": "",
"isbn": "9781338246599",
"isParentalAdvisory": false,
"isDemo": false,
"containsProfanity": false,
"duration": "3m 28s",
"synopsis": "This is how it all began - in 1963, Norman Bridwell published his very first Clifford book, and kids have loved Clifford ever since. He's an adorable dog whose well-meaning bumblings have great kid appeal. Clifford is Emily Elizabeth's, and everyone's, favorite big red dog!",
"releaseYear": "2017",
"isAbridged": false,
"isEdited": false,
"isForChildren": true,
"language": "FRENCH",
"artist": "Norman Bridwell",
"publisher": "Scholastic Inc.",
"url": "https://www.hoopladigital.com/title/10023563",
"coverImageUrl": "https://cover.hoopladigital.com/sca_9780545438681_270.jpeg",
"products": [
{
"productId": 16761575,
"licenseType": "PERPETUAL"
},
{
"productId": 10023563,
"licenseType": "PPU"
}
],
"ppuPrices": [
{
"AU": 0.86
},
{
"CA": 0.76
},
{
"NZ": 0.9
},
{
"US": 0.55
}
],
"isFiction": true,
"countryCodes": [
"AU",
"CA",
"NZ",
"US"
],
"artists": [
{
"name": "Norman Bridwell",
"artistFormal": "Bridwell, Norman",
"relationship": "AUTHOR"
},
{
"name": "Emna Belgasmi",
"artistFormal": "Belgasmi, Emna",
"relationship": "READER"
}
]
}, ← Return home