CloudPublish API

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.

API Documentation

Connection and authentication

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;

Results format

Testing

Catalogue: General

These methods are applicable to more than one type of item.

Get subjects data

/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.

Expand a subject

Catalogue: Books

A book typically represents a single ebook.

Get book data (all books)

/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.

Get book data (single book)

/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.

Get Table of Contents (single book)

Get citation for book(s)

Get imprints data

Get imprint details (single imprint)

Get series data

Catalogue: Contributors

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.

Get contributors data

Get contributor details (single contributor)

/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.

Get authors data [DEPRECATED]

Get author details (single author) [DEPRECATED]

Catalogue: Chapters

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.

Get chapter data (all chapters)

/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 "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.

Get chapter data (single chapter)

/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.

Create a 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

Update a chapter

/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.

Delete a chapter

Catalogue: Journals

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)

Get journal data (all journals)

/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.

Get journal data (single journal)

/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.

Get journal volume data

Get journal issue data (all issues)

/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.

Get journal issue data (single issue)

/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.

Get journal article data (all articles)

/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.

Get journal article data (single article)

/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.

Typical use

This method could be used to populate a page of details for a specific journal issue.

Get a reference in citation format

Get all articles by an author

Get all references to an author

Collections

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

Get collections data

/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.

Get collection details (single collection)

Accessing items for reading

Items can be accessed for online reading (using CloudPublish CloudReader) for download (PDF via Adobe Digital Editions with Adobe CRM).

Access an item (download or online)

/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.

Get number of current readers for an item

Search

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 catalogue

/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.

Save a search for a customer

Search within the text of items

/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.

Retrieve a customer's saved searches

Run a saved search

Orders

An order is a submitted cart. When processed, it generates subscriptions and transactions.

Create an order

/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.

Get order(s)

/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.

Update an order

Delete an order

Update an order's items

/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.

Delete an item from an order

Process an order (convert to subscriptions)

/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.).

Subscriptions

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.

Create a subscription

/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.

Get subscriptions data

/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.

Get a subscription

Update 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.

Delete a subscription

Transactions

A Transaction is generated when an order is processed or when a subscription is created directly.

Get transactions data

/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.

Get single transaction details

/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.

Manually create a transaction

Update a transaction

/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")

Delete a transaction

Update a transaction's items

Delete an item from a transaction

Access Tokens

An access token provides access to content for a user (possibly but not necessarily an existing customer), usually with various restrictions in place.

Create an access token

/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.

Customers

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.

Identify a customer

Retrieve customer details

/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.

Get customer-specific order information

/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.

Get customer-specific subscription information

/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.

Check whether a customer has a subscription to an item

Check whether a customer can access an item

Get customer-specific transaction information

/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).

Get customer usage statistics (excl. COUNTER stats)

/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.

Get statistical reports in COUNTER format.

Create a Customer User

/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.

Retrieve a Customer User

/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.

Retrieve all Customer Users

Update a Customer User

/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.

Delete a Customer User

Lists

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.)

Create a list

/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.

Update a list

/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.

Content Management

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.

CloudPublish API

API Documentation

/Test

Parameters

Returns

Description

Typical use

Catalogue: General

/SubjectsGetAll

Parameters

Returns

Description

/SubjectsExpand

Parameters

Returns

Description

Catalogue: Books

/BookGetAll

Parameters

Returns

Description

Typical use

/BookGet

Parameters

Returns

Description

Typical use

/BookGetTOC

Parameters

Returns

Description

Typical use

/BookGetCitation

Parameters

Returns

Description

/ImprintsGetAll

Parameters

Returns

Description

/ImprintGet

Parameters

Returns

Description

/SeriesGetAll

Parameters

Returns

Description

Catalogue: Contributors

/ContributorsGetAll

Parameters

Returns

Description

/ContributorGet

Parameters

Returns

Description

/AuthorsGetAll [DEPRECATED]

Parameters

Returns

Description

/AuthorGet [DEPRECATED]

Parameters

Returns

Description

Catalogue: Chapters

/ChaptersGetAll

Parameters

Returns

Description

/ChapterGet

Parameters

Returns

Description

Typical use

/ChapterCreate

Parameters

Returns

Description

/ChapterUpdate