The CloudPublish API is a REST-style interface to the CloudPublish platform, outputing data in JSON format. The purpose of the API is to allow a publisher to create a front-end to the CloudPublish system. The front-end can be as simple as a catalogue listing or as complex as an ecommerce book-store.
It is important to note a few things that the CloudPublish API does not do:
- There is no customer/user database provided, as such. It is expected that you maintain your own customer-facing systems / website, and then supply a unique customer identifier to the API when referring to a specific customer (e.g., retrieving subscription data for a customer). This identifier would typically be the same ID or unique customer number as used in your own customer account database, thereby enabling you to link records effectively.
- The batch processing of PDFs into ebooks is not done via the API, although you can check the progress of ebooks by using the BookGetAll and BookGet methods.
For more information, please see the CloudPublish support pages.
The CloudPublish API is a REST-style interface. Connecting to the API is accomplished by making a GET request to the CloudPublish endpoint.
Future versions will support POST for larger requests, but currently each request is limited to 255 characters via GET.
Requests are structured as follows:
http://api.cloudpublish.co.uk/?method=MethodName&args=param%3Dvalue%26param%3Dvalue&p=YYYYY&nonce=23asd3a2f5g&h=XXXXXXXXXXXXXXXX
- Endpoint: always the same
- Method: the method you want to call (see the further documentation below)
- Args: URL-encoded parameter string, in name=value pairs, delimited by ampersand. The required and optional parameters vary based on the method.
- Publisher UID: your unique publisher UID within CloudPublish.
- Nonce: A one-time, unique code such as the output generated by PHP’s uniqid() function.
- Signature: the value XXXXXXXXXXXXXXXX is the MD5 hash produced from the concatenation of the entire URL up to (but not including) &h= and your shared secret.
Your shared secret is a key (a string of characters) known to both CloudPublish and to you, and should be kept confidential.
The value for each parameter should be URL-encoded (e.g. via the PHP urlencode() function) prior to hashing.
The entire URL cannot be longer than 255 characters.
The order of these elements is important (i.e. it must be as above).
The authentication signature is an MD5 hash of the query string, not including the initial “?” or “&h=”, concatenated with your shared secret. For example, using PHP, the hash would be generated as follows:
$query = 'method=ImprintsGet&args=imprint%3DExample%20&p=12345&nonce='.urlencode(uniqid());
$hash = md5($query . $secret);
You would then complete the URL by adding on the hash as follows:
$url = 'http://api.cloudpublish.co.uk/?' . $query . '&hash=' . $hash;
/Test
Parameters
-
test_parameter
[optional]
- any value (string)
-
format
[optional]default: json
- json
- csv
Returns
- data
-
test_response
string
Description
Returns the value of test_parameter as test_response.
Typical use
This method is useful when testing that you have integrated the API successfully.
These methods are applicable to more than one type of item.
/SubjectsGetAll
Parameters
-
subject_field
[optional]default: thema
- thema
- subject
-
start_node
[optional]default: (empty)
- subject code (string)
-
item_type
[optional]default: book
- book
- journal
- series*
- collection
-
customer_ref
[optional]
- identifier to restrict tree to subscribed items only (string)
-
format
[optional]default: json
- json
Returns
- data
-
subject_code
string
-
heading_en
string
-
heading_de
string
-
heading_fr
string
-
count_total
integer
-
count_available
integer
-
num_subscribed*
integer
Description
Returns metadata for all subjects in the catalogue.
The result field subject_code contain the value of the Thema or Subject field (depending on what is passed in the subject_field parameter), and the result field heading_en will contain the human-readable version (identical to Subject if the subject_field is Subject).
If specified, the start_node will return a tree starting at that point, rather than at the top / root level. This is mainly relevant for Thema subjects.
If the item_type is series, the tree for the books catalogue will be returned broken down by series (i.e., the number of series available in each subject/thema).
The customer_ref parameter causes the num_subscribed field of the returned data to be populated.
/SubjectsExpand
Parameters
-
thema
[mandatory]
Returns
- data
-
subjects
complex
- subjects
-
subject_code
string
-
heading_en
string
-
heading_de
string
-
heading_fr
string
Description
Expands a single Thema code into human-friendly headings, starting at the top node and working down. For example, a thema of ABC will return expansions for A, AB, and ABC.
A book typically represents a single ebook.
/BookGetAll
Parameters
-
availability
[optional]default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
- subscribed*
-
format
[optional]default: json
- json
- csv
- marc
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
customer_ref
[optional*]
- identifier for customer subscribed to returned books (string)
-
imprint
[optional]default: (empty = all)
- semicolon-delimited list of imprints
-
series
[optional]default: (empty = all)
- semicolon-delimited list of series
-
series_code
[optional]default: (empty = all)
- semicolon-delimited list of series codes
-
book_ids
[optional]default: (empty = all)
- semicolon-delimited list of book IDs
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
sort_by
[optional]default: score
- item_id
- title
- date_published
- series_volume
-
sort_order
[optional]default: ascending for title and item_id, descending for date_published
- asc
- desc
-
offset
[optional]default: 0
- offset of returned data set
*customer_ref is mandatory if availability is subscribed
Returns
- data
-
book_id
integer
-
title
string
-
subtitle
string
-
series
string
-
series_volume
string
-
series_code
string
-
authors
string (delimited by semicolon)
-
initial
character
-
edition
string
-
isbn
string
-
filename
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
date_published
date (YYYY-MM-DD)
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
cover_fullsize_url
string (url)
-
open_access
integer (1 or 0)
-
on_sale
integer (1 or 0)
-
available_online
integer (1 or 0)
-
available_download
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
unavailable
integer (1 or 0)
-
unprocessed
integer (1 or 0)
-
subscribed*
integer (2, 1 or 0)
Note that the marc return format is more complete (i.e. MARC21) and is suitable for import into library systems.
Description
Returns metadata for your catalogue (or a subset based on availability) in the specified format.
Note that a maximum of 500 results is returned. You will need to use the offset parameter to access a greater number of records (e.g., offset=250 to get up to 500 results starting at the 251st result). However, there is no restriction when using the MARC output format.
Note that "unavailable" includes withdrawn books as well as those not on sale because they are not yet processed (i.e. "unprocessed").
If available_since and/or published_since is used, this returns matching books that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated (0 = no access, 1 = full access, 2 = partial access via chapter subscription). To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Typical use
This method could be used to return an overview list of catalogue items to which a customer might have access. It could also be used to return MARC data to a specialist user (e.g. a librarian). The available_since and/or published_since parameters could be used to set up new title notifications for your users.
/BookGet
Parameters
-
id
[optional*]
- a book ID (integer)
-
isbn
[optional*]
- an isbn (string)
-
customer_ref
[optional]
- identifier for customer subscribed to returned books (string)
-
format
[optional]default: json
- json
- csv
- marc
*one (and only one) of these parameters must be supplied
Returns
- data
-
book_id
integer
-
title
string
-
subtitle
string
-
publication_type
string
-
series
string
-
series_code
string
-
series_volume
string
-
initial
character
-
edition
string
-
edition_statement
string
-
language
string
-
authors
authors (Lastname, F; Last, F)
-
author_info
string
-
editors
editors (Lastname, F; Last, F)
-
doi
string
-
isbn
string
-
replaces_isbn
string
-
replaced_by_isbn
string
-
related_isbns
string
-
filename
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
description
string
-
description_short
string
-
pages
integer
-
copyright_year
date (YYYY)
-
date_published
date (YYYY-MM-DD)
-
price_currency
string
-
price_individual
float (2dp)
-
price_institution
float (2dp)
-
date_added
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
cover_fullsize_url
string (url)
-
open_access
integer (1 or 0)
-
search_available
integer (1 or 0)
-
on_sale
integer (1 or 0)
-
availability_code
string
-
available_online
integer (1 or 0)
-
available_download
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
unavailable
integer (1 or 0)
-
unprocessed
integer (1 or 0)
-
subscribed*
integer (1 or 0)
-
num_chapters**
integer
-
num_collections***
integer
Description
Returns metadata for a single book. This returns more data than /BookGetAll.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
**This refers to the number of Chapter products relating to this Book.
***This refers to the number of collections of which this Book is a member.
Typical use
This method could be used to populate a page of details for a specific book.
/BookGetTOC
Parameters
-
id
[optional*]
- a book ID (integer)
-
isbn
[optional*]
- an isbn (string)
-
format
[optional]default: json
- json
*one (and only one) of these parameters must be supplied
Returns
- data
-
page_number
integer
-
title
string
Description
Returns the TOC (Table of Contents) for a single book, in JSON format only. Each element of the TOC is represented by a toc_entry, which in turn contains page_number and title elements.
Typical use
This method could be used to retrieve the TOC after a page has loaded, to save time on the initial page load (important, as some TOCs can be very large).
/BookGetCitation
Parameters
-
id
[mandatory]
- a book ID (integer, comma-delimited string of integers for multiple IDs)
-
style
[optional]default: apa
- apa
- mla
- ama
- turabian
- chicago
-
page_range_start
[optional]
- first page if citing a page range or a single page (integer)
-
page_range_end
[optional]
- Last page if citing a page range (integer)
-
chapter_title
[optional]
- title of a chapter or article within the book (string)
-
retrieved_from_url
[optional]
- a url if the citation is to include "retrieved from ... on ..." (current date will be used)
-
format
[optional]default: json
- json
- csv
Returns
- data
-
book_id
integer
-
style
string
-
citation
string
Description
Returns a standardised citation for a book in one of the styles shown above, optionally for a single page or page range.
/ImprintsGetAll
Parameters
-
customer_ref
[optional]
- (identifier to restrict to imprints of subscribed books only)
-
format
[optional]default: json
- json
- csv
Returns
- data
-
name
string
-
num_on_sale
integer
-
num_available_online
integer
-
num_available_download
integer
-
num_withdrawn
integer
-
num_unavailable
integer
-
num_unprocessed
integer
-
num_subscribed*
integer
Description
Returns metadata for all imprints in the catalogue.
*The customer_ref parameter causes the num_subscribed field of the returned data to be populated, and will restrict the imprints returned to only those of the books to which the specified customer is subscribed.
/ImprintGet
Parameters
-
imprint
[mandatory]
- an imprint (string)
-
customer_ref
[optional]
- (identifier to restrict to imprints of subscribed books only)
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
format
[optional]default: json
- json
- csv
Returns
- data
-
(as for /BookGetAll)
Description
Returns a list of books matching a specific imprint, with the same data structure as /BookGetAll.
/SeriesGetAll
Parameters
-
customer_ref
[optional]
- (identifier to restrict to series of subscribed books only)
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
format
[optional]default: json
- json
- csv
Returns
- data
-
name
string
-
num_on_sale
integer
-
num_available_online
integer
-
num_available_download
integer
-
num_withdrawn
integer
-
num_unavailable
integer
-
num_unprocessed
integer
-
num_subscribed*
integer
Description
Returns metadata for all series in the catalogue.
*The customer_ref parameter causes the num_subscribed field of the returned data to be populated.
The thema parameter causes only the series matching the specified Thema to be returned.
A contributor is either an author or an editor (or both). Authors are associated with books, chapters, and journal articles only. Editors are associated with books and journal issues only.
/ContributorsGetAll
Parameters
-
begins_with
[optional]default: (empty = any)
- single character or string
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
availability
[optional]default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
-
item_type
[optional]default: (empty)
- string (book|journal)
-
role
[optional]default: (empty)
- string (author|editor)
-
format
[optional]default: json
- json
- csv
Returns
- data
-
name
string
-
roles
string
-
num_open_access
integer
-
num_on_sale
integer
-
num_books_on_sale
integer
-
num_journals_on_sale
integer
-
num_withdrawn
integer
-
num_unavailable
integer
-
num_unprocessed
integer
Description
Returns metadata for all contributors in the catalogue, optionally restricting the list to just open_access contributors only, and/or to contributors of books or journals only by specifying item_type, and/or to authors/editors only by specifying the role.
/ContributorGet
Parameters
-
name
[mandatory]
- an contributor (string)
-
role
[optional]default: (empty)
- string (author|editor)
-
item_type
[optional]default: (empty)
- string (book|journal)
-
customer_ref
[optional]
- (identifier to restrict to contributors of subscribed books only)
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
availability
[optional]default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
-
format
[optional]default: json
- json
- csv
Returns
- items
-
(as for /BookGetAll)
- metadata
-
contributor
string
-
contributor_variation
string
-
num_items
integer
-
num_books
integer
-
num_journals
integer
-
num_as_author
integer
-
num_as_editor
integer
-
is_author
boolean 1/0
-
is_editor
boolean 1/0
Description
Returns a list of books (including chapters) or journals (articles and issues), according to the optional item_type and/or role, matching a specific contributor with the same data structure as /CustomerSubscriptionsGet.
The metadata section contains totals from the items section, based on the availability parameter supplied, and an indication of whether the contributor is present as an author, an editor, or both.
/AuthorsGetAll [DEPRECATED]
Parameters
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
availability
[optional]default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
-
item_type
[optional]default: (empty)
- string (book|journal)
-
format
[optional]default: json
- json
- csv
Returns
- data
-
name
string
-
num_open_access
integer
-
num_on_sale
integer
-
num_available_online
integer
-
num_available_download
integer
-
num_withdrawn
integer
-
num_unavailable
integer
-
num_unprocessed
integer
Description
This method is deprecated. Please use /ContributorsGetAll instead.
Returns metadata for all authors in the catalogue, optionally restricting the list to just open_access authors only, and/or to authors of books or journals only by specifying item_type.
/AuthorGet [DEPRECATED]
Parameters
-
author
[mandatory]
- an author (string)
-
item_type
[mandatory]default: book
- string (book|journal)
-
customer_ref
[optional]
- (identifier to restrict to authors of subscribed books only)
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
availability
[optional]default: all
- all
- on_sale
- available_online
- available_download
- withdrawn
- unavailable
- unprocessed
-
format
[optional]default: json
- json
- csv
Returns
- data
-
(as for /BookGetAll)
Description
This method is deprecated. Please use /ContributorGet instead.
Returns a list of books (including chapters) or journals (articles), according to item_type, matching a specific author with the same data structure as /CustomerSubscriptionsGet.
A chapter consists of a fragment of a book that is already in your catalogue, defined by a page range within that book. While books are added by sending ONIX metadata, chapters are created via the API. Chapters are currently only available via the online eReader.
/ChaptersGetAll
Parameters
-
availability
[optional]default: all
- all
- on_sale
- withdrawn
- subscribed
-
format
[optional]default: json
- json
- csv
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
book_id
[optional]default: (matches all books)
- book identifier, to return chapters from this book only
-
chapter_ids
[optional]default: (empty = all)
- semicolon-delimited list of chapter IDs
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
customer_ref
[optional]
- identifier for customer subscribed to returned chapters (string)
-
offset
[optional]default: 0
- offset of returned data set
Returns
- data
-
chapter_id
integer
-
book_id
integer
-
title
string
-
authors
string (delimited by semicolon)
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
date_published
date (YYYY-MM-DD)
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
cover_fullsize_url
string (url)
-
open_access
integer (1 or 0)
-
on_sale
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
unavailable
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Note that the marc return format is more complete (i.e. MARC21) and is suitable for import into library systems.
Description
Returns metadata for chapters in your catalogue (or a subset based on availability or book) in the specified format.
Note that a maximum of 500 results is returned. You will need to use the offset parameter to access a greater number of records (e.g., offset=250 to get up to 500 results starting at the 251st result). However, there is no restriction when using the MARC output format.
Note that "unavailable" includes withdrawn chapters as well as those not on sale because they are not yet processed (i.e. "unprocessed").
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
/ChapterGet
Parameters
-
id
[mandatory]
- a chapter ID (integer)
-
customer_ref
[optional]
- customer identifier (string)
-
format
[optional]default: json
- json
- csv
- marc
Returns
- data
-
chapter_id
integer
-
book_id
integer
-
title
string
-
chapter_number
integer
-
start_page
integer
-
end_page
integer
-
language
string
-
authors
authors (Lastname, F; Last, F)
-
author_info
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
series
string
-
description
string
-
wordcount
integer
-
pages
integer
-
date_published
date (YYYY-MM-DD)
-
price_currency
string
-
price_individual
float (2dp)
-
price_institution
float (2dp)
-
date_added
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
open_access
integer (1 or 0)
-
on_sale
integer (1 or 0)
-
available_online
integer (1 or 0)
-
available_download
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
unavailable
integer (1 or 0)
-
unprocessed
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for a single chapter. This returns more data than /ChaptersGetAll.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
Typical use
This method could be used to populate a page of details for a specific chapter.
/ChapterCreate
Parameters
-
book_id
[mandatory]
- book identifier (integer)
-
title
[mandatory]
- chapter title (string)
-
chapter_number
[optional]
- chapter number within the book (integer)
-
start_page
[mandatory]
- first page of the chapter, within the book (integer)
-
end_page
[mandatory]
- last page of the chapter, within the book (integer)
-
copy_metadata
[optional, default: 0]
- whether to copy the metadata from the book; if copying, other metadata is ignored (boolean 1/0)
-
language
[optional]
- ISO 639-2 language code (string)
-
authors
[optional]
- Firstname, Initial delimited by semicolons (string)
-
doi
[optional]
- chapter DOI (string)
-
thema_codes
[optional]
- Thema subject codes, delimited by semicolons (string)
-
thema_qualifiers
[optional]
- Thema qualifiers, delimited by semicolons (string)
-
subjects
[optional]
- free-text subjects, delimited by semicolons (string)
-
description
[optional]
- description (string, HTML permitted)
-
wordcount
[optional]
- (integer)
-
date_published
[optional]
- (date YYYY-MM-DD)
-
price_currency
[optional]
- pricing currency (string, e.g. GBP)
-
price_ind
[optional]
- pricing for individuals (float, 2dp)
-
price_inst
[optional]
- pricing for institutions(float, 2dp)
-
open_access
[optional, default: 0]
- whether to allow Open Access (boolean 1/0)
-
available
[optional, default: 0]
- on sale and/or available to read (boolean 1/0)
-
withdrawn
[optional, default: 0]
- withdrawn from sale (boolean 1/0)
Returns
- data
-
chapter_id
integer
Description
This method creates a chapter.
The metadata can mostly be copied from the parent book (although a data link will not be maintained) by using copy_metadata=1
/ChapterUpdate
Parameters
-
chapter_id
[mandatory]
- chapter identifier (integer)
-
title
[optional]
- chapter title (string)
-
chapter_number
[optional]
- chapter number within the book (integer)
-
start_page
[optional]
- first page of the chapter, within the book (integer)
-
end_page
[optional]
- last page of the chapter, within the book (integer)
-
language
[optional]
- ISO 639-2 language code (string)
-
authors
[optional]
- Firstname, Initial delimited by semicolons (string)
-
doi
[optional]
- chapter DOI (string)
-
thema_codes
[optional]
- Thema subject codes, delimited by semicolons (string)
-
thema_qualifiers
[optional]
- Thema qualifiers, delimited by semicolons (string)
-
subjects
[optional]
- free-text subjects, delimited by semicolons (string)
-
description
[optional]
- description (string, HTML permitted)
-
wordcount
[optional]
- (integer)
-
date_published
[optional]
- (date YYYY-MM-DD)
-
price_currency
[optional]
- pricing currency (string, e.g. GBP)
-
price_ind
[optional]
- pricing for individuals (float, 2dp)
-
price_inst
[optional]
- pricing for institutions(float, 2dp)
-
open_access
[optional, default: 0]
- whether to allow Open Access (boolean 1/0)
-
available
[optional, default: 0]
- on sale and/or available to read (boolean 1/0)
-
withdrawn
[optional, default: 0]
- withdrawn from sale (boolean 1/0)
Returns
- data
-
chapter_id
integer
Description
This method updates a chapter.
/ChapterDelete
Parameters
-
chapter_id
[mandatory]
- the chapter ID (integer)
Description
This method deletes a chapter, if the chapter is not used in a subscription, order, or transaction.
Journals are handled slightly differently to books. There are several levels in the structure:
- Journal: An entire publication. Does not exist as a readable item.
- Issue: A single issue of a Journal. Can exist as a readable item, or as a container for Articles.
- Article: A single article within a single Issue of a Journal. Can exist as a readable item or as a metadata container for use with Issue.
- Reference: A single reference or endnote, associated with a single Article.
Therefore, a Journal may have multiple Issues, each of which may have multiple Articles, each of which may have multiple References.
The corresponding files you upload depend on whether you want to provide access by issue, or by article, or both. In any case you will need to upload issues and/or articles with unique filenames.
Important: In order to ensure uniqueness of your filenames, you must incorporate an ISSN or other identifier unique to your organisation. For books, the ISBN system accomplishes this for you. We recommend naming files as follows:
- Issue: ISSNvolXissY.pdf (where X and Y are integers)
- Article: ISSNvolXissYpZ.pdf (where Z is the page number of the article)
/JournalGetAll
Parameters
-
format
[optional]default: json
- json
- csv
-
journal_ids
[optional]default: (empty = all)
- semicolon-delimited list of journal IDs
-
availability
[optional]default: all
- all
- on_sale
- withdrawn
- subscribed
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
imprint
[optional]default: (empty = all)
- semicolon-delimited list of imprints
-
customer_ref
[optional]
- identifier for customer subscribed to returned books (string)
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
offset
[optional]default: 0
- offset of returned data set
Returns
- data
-
journal_id
integer
-
title
string
-
subtitle
string
-
code
string
-
issn
string
-
issn_linking
string
-
isbn
string
-
language
string
-
url
string
-
doi
string
-
subject
string
-
keywords
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
admin_name
string
-
admin_email
string
-
editor_name
string
-
editor_email
string
-
editorial_board
string
-
place
string
-
address
string
-
country
string
-
publication_statement
string
-
description
string
-
open_access
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for your journals, or a subset based on selected parameters, in the specified format.
If available_since and/or published_since is used, this returns matching journals that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
/JournalGet
Parameters
-
format
[optional]default: json
- json
- csv
-
id
[optional*]
- a journal ID (integer)
-
isbn
[optional*]
- an isbn (string)
-
issn
[optional*]
- an issn (string)
-
code
[optional*]
- a publisher code (string)
-
customer_ref
[optional]
- (identifier for customer subscribed to returned journals)
Returns
- data
-
journal_id
integer
-
title
string
-
subtitle
string
-
code
string
-
issn
string
-
issn_linking
string
-
isbn
string
-
language
string
-
url
string
-
doi
string
-
subject
string
-
keywords
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
admin_name
string
-
admin_email
string
-
editor_name
string
-
editor_email
string
-
editorial_board
string
-
place
string
-
address
string
-
country
string
-
publication_statement
string
-
description
string
-
price_currency
string
-
price_individual
float (2dp)
-
price_institution
float (2dp)
-
open_access
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed**
integer (1 or 0)
Description
Returns metadata for a single journal. This returns more data than /JournalGetAll, including links (by ID) to all issues and articles connected to the journal.
description may contain HTML.
*One (and only one) of these identifiers must be supplied.
**The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal.
/JournalVolumeGetAll
Parameters
-
journal_id
[mandatory]
- a journal ID (integer)
-
availability
[optional]default: all
- all
- on_sale
- withdrawn
- subscribed
-
customer_ref
[optional]
- identifier for customer subscribed to returned books (string)
-
format
[optional]default: json
- json
Returns
- data
-
journal_id
integer
-
volume
integer
-
num_issues
integer
-
date_published
date (YYYY-MM-DD)
-
open_access
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for volumes in the specified journal.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
/JournalIssueGetAll
Parameters
-
format
[optional]default: json
- json
- csv
-
availability
[optional]default: all
- all
- on_sale
- withdrawn
- subscribed
-
journal_id
[optional]
- a journal ID (integer)
-
journal_issue_ids
[optional]default: (empty = all)
- semicolon-delimited list of journal issue IDs
-
volume
[optional, requires journal_id]
- a volume number (integer)
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
customer_ref
[optional]
- identifier for customer subscribed to returned books (string)
-
imprint
[optional]default: (empty = all)
- semicolon-delimited list of imprints
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
offset
[optional]default: 0
- offset of returned data set
Returns
- data
-
journal_issue_id
integer
-
journal_id
integer
-
volume
integer
-
issue
integer
-
title
string
-
subtitle
string
-
keywords
string
-
description
string
-
editors
string
-
language
string
-
url
string
-
isbn
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
subjects
string
-
pages
integer
-
start_page
integer
-
end_page
integer
-
front_matter_pages
integer
-
back_matter_pages
integer
-
wordcount
integer
-
date_published
date (YYYY-MM-DD)
-
filename
string
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
open_access
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for journal issues, or a subset based on selected parameters, in the specified format.
If volume is used, then journal_id must also be specified. This returns all issues in the corresponding volume of that journal.
If available_since and/or published_since is used, this returns matching issues that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
/JournalIssueGet
Parameters
-
format
[optional]default: json
- json
- csv
-
id
[optional*]
- a journal issue ID (integer)
-
isbn
[optional*]
- an isbn (string)
-
customer_ref
[optional]
- (identifier for customer subscribed to returned issue)
Returns
- data
-
journal_issue_id
integer
-
journal_id
integer
-
journal_title
string
-
volume
integer
-
issue
integer
-
title
string
-
subtitle
string
-
keywords
string
-
description
string
-
editors
string
-
language
string
-
url
string
-
isbn
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
subjects
string
-
pages
integer
-
start_page
integer
-
end_page
integer
-
front_matter_pages
integer
-
back_matter_pages
integer
-
wordcount
integer
-
date_published
date (YYYY-MM-DD)
-
filename
string
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
price_currency
string
-
price_individual
float (2dp)
-
price_institution
float (2dp)
-
open_access
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for a single journal issue. This returns more data than /JournalIssueGetAll, including links (by ID) to all articles connected to the journal.
description may contain HTML.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal issue.
/JournalArticleGetAll
Parameters
-
format
[optional]default: json
- json
- csv
-
journal_id
[optional]
- a journal ID (integer)
-
journal_issue_id
[optional]
- a journal issue ID (integer)
-
journal_article_ids
[optional]default: (empty = all)
- semicolon-delimited list of journal article IDs
-
volume
[optional, requires journal_id]
- a volume number (integer)
-
issue
[optional, requires journal_id]
- an issue number (integer)
-
available_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
published_since
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
thema
[optional]default: (matches all Themas)
- uppercase Thema subject code, semicolon-delimited for multiple codes
-
customer_ref
[optional]
- identifier for customer subscribed to returned books (string)
-
imprint
[optional]default: (empty = all)
- semicolon-delimited list of imprints
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
offset
[optional]default: 0
- offset of returned data set
Returns
- data
-
journal_article_id
integer
-
journal_issue_id
integer
-
journal_id
integer
-
volume
integer
-
issue
integer
-
original_page_number
integer
-
title
string
-
subtitle
string
-
abstract
string
-
language
string
-
authors
string
-
url
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
subjects
string
-
pages
integer
-
wordcount
integer
-
date_published
date (YYYY-MM-DD)
-
filename
string
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
open_access
integer (1 or 0)
-
subscribed*
integer (1 or 0)
Description
Returns metadata for journal articles, or a subset based on selected parameters, in the specified format.
If volume is used, then journal_id must also be specified. In turn, volume is required if issue is specified. This returns all articles in the corresponding volume / issue of that journal.
Alternatively, journal_issue_id can be specified to return all articles associated with that issue.
If available_since and/or published_since is used, this returns matching issues that have been available and/or published since the specified dates.
The thema parameter can be used to restrict to one or more Thema subjects. Multiple subjects can be specified by comma-delimiting codes.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet.
/JournalArticleGet
Parameters
-
format
[optional]default: json
- json
- csv
-
id
[mandatory]
- a journal article ID (integer)
-
customer_ref
[optional]
- (identifier for customer subscribed to returned issue)
Returns
- data
-
journal_issue_id
integer
-
journal_id
integer
-
journal_title
string
-
issue_id
integer
-
journal_issue_title
string
-
volume
integer
-
issue
integer
-
original_page_number
integer
-
start_page
integer
-
end_page
integer
-
title
string
-
subtitle
string
-
abstract
string
-
language
string
-
authors
string
-
url
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
subjects
string
-
keywords
string
-
pages
integer
-
front_matter_pages
integer
-
back_matter_pages
integer
-
wordcount
integer
-
date_published
date (YYYY-MM-DD)
-
filename
string
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
price_currency
string
-
price_individual
float (2dp)
-
price_institution
float (2dp)
-
open_access
integer (1 or 0)
-
search_available
integer (1 or 0)
-
subscribed*
integer (1 or 0)
- references:
-
journal_reference_id
integer
-
label
string
-
note
string
-
source
string
-
patent
string
-
title
string
-
edition_statement
string
-
series
string
-
volume
string
-
issue
integer
-
first_page
integer
-
last_page
integer
-
authors
string
-
date_published
date (YYYY-MM-DD)
-
publisher
string
-
publisher_place
string
-
url
string
-
url_access_date
datetime (YYYY-MM-DD HH:MM:SS)
Description
Returns metadata for a single journal article. This returns more data than /JournalArticleGetAll, including all references.
*The customer_ref parameter causes the subscribed field of the returned data to be populated. To get a list of the customer's subscriptions, use /CustomerSubscriptionsGet. Note that a customer can be subscribed to just one article, to a single issue, or to a whole journal. The subscription always cascades, so that if a journal is subscribed, then all articles and issues within that journal are automatically also subscribed.
Typical use
This method could be used to populate a page of details for a specific journal issue.
/JournalReferenceGetCitation
Parameters
-
format
[optional]default: json
- json
- csv
-
style
[optional]default: apa
- apa
- mla
- ama
- turabian
- chicago
-
id
[mandatory]
- a journal reference ID (integer)
Returns
- data
-
citation
string
Description
Returns a citation for a specified reference in the specified style.
/JournalArticleAuthorSearch
Parameters
-
format
[optional]default: json
- json
- csv
-
author
[mandatory]
-
match
[optional]default: substring
- substring
- exact
Returns
- data
-
author
string
- articles:
-
article_id
Description
Searches for a specified author in journal articles. The author can be be matched as a substring or exact. In either case, the returned data will include the author as matched (possibly multiple times if different variations are matched).
/JournalReferenceAuthorSearch
Parameters
-
format
[optional]default: json
- json
- csv
-
author
[mandatory]
-
match
[optional]default: substring
- substring
- exact
Returns
- data
-
author
string
- references:
-
reference_id
Description
Searches for a specified author in journal references. The author can be be matched as a substring or exact. In either case, the returned data will include the author as matched (possibly multiple times if different variations are matched).
Collections are simply groups of the same type of item. They are typically used to group items for sales purposes, e.g. by subject. A collection can contain items of one (and only one) of the following types:
- Books
- Journals (i.e. complete journals)
- Journal issues (i.e. single issues)
- Journal articles
/CollectionsGetAll
Parameters
-
customer_ref
[optional]
- (identifier to restrict to collections containing subscribed items only)
-
type
[optional]default: (empty)
- books
- journals
- journal_issues
- journal_articles
-
status
[optional]default: public
- public
- private
- any
-
featured
[optional]default: 1
- 1
- 0
-
subject
[optional]
- a subject
-
item_id
[optional]
- a single item ID (integer)
-
item_type
[optional*]
- a single item type (book|chapter|journal_issue|journal_article)
-
format
[optional]default: json
- json
- csv
*Required if item_id is supplied
Returns
- data
-
collection_id
integer
-
code
string
-
name
string
-
type
string
-
slug
string
-
subjects
string
-
num_titles
integer
-
num_titles_available
integer
-
public
integer (1 or 0)
-
featured
integer (1 or 0)
-
description
text
Description
Returns metadata for any collections you have created.
If type is specified, only collections of that type will be returned. Note that only collections marked "public" will be returned, unless status is set to "any".
The customer_ref parameter causes will restrict the collections returned to only those containing items to which the specified customer is subscribed.
If item_id and item_type are provided, this will limit the results to collections containing that item, taking into account any other parameters.
/CollectionGet
Parameters
-
id
[optional*]
- a collection ID (integer)
-
slug
[optional*]
- a collection slug (string)
-
code
[optional*]
- a collection metadata code (string)
-
customer_ref
[optional]
- (identifier to populate subscribed field)
-
format
[optional]default: json
- json
- csv
- marc**
*one of these parameters must be supplied
**MARC-format output is currently only available for eBook collections
Returns
- data
-
(see description)
Description
Returns a list of titles matching a specific collection with the same data structure as /BookGetAll, /JournalGetAll, /JournalIssueGetAll, or JournalArticleGetAll depending on collection type.
The customer_ref parameter causes will cause the "subscribed" field of the results to be populated.
Items can be accessed for online reading (using CloudPublish CloudReader) for download (PDF via Adobe Digital Editions with Adobe CRM).
/Read
Parameters
-
book_id
[optional*]
- a book ID (integer)
-
journal_issue_id
[optional*]
- a journal issue ID (integer)
-
journal_article_id
[optional*]
- a journal article ID (integer)
-
chapter_id
[optional*]
- a chapter ID (integer)
-
customer_ref
[mandatory unless in preview mode]default: (empty)
- a customer identifier (string)
-
customer_user_ref
[optional]default: (empty)
- a customer personalisation identifier (string)
-
mode
[mandatory]
- preview
- online
- download
-
start_page
[optional]default: 1
- a page to start reading (integer)
-
return_url
[optional]default: (see description)
- an encoded/escaped url to which the user will return after reading online
-
drm
[optional]
- soft
- hard
-
access_token
[optional]default: (empty)
- an access token code (string)
Returns
-
url
string
Description
This method allows items to be accessed for online reading in FastReader. This method returns a URL which can then be called, for a limited period, to either open FastReader (for online viewing) or to initiate a download.
*One (and only one) item ID must be supplied, either book_id, journal_issue_id, journal_article_id or chapter_id.
The customer_ref is required unless in preview mode. When the returned URL is used, the customer will be checked for a valid subscription and against the number of current readers.
The customer_user_ref is optional, and allows you to personalise content, by having more than one possible user per customer_ref. For example, if customer_ref refers to an organisation, then customer_user_ref can refer to a specific user within that organisation. If you do not include it, all personalisation data will be stored with the customer_ref alone. Therefore if there are multiple end-users sharing the same customer_ref, they will see each other's personalised content (bookmarks, notes, etc.), which is undesirable.
The preview mode provides a limited version of the item (online only), and does not cause a check against the number of current readers.
The return_url is the URL to which the user will be returned when they click "Exit" from FastReader (when reading online). If not provided, the publisher's default URL will be used (this can be changed in the publisher's settings).
Important: If your user is rejected when they use the url (for example because there are too many concurrent readers), the URL will trigger a HTTP error 403 "Forbidden", with the body containing a descriptive error message. You will probably want to handle these in a visually useful way for your users.
Downloads: For books and journal issues, downloads will be made to Adobe Digital Editions (or compatible Adobe DRM devices) with Adobe's "hard" DRM, or as an encrypted watermarked PDF ("soft" DRM) depending on the value of the drm parameter. If this is not supplied, then your account default preference will be used (this can be viewed under "Settings" in the Admin Tool). For more information, please see the FAQ.
If you supply the drm parameter with mode set to online, then the relevant DRM will be inherited for download requests from within the online ereader.
/ReadGetCurrentReaders
Parameters
-
book_id
[optional*]
- a book ID (integer)
-
journal_issue_id
[optional*]
- a journal issue ID (integer)
-
journal_article_id
[optional*]
- a journal article ID (integer)
-
chapter_id
[optional*]
- a chapter ID (integer)
-
customer_ref
[mandatory]default: (empty)
- a customer identifier (string)
Returns
-
count
integer
-
copies
integer
Description
This method checks against the number of current readers for the specified item, for a specified customer. It returns the number of current readers and the number of copies available for reading in total (-1 if unlimited).
*One (and only one) item ID must be supplied, either book_id, journal_issue_id, journal_article_id or chapter_id.
The returned value count is the current number of readers (including both online and download readers), and copies is the number of copies available in all current subscriptions, but not including any available via a share group.
Typical use
This method could be used to ascertain whether an item can be read (i.e. not unavailable due to concurrent readers) before attempting to read, in order to avoid an error when invoking the URL returned by /Read.
Searches are conducted either across the catalogue, searching either catalogue metadata or within the text of specific items. Searches can be saved against a customer identifier.
- /Search is for searching catalogue metadata, using keyword matching
- /SearchText is for searching within the text of one or more items, or your entire catalogue, using natural language matching
Natural language matching allows for the search term to be enclosed in double-quotes (") to prioritise a seach for the exact phrase.
Searches conducted via /Search can be saved, using /SearchSave, but fulltext searches via /SearchText cannot be saved.
/Search
Parameters
-
customer_ref
optional
- a customer identifier (string)
-
limit
[optional]default / max: 500
- integer 1-500
-
availability
[optional]default: all
- all
- on_sale
- withdrawn
- subscribed
- open_access
-
match_type
[optional]default: any
- all
- any
- phrase
- title
- author
-
item_type
[optional]default: any
- any
- book
- journal
-
language
[optional]default: (empty)
- a language (3-character string, ISO 639-2/5 format)
-
keywords
[optional*]default: (empty)
- space-delimited keywords (i.e. search terms)
-
collection_id
[optional]default: (empty)
- a single CloudPublish collection ID
-
thema
[optional]default: (empty)
- a single Thema subject code
-
imprints
[optional*]default: (empty)
- comma-delimited imprints
-
series
[optional]default: (empty)
- a single series attribute (books only)
-
series_volume
[optional]default: (empty)
- a single series volume attribute (books only)
-
series_code
[optional]default: (empty)
- a single series code attribute (books only)
-
date_published_from
[optional]default: (empty)
- date in format YYYY-MM-DD
-
date_published_to
[optional]default: (empty)
- date in format YYYY-MM-DD
-
open_access
[optional]default: (empty = any)
- boolean 1/0
-
sort_by
[optional]default: score
- score
- item_id
- title
- date_published
-
sort_order
[optional]default: ascending for title and item_id, descending for date_published and score
- asc
- desc
*at least one of these parameters must be supplied
Returns
- data
-
search_id
integer
-
results
complex
- results:
-
item_id
integer
-
item_type
string
-
title
string
-
subtitle
string
-
series
string
-
journal
string
-
journal_code
string
-
volume
string
-
issue
string
-
journal_id
string
-
journal_issue_id
string
-
parent_item_id
integer
-
parent_item_type
string
-
authors
string (delimited by semicolon)
-
edition
string
-
isbn
string
-
doi
string
-
thema_codes
string
-
thema_qualifiers
string
-
imprint
string
-
date_published
date (YYYY-MM-DD)
-
cover_thumbnail_url
string (url)
-
cover_midsize_url
string (url)
-
cover_fullsize_url
string (url)
-
open_access
integer (1 or 0)
-
available
integer (1 or 0)
-
withdrawn
integer (1 or 0)
-
subscribed
integer (2 [partial access], 1 [full access], or 0 [no access])
Description
The search will run against common metadata fields for the specified items, restricted by item type, collection, subject (Thema), imprint, series, and/or publication date.
A maximum of 500 results is returned.
A customer_ref is required if availability is set to "subscribed". This has the effect of confining the search to the customer's own subscriptions.
If a customer_ref is supplied (regardless of the availability setting), the returned data includes a search ID which can be used to save a search for a customer (see /SearchSave below). This search ID is only valid for 24 hours: if the search is not saved, the ID is removed from the system after 24 hours.
If customer_ref is supplied, then the subscribed value in the returned data will be 0 if there is no subscription, or 1 if there is a matching subscription. If there is a matching subscription that provides partial access (e.g. a journal issue in the context of a journal search) then the returned value will be 2.
/SearchSave
Parameters
-
search_id
[mandatory]
- a search ID (integer; returned from /Search)
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_user_ref
[mandatory]
- a customer personalisation identifier (string)
-
savename
[optional]default: "Search #XXXXX" (where XXXXX is the search_id)
-
unique
[optional]default: 0
- 1 (yes) or 0 (no)
Returns
- data
-
search_id
integer
Description
This method allows a search (i.e., /Search) to be saved for a specified customer; the customer_ref must match the same customer_ref used for the original search.
The saved search must be associated with an individual user via the customer_user_ref parameter. This could be set to the same as customer_ref if the customer does not have multiple users.
Note that saving a search only applies to searches carried out with /Search, but not with /SearchText.
The savename does not need to be unique to the customer, although uniqueness (to the customer) can be enforced by passing unique=1. The savename can be modified by saving again, with a different value.
/SearchText
Parameters
-
item_id
[optional*]
- comma-delimited list of item IDs (string)
-
item_type
[mandatory]
- a single item type (book|chapter|journal_issue|journal_article)
-
searchtext
[mandatory]
- search phrase (string)
-
customer_ref
[optional]
- a customer identifier (string)
-
return_distinct
[optional]
- boolean (1 or 0, default: 0)
-
language
[optional]default: eng
- a language (3-character string, ISO 639-2/5 format)
*If not specified, the whole catalogue will be searched for the corresponding item_type, unless customer_ref is specified, in which case only that customer's subscriptions will be searched.
Returns
- data
-
searchtext
string
-
num_results
integer
-
num_distinct_results
integer
-
results
complex
- results:
-
page
integer
-
text
string
-
item_type
string
-
item_id
integer
-
isbn
string
-
score
float
Description
This method allows searching within the text of a specified item or items (of a single specified type). The function is quite different to /Search because this method only matches against a specific term or phrase, i.e. it is not possible to supply a list of keywords.
Note that if item_id is not specified, the whole catalogue will be searched, unless customer_ref is specified, in which case only that customer's subscriptions will be searched.
Important: If item_id is specified, and customer_ref is specified, only the subset of the items specified to which the customer is subscribed will be searched.
If return_distinct parameter is set to 1, then only the first result from each matched item is returned.
The language parameter should be the user's input language.
/SearchGetSavedSearches
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_user_ref
[optional]
- a customer personalisation identifier (string)
Returns
- data
-
search_id
integer
-
savename
integer
-
customer_user_ref
integer
-
date_created
integer
Description
This method allows retrieves all of a customer's saved searches. If customer_user_ref is supplied, then only that personalised user's searches will be returned, otherwise all of the customer's searches will be returned.
/SearchRunSavedSearch
Parameters
-
search_id
[mandatory]
- a saved search ID (integer)
-
customer_ref
[mandatory]
- a customer identifier (integer)
Returns
- data
-
search_id
integer
-
results
complex
- results:
-
(as for /Search)
Description
This method re-runs the search entirely with the same parameters as the original search. It can therefore return different results if the underlying catalogue has been updated.
Note that both the identifiers are mandatory.
An order is a submitted cart. When processed, it generates subscriptions and transactions.
/OrderCreate
Parameters
-
customer_ref
[optional*]
- a customer identifier (string)
-
customer_id
[optional*]
- a customer id (integer)
-
customer_user_ref
[optional**]
- a customer user identifier (string)
-
customer_user_id
[optional**]
- a customer user id (integer)
-
reference
[optional]
- a reference number/code (string)
-
status
[optional]
- an order status (string)
-
description
[optional]
- an order description (string)
-
book_items
[optional]
- comma-delimited list of book IDs (string)
-
book_items_quantity
[optional, default 1]
- default quantity for each book item (integer)
-
chapter_items
[optional]
- comma-delimited list of chapter IDs (string)
-
chapter_items_quantity
[optional, default 1]
- default quantity for each chapter item (integer)
-
journal_items
[optional]
- comma-delimited list of journal IDs (string)
-
journal_items_quantity
[optional, default 1]
- default quantity for each journal item (integer)
-
journal_issue_items
[optional]
- comma-delimited list of journal issue IDs (string)
-
journal_issue_items_quantity
[optional, default 1]
- default quantity for each journal issue item (integer)
-
journal_article_items
[optional]
- comma-delimited list of journal article IDs (string)
-
journal_article_items_quantity
[optional, default 1]
- default quantity for each journal article item (integer)
-
collection_id
[optional]
- a collection ID
-
collection_items_quantity
[optional, default 1]
- default quantity for each collection item (integer)
-
allow_online
[optional, default per publisher settings]
- value for resulting subscription (boolean)
-
allow_download
[optional, default per publisher settings]
- value for resulting subscription (boolean)
-
allow_printing
[optional, default per publisher settings] (boolean)
- value for resulting subscription
-
allow_unlimited_printing
[optional, default per publisher settings] (boolean)
- value for resulting subscription
-
print_percentage_allowance
[optional, default per publisher settings]
- value for resulting subscription (integer, must be 0-100)
*/**at least one in each pair of these parameters must be supplied
Returns
- data
-
order_id
integer
Description
This method creates a new (empty) order. Items can be added here or one-by-one using /OrderUpdateItem. If adding items here, the default quantity (for each) is 1 if not specified.
Important note: CloudPublish does not store any pricing information within orders, because it expects you to do this within your own ecommerce platform. Orders exist within CloudPublish in order to provide a subscription mechanism only.
Returns an order_id for use with the related order-management methods.
/OrderGet
Parameters
-
order_id
[optional]
- an order ID (integer)
-
customer_ref
[optional]
- a customer identifier (string)
-
status
[optional]
- an order status (string)
Returns
- data
-
order_id
integer
-
customer_ref
string
-
status
string
-
reference
string
-
description
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
processed
boolean (1/0)
-
date_processed
datetime (YYYY-MM-DD HH:MM:SS)
-
transaction_id
integer
-
items
complex
- items:
-
item_id
integer
-
item_type
string
-
quantity
-1, 0, or positive integer
-
allow_online
1 or 0
-
allow_download
1 or 0
Description
This method returns details about one or more matching orders. If no parameters are passed, all orders will be returned. The fields date_processed and transaction_id are only populated if processed is 1.
/OrderUpdate
Parameters
-
order_id
[mandatory]
- the order ID (integer)
-
reference
[optional]
- a reference number/code (string)
-
status
[optional]
- an order status (string)
-
description
[optional]
- an order description (string)
Description
This method updates an order's fields. Only the values passed will be updated, but the complete order details (not including items) are returned.
/OrderDelete
Parameters
-
order_id
[mandatory]
- the order ID (integer)
-
customer_ref
[mandatory]
- a customer identifier (integer)
Description
This method deletes an order, and is applicable only to unprocessed orders.
/OrderUpdateItem
Parameters
-
order_id
[mandatory]
- the order ID (integer)
-
book_id
[optional*]
- book ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
-
quantity
[mandatory]
- -1, 0, or positive integer
-
allow_online
[optional]
- boolean (1 or 0, default per publisher settings)
-
allow_download
[optional]
- boolean (1 or 0, default per publisher settings)
-
allow_printing
[optional]
- boolean (1 or 0, default per publisher settings)
-
allow_unlimited_printing
[optional]
- boolean (1 or 0, default per publisher settings)
-
print_percentage_allowance
[optional]
- integer (0-100, default per publisher settings)
-
duration
[optional]default: 0 (unlimited)
- integer
*one (and only one) of these parameters must be supplied
Returns
- data
-
order_id
integer
-
item_id
integer
-
item_type
string
-
quantity
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
duration
integer
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates an order to set the number of a given item (either updating the quantity for an existing item or adding a new item). It is applicable only to unprocessed orders (i.e. not already converted to a transaction via /OrderProcess).
The quantity of an item typically corresponds to the number of copies of an ebook that will be available in the subscription that is created when the order is processed.
The quantity can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV), or a positive integer (which will correspond to the readers property of the resulting subscription).
The two allow_ parameters control whether the resulting subscription allows the book to be viewed online and/or downloaded.
The optional duration is the duration of the resulting subscription in seconds (rounded to the nearest day). A duration of 0 corresponds to an unlimited subscription; this is the default.
/OrderDeleteItem
Parameters
-
order_id
[mandatory]
- the order ID (integer)
-
book_id
[optional*]
- book ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Description
This method updates an order to remove the specified item completely. It is applicable only to unprocessed orders (i.e. not already converted to a transaction via /OrderProcess).
/OrderProcess
Parameters
-
order_id
[mandatory]
- the order ID (integer)
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_type
[optional]default: inst
- a customer type (string: inst|ind)
-
status
[optional]
- a transaction status (string)
-
invoice_number
[optional]
- an invoice number or other reference code (uniqueness not enforced) (string)
-
invoice_reference
[optional]
- an additional invoice-related reference field (uniqueness not enforced) (string)
-
invoice_date
[optional]
- a date for the invoice (date in format YYYY-MM-DD)
-
ecommerce_tx_ref
[optional]
- an ecommerce transaction reference (uniqueness not enforced) (string)
-
ecommerce_tx_status
[optional]
- an ecommerce transaction status (string)
-
start_date
[optional]default: (current date)
- date in format YYYY-MM-DD
-
end_date
[optional]default: (empty)
- date in format YYYY-MM-DD
-
notes
[optional]
- notes to be attached to the transaction (text blob)
Returns
- data
-
transaction_id
integer
-
customer_ref
string
-
status
string
-
invoice_number
string
-
invoice_reference
string
-
invoice_date
date (YYYY-MM-DD)
-
ecommerce_tx_ref
string
-
ecommerce_tx_status
string
-
notes
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
items
complex
-
subscriptions
complex
- items:
-
transaction_item_id
integer
-
item_id
integer
-
item_type
string
-
quantity
-1, 0, or positive integer
- subscriptions:
-
subscription_id
integer
-
item_id
integer
-
item_type
string
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
allow_printing
1 or 0
-
allow_unlimited_printing
1 or 0
-
print_percentage_allowance
integer 0-100
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method creates subscriptions and a transaction from an order. The optional start_date sets the start-date of each subscription, and is by default the current date (at the time the order was processed). Each subscription's expiry date is either not set (i.e. unlimited) or is set according to the order item's duration which is added to the current date / start_date as applicable.
Pricing information for the transaction will be based on the customer_type parameter, which corresponds to the prices listed under price_inst and price_ind for the various item types (books, etc.).
A subscription entitles a customer to access one or more copies of a book. It can be created directly or by processing an order. Note that creating a subscription directly also creates a corresponding transaction.
It is possible for a customer to have more than one subscription to a given book. In this case, the /CustomerSubscriptionCheck method will check all matching subscription, and will return affirmatively if at least one is valid/current for the book.
/SubscriptionCreate
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
status
[optional]
- a transaction status (string)
-
invoice_number
[optional]
- an invoice number or other reference code (uniqueness not enforced) (string)
-
invoice_reference
[optional]
- an additional invoice-related reference field (uniqueness not enforced) (string)
-
invoice_date
[optional]
- a date for the invoice (date in format YYYY-MM-DD)
-
ecommerce_tx_ref
[optional]
- an ecommerce transaction reference (uniqueness not enforced) (string)
-
ecommerce_tx_status
[optional]
- an ecommerce transaction status (string)
-
notes
[optional]
- notes to be attached to the transaction (text blob)
-
book_id
[optional*]
- book ID (integer, comma-delimited string of integers for multiple IDs)
-
journal_id
[optional*]
- journal ID (integer, comma-delimited string of integers for multiple IDs)
-
journal_issue_id
[optional*]
- journal issue ID (integer, comma-delimited string of integers for multiple IDs)
-
journal_article_id
[optional*]
- journal article ID (integer, comma-delimited string of integers for multiple IDs)
-
collection_id
[optional*]
- a collection ID (integer, comma-delimited string of integers for multiple IDs)
-
access_model
[optional]default: standard
- standard, pda, access_limit
-
copies
[optional]default: -1
- -1, 0, or positive integer
-
allow_online
[optional]default: 1
- 1 or 0 (integer)
-
allow_download
[optional]default: 1
- 1 or 0 (integer)
-
allow_printing
[optional]default: 1
- 1 or 0 (integer)
-
allow_unlimited_printing
[optional]default: 1
- 1 or 0 (integer)
-
print_percentage_allowance
[optional]default: 0
- 0-100 (integer / percentage)
-
start_date
[optional]default: (current date)
- date in format YYYY-MM-DD
-
end_date
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
*one or more of these parameters must be supplied
Returns
- data
-
transaction_id
integer
-
subscription_ids
complex
- subscription_ids
-
subscription_id**
integer
**if multiple subscriptions are created as a result of passing in collection_id, then this element will appear multiple times
Description
This method creates a subscription (or, in the case of a collection, multiple subscripions) directly without transaction or order.
The copies of an item typically corresponds to the number of copies of an item that will be available in the subscription that is created when the order is processed.
The copies can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV, where the subscription will be updated later), or a positive integer (representing the maximum number of concurrent readers on this subscription).
Setting print_percentage_allowance to 0 means that the main account setting will be used instead. This is a rolling 30-day print allowance expressed as a percentage of the item's pagecount.
Setting allow_unlimited_printing requires allow_printing to be set to 1, and will cause print_percentage_allowance to be ignored.
This method returns a unique subscription_id and corresponding transaction_id for use in referring to this subscription later.
Note that if you subscribe to a Collection via collection_id, this creates subscriptions to the underlying books (or other items), and not to the Collection itself. Therefore, any subsequent changes to the Collection's contents will have no effect on customer subscriptions.
/SubscriptionsGetAll
Parameters
-
book_id
[optional*]default: (empty)
- book ID (integer)
-
journal_issue_id
[optional*]default: (empty)
- a journal issue ID (integer)
-
journal_article_id
[optional*]default: (empty)
- a journal article ID (integer)
-
chapter_id
[optional*]default: (empty)
- a chapter ID (integer)
-
order_id
[optional]default: (empty)
- order ID (integer)
-
start_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
start_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
end_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
end_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
allow_online
[optional]default: (empty)
- boolean / integer (1 or 0) or empty to match both
-
allow_download
[optional]default: (empty)
- boolean / integer (1 or 0) or empty to match both
-
access_model
[optional]default: (empty)
- access model: standard, pda, access_limit or empty to match any
Returns
- data
-
subscription_id
integer
-
item_id
integer
-
item_type
string
-
customer_ref
string
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
*only one (or none) of these parameters may be supplied
Description
This method returns subscription data based on the parameters, or for all time if no parameters are supplied (up to a maximum of 500 records).
One (or none) of book_id, journal_issue_id, journal_article_id or chapter_id may be supplied. Specifying an item and/or order_id parameters allow subscriptions referring to a specific item and/or order to be returned.
To return subscriptions relating to a specific customer, use the /CustomerSubscriptionsGet method.
/SubscriptionGet
Parameters
-
subscription_id
[mandatory]
- a subscription ID (integer)
Returns
- data
-
subscription_id
integer
-
book_id
integer
-
customer_ref
string
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns details about a subscription.
/SubscriptionUpdate
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
subscription_id
[mandatory]
- a subscription ID (integer)
-
allow_online
[optional]default: unchanged
- 1 or 0 (integer)
-
allow_download
[optional]default: unchanged
- 1 or 0 (integer)
-
allow_printing
[optional]default: 1
- 1 or 0 (integer)
-
allow_unlimited_printing
[optional]default: 1
- 1 or 0 (integer)
-
print_percentage_allowance
[optional]default: 0
- 0-100 (integer / percentage)
-
copies
[optional]default: unchanged
- -1, 0, or positive integer
-
start_date
[optional]default: unchanged
- date in format YYYY-MM-DD
-
end_date
[optional]default: unchanged
- date in format YYYY-MM-DD
Returns
- data
-
subscription_id
integer
-
book_id
integer
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates an existing subscription. Only the supplied parameters cause properties to be updated; all other properties of the subscription will be left unchanged.
Setting print_percentage_allowance to 0 means that the main account setting will be used instead. This is a rolling 30-day print allowance expressed as a percentage of the item's pagecount.
Setting allow_unlimited_printing requires allow_printing to be set to 1, and will cause print_percentage_allowance to be ignored.
Typical use
If you are implementing a PDA (patron-driven acquisition) or PPV (pay-per-view) model, you could set copies to 0 when initially creating the subscription, and then manually create an associated transaction (using /TransactionCreate) when you update the subscription based on customer action.
/SubscriptionDelete
Parameters
-
subscription_id
[mandatory]
- the order ID (integer)
-
customer_ref
[mandatory]
- a customer identifier (string)
Description
This method deletes a subscription.
Typical use
It is better to set the expiry of a subscription to a date in the past, rather than to delete a subscription, in order to preserve an audit trail.
A Transaction is generated when an order is processed or when a subscription is created directly.
/TransactionsGetAll
Parameters
-
book_id
[optional]default: (empty)
- book ID (integer)
-
journal_id
[optional]default: (empty)
- journal ID (integer)
-
journal_issue_id
[optional]default: (empty)
- journal issue ID (integer)
-
journal_article_id
[optional]default: (empty)
- journal article ID (integer)
-
order_id
[optional]default: (empty)
- order ID (integer)
-
date_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
date_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
status
[optional]default: (empty)
- string
Returns
- data
-
transaction_id
integer
-
order_id
integer
-
customer_ref
string
-
invoice_number
string
-
invoice_reference
string
-
invoice_date
date (YYYY-MM-DD)
-
status
string
-
ecommerce_tx_ref
string
-
ecommerce_tx_status
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns transaction data based on the parameters, or for all time if no parameters are supplied (up to a maximum of 500 records).
The date_after and date_before parameters allow a date range to be specified; use just one to return all transactions before or after a date (i.e., invoice_date.
The book_id, journal_id, journal_issue_id, journal_article_id and order_id parameters allow transactions referring to a specific item or order to be returned.
To return transactions relating to a specific customer, use the /CustomerTransactionsGet method.
/TransactionGet
Parameters
-
transaction_id
[mandatory]
- the transaction ID (integer)
-
customer_ref
[mandatory]
- a customer identifier (string)
Returns
- data
-
transaction_id
integer
-
order_id
integer
-
customer_ref
string
-
invoice_number
string
-
invoice_reference
string
-
invoice_date
date (YYYY-MM-DD)
-
status
string
-
ecommerce_tx_ref
string
-
ecommerce_tx_status
string
-
notes
text
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
items
complex
- items
-
item_id
integer
-
item_type
string
-
item_title
string
-
item_identifier
string
-
price
string
-
price_currency
string
-
quantity
integer
Description
This method returns full data for a single transaction, which must match the customer_ref.
/TransactionCreate
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
invoice_number
[optional]
- an invoice number (string)
-
invoice_reference
[optional]
- an invoice reference (string)
-
invoice_date
[optional]
- an invoice date in format YYYY-MM-DD
-
status
[optional]
- a transaction status (string)
-
ecommerce_tx_ref
[optional]
- an ecommerce transaction reference (string)
-
ecommerce_tx_status
[optional]
- an ecommerce transaction status (string)
-
notes
[optional]
- transaction notes (text blob)
Returns
- data
-
transaction_id
integer
Description
This method manually creates a transaction. In itself, it is an empty container for transaction items, which should then be created one by one using /TransactionItemUpdate
Typical use
Transactions created manually are useful for implementing PDA or PPV.
The status field can be empty or can be set to one of a set of values relevant to your own accounts/billing system, e.g. "invoiced", "paid", "cancelled", etc. You can then retrieve all matching transactions using the status parameter of /TransactionsGetAll.
/TransactionUpdate
Parameters
-
transaction_id
[mandatory]
- the transaction ID (integer)
-
invoice_number
[optional]
- an invoice number (string)
-
invoice_reference
[optional]
- an invoice reference (string)
-
invoice_date
[optional]
- an invoice date in format YYYY-MM-DD
-
status
[optional]
- a transaction status (string)
-
ecommerce_tx_ref
[optional]
- an ecommerce transaction reference (string)
-
ecommerce_tx_status
[optional]
- an ecommerce transaction status (string)
-
notes
[optional]
- transaction notes (text blob)
Returns
- data
-
transaction_id
integer
-
order_id
integer
-
customer_ref
string
-
invoice_number
string
-
invoice_reference
string
-
invoice_date
date (YYYY-MM-DD)
-
status
string
-
ecommerce_tx_ref
string
-
ecommerce_tx_status
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method updates a transaction by changing any of the above attributes. When adding notes, remember that the value will be replaced rather than appended.
Typical use
To update a transaction status (e.g. change a status from "PENDING" to "PAID")
/TransactionDelete
Parameters
-
transaction_id
[mandatory]
- the transaction ID (integer)
-
customer_ref
[mandatory]
- the customer idenfitier (string)
Description
Deletes a transaction and (NB) all associated transaction items and subscriptions.
/TransactionUpdateItem
Parameters
-
transaction_id
[mandatory]
- the transaction ID (integer)
-
book_id
[optional*]
- book ID (integer)
-
chapter_id
[optional*]
- chapter ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
-
quantity
[mandatory]
- -1, 0, or positive integer
*one (and only one) of these parameters must be supplied
Returns
- data
-
transaction_item_id
integer
Description
This method updates a transaction to set the number of a given item (either updating the quantity for an existing item or adding a new item). Note that by altering the transaction's items, the transaction will become inconsistent with any original order that created the transaction.
The quantity of an item typically corresponds to the number of copies of an item that will be available in the subscription. NB, any associated subscriptions are NOT updated: this must be done by /SubscriptionUpdate.
The quantity can be -1 (an unlimited number of copies), 0 (no copies - useful if implementing PDA or PPV), or a positive integer.
/TransactionDeleteItem
Parameters
-
transaction_id
[mandatory]
- the transaction ID (integer)
-
book_id
[optional*]
- book ID (integer)
-
chapter_id
[optional*]
- chapter ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Description
This method updates an order to remove the specified item completely. NB, any associated subscriptions are NOT updated: this must be done by /SubscriptionUpdate.
An access token provides access to content for a user (possibly but not necessarily an existing customer), usually with various restrictions in place.
/AccessTokenCreate
Parameters
-
quantity
[optional]default: 1
- quantity to generate, min 1, max 100 (integer)
-
active
[optional]default: 0
- whether the access token is active (boolean 1/0)
-
customer_ref
[optional]default: (empty)
- a customer identifier (string)
-
item_type
[optional]default: (empty)
- a single item type (book|chapter|journal_issue|journal_article|collection)
-
item_id
[optional]default: (empty)
- an item identifier (integer)
-
item_restriction
[optional]default: (empty)
- e.g. volume=53|volume=54 (string)
-
max_uses
[optional]default: -1
- -1, or positive integer
-
allow_online
[optional]default: 1
- 1 or 0 (integer)
-
allow_download
[optional]default: 1
- 1 or 0 (integer)
-
allow_printing
[optional]default: 1
- 1 or 0 (integer)
-
allow_unlimited_printing
[optional]default: 1
- 1 or 0 (integer)
-
print_percentage_allowance
[optional]default: 0
- 0-100 (integer / percentage)
-
start_date
[optional]default: (current date)
- date in format YYYY-MM-DD
-
end_date
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
*one or more of these parameters must be supplied
Returns
- data
-
access_tokens**
complex
- access_tokens
-
access_token_id
integer
-
code
string
**if multiple access tokens are created as a result of passing in a quantity greater than 1, then this element will appear multiple times
Description
This method creates one or more access tokens with the specified restrictions (if any). These can be redeemed via the /Read API method, or via an integration-specific method.
A customer is a single actor within your customer-base. In CloudPublish, customers are described by a unique identifier, customer_ref (string), which we recommend setting to be the same as the complete corresponding customer record in your own systems.
A CloudPublish customer is typically an institution / organisation entity, and will have one or more customer users, which can be created and managed by further API calls as described below. Again, these can
correspond to users in your own systems, this time via the unique identifier customer_user_ref.
/CustomerIdentify
Parameters
-
ip_address
[mandatory]
- an IP address (string)
-
referrer_url
[mandatory]
- a URL (string)
-
shibboleth_entity_id
[optional]
- a Shibboleth Entity ID (string)
-
openathens_id
[optional]
- an OpenAthens organisation ID (string)
-
customer_ref
[optional]
- a CloudPublish customer identifier (string)
Returns
- data
-
customer_id
integer
-
access_method
string
Description
This method will identify a customer (if the customer is already created via the Admin Tool). Both ip_address and referrer_url are required; they are tested in that order, followed by shibboleth_entity_id, openathens_id, and customer_ref.
/CustomerGet
Parameters
-
customer_id*
[optional]
- a customer id (integer)
-
customer_ref*
[optional]
- a customer identifier (string)
*one (and only one) of these parameters must be supplied
Returns
- data
-
ref
string
-
organisation
string
-
address
string
-
postcode
string
-
phone
string
-
country
string
-
contact_name
string
-
contact_email
string
-
logo
string
-
shibboleth_entity_id
string
-
shibboleth_entitlement
string
-
shibboleth_affiliations
string
-
shibboleth_admin_affiliations
string
-
openathens_org_ids
string
-
ip_range
string
-
referrer_url
string
-
share_group
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method will return details for a single customer, based on the supplied identifier.
/CustomerOrdersGet
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
date_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
date_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
Returns
- data
-
order_id
integer
-
customer_ref
string
-
status
string
-
reference
string
-
description
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
processed
boolean (1/0)
-
date_processed
datetime (YYYY-MM-DD HH:MM:SS)
-
transaction_id
integer
-
items
complex
- items:
-
item_id
integer
-
item_type
string
-
quantity
-1, 0, or positive integer
-
allow_online
1 or 0
-
allow_download
1 or 0
Description
This method returns all order information for a specified customer (within / after / before certain creation dates if specified). The fields date_processed and transaction_id are only populated if processed is 1.
/CustomerSubscriptionsGet
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
current_only
[optional]default: 1
- boolean (1 or 0)
-
item_type
[optional]default: (empty)
- string (book|journal)
-
book_id
[optional]default: (empty)
- book ID (integer)
-
chapter_id
[optional]default: (empty)
- chapter ID (integer)
-
journal_id
[optional]default: (empty)
- journal ID (integer)
-
journal_issue_id
[optional]default: (empty)
- journal issue ID (integer)
-
journal_article_id
[optional]default: (empty)
- journal article ID (integer)
-
start_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
start_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
end_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
end_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
allow_online
[optional]default: (empty)
- boolean / integer (1 or 0) or empty to match both
-
allow_download
[optional]default: (empty)
- boolean / integer (1 or 0) or empty to match both
-
include_share_group
[optional]default: 0
- boolean / integer (1 or 0)
Returns
- data
-
subscription_id
integer
-
item_id
integer
-
item_type
string
-
customer_ref
string
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
-
is_valid
1 or 0
-
via_share_group
1 or 0
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns subscription information for a specified customer (within / after / before certain subscription start/end dates if specified), including current valid subscriptions only if current_only is 1.
If item_type is book, then all subscribed books will be returned (including the books for which chapters are subscribed). Similarly if item_type is journal, then all subscribed journals (even if only a single article / volume / issue is subscribed) will be returned.
Alternatively, if one of book_id, journal_id, journal_issue_id or journal_article_id is passed, then only subscriptions corresponding to the specified item are returned (usually but not always this will be just one subscription).
The is_valid parameter in the returned data indicates whether the subscription is current / valid.
The include_share_group parameter will include subscriptions available to this customer via their share_group - by default these are not included.
/CustomerSubscriptionCheck
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
book_id
[optional*]
- book ID (integer)
-
chapter_id
[optional*]
- chapter ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
*one (and only one) of these parameters must be supplied
Returns
- data
-
result
boolean (1/0)
-
subscription_id
integer
-
copies
integer
-
allow_online
1 or 0
-
allow_download
1 or 0
-
start_date
date (YYYY-MM-DD)
-
end_date
date (YYYY-MM-DD)
Description
This method returns 1 or 0 (i.e. whether or not a valid subscription exists), plus the subscription_id, expiry date and number of copies (if there is a valid subscription), for the specified item. Note that this method checks only the customer's direct subscriptions, not those of any other customer linked via share_group. To include those, use /CustomerAccessCheck instead.
/CustomerAccessCheck
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
book_id
[optional*]
- book ID (integer)
-
chapter_id
[optional*]
- chapter ID (integer)
-
journal_id
[optional*]
- journal ID (integer)
-
journal_issue_id
[optional*]
- journal issue ID (integer)
-
journal_article_id
[optional*]
- journal article ID (integer)
-
access_now
[optional]default: 0
- boolean (1 or 0)
-
access_type
[optional]default: any
- any / online / download
*one (and only one) of these parameters must be supplied
Returns
- data
-
result
boolean (1/0)
Description
This method checks the customer's own subscriptions and those accessible via share_group. It simply returns 1 or 0 (i.e. whether or not a valid subscription exists) for the specified item.
/CustomerTransactionsGet
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
book_id
[optional]default: (empty)
- book ID (integer)
-
chapter_id
[optional]default: (empty)
- chapter ID (integer)
-
journal_id
[optional]default: (empty)
- journal ID (integer)
-
journal_issue_id
[optional]default: (empty)
- journal issue ID (integer)
-
journal_article_id
[optional]default: (empty)
- journal article ID (integer)
-
order_id
[optional]default: (empty)
- order ID (integer)
-
date_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
date_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
status
[optional]default: (empty)
- string
Returns
- data
-
transaction_id
integer
-
order_id
integer
-
customer_ref
string
-
invoice_number
string
-
invoice_reference
string
-
invoice_date
date (YYYY-MM-DD)
-
status
string
-
ecommerce_tx_ref
string
-
ecommerce_tx_status
string
-
notes
text
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
-
last_modified
datetime (YYYY-MM-DD HH:MM:SS)
-
items
complex
- items
-
item_id
integer
-
item_type
string
-
quantity
integer
Description
This method returns a list of the transactions associated with the specified customer (within / after / before certain invoice dates if specified).
/CustomerStatistics
Parameters
-
format
[optional]default: json
- json
- csv
-
customer_ref
[optional]
- a customer identifier (string)
-
customer_user_ref
[optional]
- a customer user identifier (string)
-
event_type
[optional]
- an event type (string: read|read_online|read_download|catalogue_search|item_turnaway)
-
item_type
[optional]
- an item type (string: book|journal)
-
book_id
[optional]default: (empty)
- book ID (integer)
-
chapter_id
[optional]default: (empty)
- chapter ID (integer)
-
journal_id
[optional]default: (empty)
- journal ID (integer)
-
journal_issue_id
[optional]default: (empty)
- journal issue ID (integer)
-
journal_article_id
[optional]default: (empty)
- journal article ID (integer)
-
date_after
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
-
date_before
[optional]default: 0000-00-00
- date in format YYYY-MM-DD
Returns
- data
-
customer_ref
string
-
item_type
string
-
item_id
integer
-
item_title
string
-
item_identifier
string
-
item_doi
string
-
event
string
-
event_data_1
string
-
event_data_2
string
-
date_created
datetime (YYYY-MM-DD HH:MM:SS)
Description
This method returns statistics about customer item access and other customer-related events within CloudPublish. event shows the type of event; event_data_1 and event_data_2 show extra data as applicable (e.g. search terms). If customer_ref is passed, data will be restricted to that customer only. If book_id, journal_id, journal_issue_id or journal_article_id is passed, data will be restricted to that item (or those items) only. Both can be passed for a precise subset of the available data.
If customer_user_ref is passed, then customer_ref is also required. The customer_user_ref allows the statistics for related organisations to be included. If customer_user_ref represents a CustomerUser with admin=1 then all Customers matching that CustomerUser's admin_stats_for will be included in the output.
/CustomerCOUNTERData
Parameters
-
report
[mandatory]
- book_report_1
- book_report_3
- book_report_5
- journal_report_1
- journal_report_2
- journal_report_5
-
customer_ref
[mandatory]
- customer identifier, comma-delimited for multiple customers (string)
-
customer_user_ref
[optional]
- a customer user identifier (string)
-
date_after
[mandatory]
- partial date in format YYYY-MM
-
date_before
[mandatory]
- partial date in format YYYY-MM
Returns
- data
-
(structure depends on report selected)
Description
This method returns statistics about customer ebook access in COUNTER format. The reports available are as follows:
- book_report_1 - Number of successful title requests by month and title
- book_report_3 - Turnaways by month and title
- book_report_5 - Total searches and sessions by month and title
The report runs from the start of the month specified in date_after to the end of the month specified in date_before.
Passing customer_user_ref allows the admin_stats_for attribute of an end-user to be taken into account (i.e. to return data for the linked accounts).
/CustomerUserCreate
Parameters
-
customer_ref
[mandatory]
- customer identifier (string)
-
username
[mandatory]
- customer user identifier (unique, string)
-
password
[mandatory]
- customer password (string)
-
name
[optional]default: (empty)
- customer user's real name (string)
-
admin
[optional]default: 0
- allows admin-level access (boolean 1/0)
-
admin_users_for
[optional]default: (empty)
- Other Customer IDs that this user can access for user admin (string, comma-delimited ints)
-
admin_subs_for
[optional]default: (empty)
- Other Customer IDs that this user can access for subscription admin (string, comma-delimited ints)
-
admin_stats_for
[optional]default: (empty)
- Other Customer IDs that this user can access for statistics admin (string, comma-delimited ints)
-
expiry
[optional]default: 0000-00-00 (no expiry)
- account expiry date (date, YYYY-MM-DD)
Returns
- data
-
customer_id
integer
-
customer_ref
string
-
customer_user_id
integer
-
name
string
-
username
string
-
password
string
-
expiry
date
-
has_expired
boolean
-
admin
boolean
-
admin_users_for
string
-
admin_subs_for
string
-
admin_stats_for
string
Description
This method creates an end-user for a customer. These details can also be changed on the Admin Site, therefore it is important to resync your local records (e.g. of the user's passwords) regularly by using /CustomerUserGet.
The various admin attributes are for your use and do not confer any privileges within CloudPublish, and the expiry attribute has no effect except to provide you with a convenient mechanism via the has_expired value.
It is also possible to create and manage these users manually via the Admin Site.
/CustomerUserGet
Parameters
-
customer_id
[optional*]
- customer identifier (int)
-
customer_ref
[optional*]
- customer identifier (string)
-
customer_user_id
[optional**]
- customer user identifier (integer)
-
username
[optional**]
- customer user identifier (string)
*/** one of each of these pairs of values must be supplied
Returns
- data
-
customer_id
integer
-
customer_ref
string
-
customer_user_id
integer
-
customer_organisation
string
-
customer_logo
string
-
customer_address
string
-
customer_postcode
string
-
customer_phone
string
-
customer_country
string
-
customer_vat_number
string
-
name
string
-
username
string
-
password
string
-
expiry
date
-
has_expired
boolean
-
admin
boolean
-
admin_users_for
string
-
admin_subs_for
string
-
admin_stats_for
string
-
cart
complex; currently a placeholder only
Description
This method retrieves a customer end-user for a customer that was previously created with /CustomerUserCreate or via the Admin Site. Several values from the associated Customer model are also returned, for convenience.
/CustomerUserGetAll
Parameters
-
customer_id
[optional*]
- customer identifier (int)
-
customer_ref
[optional*]
- customer identifier (string)
* one of these must be supplied
Returns
- data
-
customer_id
integer
-
customer_ref
string
-
customer_user_id
integer
-
customer_organisation
string
-
customer_logo
string
-
name
string
-
username
string
-
password
string
-
expiry
date
-
has_expired
boolean
-
admin
boolean
-
admin_users_for
string
-
admin_subs_for
string
-
admin_stats_for
string
Description
This method retrieves all of a customer's end-users that were previously created with /CustomerUserCreate or via the Admin Site. Several values from the associated Customer model are also returned, for convenience.
/CustomerUserUpdate
Parameters
-
customer_id
[optional*]
- customer identifier (int)
-
customer_ref
[optional*]
- customer identifier (string)
-
customer_user_id
[optional**]
- customer user identifier (integer)
-
username
[optional**]
- customer user identifier (string)
-
password
[mandatory]
- customer password (string)
-
name
[optional]default: (empty)
- customer user's real name (string)
-
admin
[optional]default: 0
- allows admin-level access (boolean 1/0)
-
admin_users_for
[optional]default: (empty)
- Other Customer IDs that this user can access for user admin (string, comma-delimited ints)
-
admin_subs_for
[optional]default: (empty)
- Other Customer IDs that this user can access for subscription admin (string, comma-delimited ints)
-
admin_stats_for
[optional]default: (empty)
- Other Customer IDs that this user can access for statistics admin (string, comma-delimited ints)
-
expiry
[optional]default: 0000-00-00 (no expiry)
- account expiry date (date, YYYY-MM-DD)
-
customer_organisation
[optional]default: (empty)
- +customer organisation (string)
-
customer_logo
[optional]default: (empty)
- +customer logo (string)
-
customer_address
[optional]default: (empty)
- +customer address (string)
-
customer_postcode
[optional]default: (empty)
- +customer postcode (string)
-
customer_phone
[optional]default: (empty)
- +customer phone (string)
-
customer_country
[optional]default: (empty)
- +customer country (string)
-
customer_vat_number
[optional]default: (empty)
- +customer VAT number (string)
*/** one of each of these pairs of values must be supplied
Returns
- data
-
customer_id
integer
-
customer_ref
string
-
customer_user_id
integer
-
name
string
-
username
string
-
password
string
-
expiry
date
-
has_expired
boolean
-
admin
boolean
-
admin_users_for
string
-
admin_subs_for
string
-
admin_stats_for
string
Description
This method updates a customer end-user for a customer that was previously created with /CustomerUserCreate or via the Admin Site.
Fields marked with "+" are optional, and will update the parent Customer. If they are passed, and empty, the corresponding values will be deleted; if they are not passed at all, then no action is taken.
/CustomerUserDelete
Parameters
-
customer_id
[mandatory]
- customer identifier (int)
-
customer_user_id
[mandatory]
- customer user identifier (integer)
Description
This method deletes a customer end-user for a customer that was previously created with /CustomerUserCreate or via the Admin Site, along with all data connected with that user (including usage data).
A list is simply an arbitrary list of items, typically created by an end-user (for example, a search result, or a "read later" list, etc.)
/ListCreate
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_user_ref
[mandatory]
- a customer end user identifier (string)
-
savename
[mandatory]
- a savename for the list
-
list_type
[optional]default: general
- a list type (book|chapter|journal|journal_issue|journal_article|general)
-
book_ids
[optional]
- comma-delimited list of book IDs
-
chapter_ids
[optional]
- comma-delimited list of chapter IDs
-
journal_ids
[optional]
- comma-delimited list of journal IDs
-
journal_issue_ids
[optional]
- comma-delimited list of journal issue IDs
-
journal_article_ids
[optional]
- comma-delimited list of journal article IDs
Returns
- data
-
list_id
integer
-
num_items_added
integer
-
num_items_rejected
integer
Description
This method allows a list to be created. It is possible for two or more lists for the same end user to have the same savename. It is possible to have an empty list if no item IDs are supplied.
Items may be rejected if they do not exist, or refer to withdrawn (and not subscribed) items, or if they are duplicates.
The list_type does not necessarily need to correspond exactly with the items specified, for example a "book" list could include chapters as well as books.
This attribute is simply a convenience for presentation.
/ListUpdate
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
list_id
[mandatory]
- a list identifier (string)
-
action
[optional]default: set
- set|add|remove
-
savename
[optional]default: (no change)
- a savename for the list
-
list_type
[optional]default: (no change)
- a list type (book|chapter|journal|journal_issue|journal_article|general)
-
book_ids
[optional]
- comma-delimited list of book IDs
-
chapter_ids
[optional]
- comma-delimited list of chapter IDs
-
journal_ids
[optional]
- comma-delimited list of journal IDs
-
journal_issue_ids
[optional]
- comma-delimited list of journal issue IDs
-
journal_article_ids
[optional]
- comma-delimited list of journal article IDs
Returns
- data
-
list_id
integer
-
num_items_added
integer
-
num_items_rejected
integer
-
num_items_removed
integer
Description
This method allows an existing list to be updated. The savename will only be updated if supplied. It is possible for two or more lists for the same end user to have the same savename.
It is possible to have an empty list if no item IDs are supplied. Items may be rejected if they do not exist, or refer to withdrawn (and not subscribed) items, or if they are duplicates.
The list_type does not necessarily need to correspond exactly with the items specified, for example a "book" list could include chapters as well as books.
This attribute is simply a convenience for presentation.
If action is set, then any supplied item types will be wiped and set as specified. Any item types not supplied will be unaffected.
/ListDelete
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_user_ref
[mandatory]
- a customer end user identifier (string)
-
list_id
[mandatory]
- a list identifier (string)
Description
This method allows an existing list to be permanently deleted. The items within the list are not affected - this only deletes the list "container".
/ListGetAll
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
customer_user_ref
[optional]
- a customer end user identifier (string)
-
list_type
[optional]default: (match all)
- a list type (book|chapter|journal|journal_issue|journal_article|general)
-
date_after
[optional]default: 0000-00-00
- date created, in format YYYY-MM-DD
-
date_before
[optional]default: 0000-00-00
- date created, in format YYYY-MM-DD
Returns
- data
-
list_id
integer
-
list_type
string
-
savename
string
-
num_items
integer
-
num_books
integer
-
num_chapters
integer
-
num_journals
integer
-
num_journal_issues
integer
-
num_journal_articles
integer
-
date_created
date (YYYY-MM-DD)
Description
This method returns data for all matching lists (or all a customer's lists).
/ListGet
Parameters
-
customer_ref
[mandatory]
- a customer identifier (string)
-
list_id
[mandatory]
- a list identifier (integer)
Returns
- data
-
list_id
(integer)
-
customer_ref
(string)
-
customer_user_ref
(string)
-
savename
(string)
-
list_type
(string)
-
items
(complex)
-
date_created
date (YYYY-MM-DD)
Description
This method returns data for all matching lists (or all a customer's lists). The output in items is similar to /BooksGetAll, /JournalGetAll, etc. depending on each item type.
The CloudPublish Admin Tool allows you to create content "snippets" which are intended to be displayed on any related landing page on your site. Use the API to retrieve them.
/CMSGetSnippet
Parameters
-
item_type
[mandatory]
- a type to match the key (string)
-
item_key
[mandatory]
- a key matching the type (int or string)
Returns
- data
-
snippet_id
integer
-
item_type
string
-
item_key
string
-
title
string
-
snippet
string
Description
This method allows for content to be retrieved from the CMS snippet creation tool. If item_type is "series", "subject", or "other" then item_key should be a string. Otherwise, item_key is an integer, i.e. the ID of the corresponding item. Note that snippet in the data returned is HTML data.