We supply a simple API to acquire excerpt links. The API includes a full feed, a delta feed for recent changes, and individual ISBN lookup.
For most integrations, the practical approach is to test your deployment first with a short-dated delta request, then fetch the full feed once your code is production-ready, and thereafter keep your catalogue up to date with overlapping delta requests.
Across these endpoints, excerpts are only returned when they are eligible for public distribution. In particular, titles with a future publication date are not returned unless they have been explicitly marked as previewable.
The Excerpt Changes Feed API provides a list of excerpts that have been added or updated since a given date.
This API is the recommended way to keep your local catalogue in sync once you have completed your initial full-feed import.
When testing a deployment, start with a short-dated delta request so that you can validate your integration against a small and recent set of changes. Once your code is production-ready, fetch the full feed, then use this delta feed with a deliberate overlap. For example, if you poll weekly, it is sensible to request the last 15 days of changes each time so that delayed jobs, retries, or temporary failures do not cause you to miss updates.
GET /discovery/api/excerpt_updates
[application/json]
Note: it is important that you set the Accept header to Accept: application/json.
| updated_since |
Returns excerpts that have been changed on/after the Can be a date or date-time in ISO 8601 format. Default: 7 days prior to the current time. Note: requests older than 14 days are currently clamped to the most recent 14 days. |
| language_code |
Filters publications to return those that have a matching language code. The language_code value should correspond to the ISO 639-1 two-letter format. If option is not passed (ie unset) then all publications will be returned regardless of their language. Default: unset Note: see section "Jellybooks Web Reader UI language" if you need to ensure the User Interface is also displayed in a preferred language. |
[application/json]
object
response_header object
generated_at datetime
page number
per_page number
count number
total_count number
excerpts array
object
isbn13 string
title string
url string
updated_at datetime
available boolean
update_reason string
[REQUEST]
curl "https://www.jellybooks.com/discovery/api/excerpt_updates?jb_discovery_api_key={api_key}&updated_since=$(date -u -d '2 days ago' +%Y-%m-%dT%H:%M:%SZ)" \
-H 'Accept: application/json' \
--compressed
[RESPONSE]
{
"response_header": {
"generated_at": "2023-03-26T20:28:13.908+00:00",
"page": 1,
"per_page": 1000000,
"count": 123,
"total_count": 123
},
"excerpts": [
{
"isbn13": "9781909954342",
"title": "Virgin & Child",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/virgin-child_9781909954342-ex/L3Leb",
"updated_at": "2023-03-23T20:24:02.038Z",
"available": true,
"update_reason": "added"
},
{
"isbn13": "9781909954410",
"title": "Angelica, Paintress of Minds",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/angelica-paintress-of-minds_9781909954410-ex/L3Leb",
"updated_at": "2023-03-21T11:48:29.132Z",
"available": false,
"update_reason": "withdrawn"
},
...
// more entries...
...
]
}
Use this endpoint when you need to check a single ISBN on demand, for example while validating one title or refreshing a single product page.
The lookup follows the same availability rules as the feeds. If a title has a future publication date and is not marked as previewable, it will not be returned.
We grant access to the API via an API key. The key can be passed as a header or URL param.
| Header | JB-Discovery-Api-Key |
| Param | ?jb_discovery_api_key={api_key} |
GET /discovery/api/excerpts/{isbn13}
[application/json]
Note: it is important that you set the Accept header to Accept: application/json.
[application/json]
object
response_header object
generated_at datetime
excerpt object
isbn13 string
title string
url string
created_at datetime
[REQUEST]
curl https://www.jellybooks.com/discovery/api/excerpts/9780241243626?jb_discovery_api_key={api_key} \
-H 'Accept: application/json' \
--compressed
[RESPONSE]
{
"response_header": {
"generated_at": "2022-05-26T11:09:52.676+00:00"
},
"excerpt": {
"isbn13": "9780241243626",
"title": "Ulysses",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/ulysses_9780241243626-ex/L3Leb",
"created_at": "2021-05-31T13:44:00.712Z"
}
}
This API returns the full list of excerpts currently available to your discovery client at the time of the request.
It is reasonable to call the full feed occasionally, especially for an initial import or for an occasional reconciliation pass. However, repeatedly processing very large result sets imposes avoidable load on both your systems and ours.
For that reason, we recommend using the delta feed for ongoing synchronisation. In the future, the full feed endpoint may be changed to paginate responses or to apply other limits.
Note: the Feed API has different default behaviour for publisher clients. By default the feed is filtered to list only those titles published by the publisher client.
All other client types (eg booksellers) will not have a publisher filter applied.
We grant access to the API via an API key. The key can be passed as a header or URL param.
| Header | JB-Discovery-Api-Key |
| Param | ?jb_discovery_api_key={api_key} |
GET /discovery/api/excerpts
[application/json]
Note: it is important that you set the Accept header to Accept: application/json.
| language_code |
Filters publications to return those that have a matching language code. The language_code value should correspond to the ISO 639-1 two-letter format. If option is not passed (ie unset) then all publications will be returned regardless of their language. Default: unset Note: see section "Jellybooks Web Reader UI language" if you need to ensure the User Interface is also displayed in a preferred language. |
[application/json]
object
response_header object
generated_at datetime
page number
per_page number
count number
total_count number
excerpts array
object
isbn13 string
title string
url string
created_at datetime
[REQUEST]
curl https://www.jellybooks.com/discovery/api/excerpts?jb_discovery_api_key={api_key} \
-H 'Accept: application/json' \
--compressed
[RESPONSE]
{
"response_header": {
"generated_at": "2022-04-25T13:21:55.742+00:00",
"page": 1,
"per_page": 1000000,
"count": 92887,
"total_count": 92887
},
"excerpts": [
{
"isbn13": "9781909954342",
"title": "Virgin & Child",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/virgin-child_9781909954342-ex/L3Leb",
"created_at": "2021-01-15T20:24:02.038Z"
},
{
"isbn13": "9781909954410",
"title": "Angelica, Paintress of Minds",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/angelica-paintress-of-minds_9781909954410-ex/L3Leb",
"created_at": "2021-01-15T20:24:27.548Z"
},
...
// thousands of entries...
...
]
}
The API lists an excerpt item per ISBN. There are many instances where we have multiple ISBNs for a given publication, eg ebook, hardback and paperback. In such instances, we output the same excerpt URL for each publication variant. For example:
...
{
"isbn13": "9780241590294",
"title": "DK Eyewitness Top 10 Provence and the Cote d'Azur",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/dk-eyewitness-top-10-provence-and-the-cote-d-azur_9780241590287-ex/bwells",
"created_at": "2022-04-13T10:01:26.894Z"
},
{
"isbn13": "9780241472194",
"title": "DK Eyewitness Top 10 Provence and the Cote d'Azur",
"url": "https://www.jellybooks.com/cloud_reader/excerpts/dk-eyewitness-top-10-provence-and-the-cote-d-azur_9780241590287-ex/bwells",
"created_at": "2022-04-13T10:01:26.894Z"
},
...
The API supplies URLs for samples that are viewed within the Jellybooks Web Reader. The Jellybooks Web Reader's interface has been translated into many languages. We leave it to clients to decide for themselves the preferred language for their needs. The default is English.
The UI language can be specified via the URL parameter locale={language_code}. Append
this parameter to the excerpt URL returned by the API. E.g.
https://www.jellybooks.com/cloud_reader/excerpts/ulysses_9780241243626-ex/L3Leb?locale=es
| Catalan | ca |
| Danish | da |
| Dutch | nl |
| English | en (default) |
| French | fr |
| German | de |
| Italian | it |
| Portuguese (Brazil) | pt-BR |
| Russian | ru |
| Spanish | es |
| Welsh | cy |