Skip to content

Product Resource

Introduction

A product in the Open Publishing ecosystem can be a book in all kinds of forms. Included are Ebooks as well as hardcopies. The resource includes all types of formats, e.g. EPUB, PDF, audiobooks, POD, In Stock Printing or software.

Example URL

Get single product:

https://api.openpublishing.com/resource/v3/products/[ID]

Allowed methods: GET, PUT, POST, DELETE.

Search Filters

All products:

https://api.openpublishing.com/resource/v3/products

Search for ean:

https://api.openpublishing.com/resource/v3/products?ean=9783638876346

Search for title:

https://api.openpublishing.com/resource/v3/products?title=internet

Filter by language:

https://api.openpublishing.com/resource/v3/products?language=de

Filter by BISAC category:

https://api.openpublishing.com/resource/v3/products?bisac=BUS041000

Filter by THEMA category:

https://api.openpublishing.com/resource/v3/products?thema=1DDU

Filter by subject:

https://api.openpublishing.com/resource/v3/products?subject_id=22

Filter by imprint:

https://api.openpublishing.com/resource/v3/products?imprint_id=30

Filter by category:

https://api.openpublishing.com/resource/v3/products?category_id=17

Filter by publication date:

https://api.openpublishing.com/resource/v3/products?publication_date__range=2023-01-01,2023-01-31
https://api.openpublishing.com/resource/v3/products?publication_date_ebook=2023-01-01
https://api.openpublishing.com/resource/v3/products?publication_date_book__gt=2023-01-01
https://api.openpublishing.com/resource/v3/products?publication_date_audiobook__lt=2023-01-01
https://api.openpublishing.com/resource/v3/products?publication_date_software=2023-01-01

The way the filters operate can be specified with a suffix separated with an underscore. If it is omitted, the operator is eq (equal). Common suffixes are: eq/ne (equality operators), lt, gt, le, ge (less and greater (or equal) than), startswith/endswith/contains.

  https://api.openpublishing.com/resource/v3/products?title__startswith=kafka

Filter by external identifiers:

https://api.openpublishing.com/resource/v3/products?external_identifier_type=klopotek&external_identifier_value=503107

external_identifier_type / external_identifier_value : Search for products with an external identifier set. The external identifier type is the category of the product, e.g. "paypal" whereas the value is the id itself. If only external_identifier_type is specified, all products with the external identifier type set are returned. If you search for only external_identifier_value - the system will return all identifiers with the value, where the type is not set.

Allowed methods: GET

Search Options

Limit results:

https://api.openpublishing.com/resource/v3/products?display=10

Use caching:

https://api.openpublishing.com/resource/v3/products?cache=yes

Sort results:

The results can be sorted according to specific criteria:

  • bestseller sort results by bestseller
  • most_read: sort results by most shop views
  • newest: sort results by newest publications

The sort order can be specified by appending the postfixes __asc and __desc. If it is omitted, the results are sorted in ascending order.

https://api.openpublishing.com/resource/v3/products?sort=bestseller__asc

Fields

Abstract

abstract is a field describing the abstract of the text. The value can be a string or null.

Audience

The audience subobject contains several fields describing the audience of the product.

  • age_range_from: Age from which the book is recommended. An integer number or null.
  • age_range_to: Age to which the book is recommended. An integer number or null.
  • audience_code: Audience code taken from ONIX Codelist 28.
  • onix_adult_audience_rating: Adult audience rating taken from ONIX Codelist 203.

Biographical note

biographical_note is a field describing the biographical notes of the text. The value can be a string or null.

Bisac categories

The field bisac contains a list of bisac categories. The bisac categories are listed with their identifiers as strings.

VLB Categories

The field vlb contains a list of (VLB)[https://vlb.de/assets/images/wgsneuversion2_0.pdf]. The list of strings contains the last three digits of each classification. The first character is added by OP automatically dependent on the product form.

Authors and other Contributors

The contributors subobject is an array of contributor elements. Each contributor element has the following fields:

  • academic_title: Academic title of person. String or null.
  • company_account: Boolean indicating if person is a company or a natural person. Defaults to false.
  • corporate_name: Corporate name. String or null.
  • first_name: First name of person. String or null.
  • last_name: Last name of person. String or null.
  • last_name_first: Boolean, indicating the order of last name and first name. Defaults to false.
  • prefix: Prefix of name. String or null.
  • role: Onix contributor role. See code list 17 for possible values. Defaults to A01 (Author). f textual work).
  • suffix: Suffix of name. String or null.
  • gender: Gender of person. m (male), f (female), d (diverse) or null.

The field copyright_year describes the year of the copyright. It is a String containing a year e.g. "2008" or null.

"copyright_year": null,

Eans

The field eans contains a list of all EANs of the product with the corresponding formats.

Example:

   "eans": [
      {
        "ean": "9783959122436",
        "formats": ["pdf", "epub"]
      },
      {
        "ean": "9783959122443",
        "formats": ["pod"]
      }
   ],

Product format

The format field contains an array of strings, describing the activated product format for the product. Available formats are:

  • epub: Ebooks in Epub format.
  • mobi: Ebooks in Mobipocket format.
  • pdf: Ebooks in PDF format.
  • ibooks: Ebooks in apple ibook format.
  • audiobook: Audio books.
  • software: Software.
  • pod: Print on demand titles.

Note: the field form is deprecated and must not be used anymore.

Identifier

The identifier field contains the Open Publishing internal unique identifier of the object.

Imprint

The imprint subfield contains a dict describing the imprint and publisher of the product. Fields of the subfield are:

  • city: City of the publisher.
  • country: Country of the publisher. Encoded as ISO 3166.
  • email: Email address of the publisher.
  • fax: Fax number of the publisher.
  • id: Open Publishing ID of the imprint.
  • imprint_name: Imprint name as string.
  • phone: Telephone number of the publisher. String or null.
  • publisher_name: Publisher name as string.

Note: Imprints are a 1:n relation within the Open Publishing eco system identified by a unique name or the id. It is recommended to maintain the publisher information within the Open Publishing backend and only set the corresponding ID via REST interface. When pulling the information the information from the corresponding Imprint is filled out automatically.

Keywords

The keywords field contains a list of keywords used for advertising the text. Each keyword is a string. Maximum length of each keyword is 255 bytes.

Labels

The labels field contains a list of strings internally used for marking and grouping products. These labels may be used to control the internal publishing workflow and are not exported to external partners.

Language

The value of the field language is the language code of the product. The value is a ISO-639-2/B language code (e.g. fre for french)

POD Settings

   "pod": {
      "back": null,
      "binding": "pb",
      "colored_pages": [],
      "cover_duplex": false,
      "cover_width": 302,
      "cover_height": 215,
      "finish": "matt",
      "hc_material": null,
      "height": 210,
      "ink_color": "monochrome",
      "number_of_pages": 224,
      "paper": "cream90gsm",
      "quality": "standard",
      "weight": null,
      "width": 148,
      "cover_trim": 3,
      "bookblock_trim": null
   }

The following fields may be configured within the pod node:

  • binding: binding type, possible values: pb (paper back), hc (hard cover), booklet (saddle stich binding), wireo (coil bound). The availability of the formats depend on the selected printers.
  • back: shape of book spine, possible values: straight,rounded or null for not specified. Only necessary for hard cover books.
  • hc_material: linen look for hard cover binding, possible values: cloth_red, efalin_blue, efalin_green, efalin_orange, efalin_gray, efalin_tan, efalin_black
  • cover_duplex: Indicate if inside of cover should be printed. Only available for a some printers.
  • paper: Type of paper for book block, possible values: cream80gsm (BOD: Chamois 80g), white80gsm (BOD: White 80g), cream90gsm (BOD: Chamois 90g), white90gsm (BOD: White 90g) , white70pound (US Market only), white80pound (US Market only)
  • finish: cover / dust jacket lamination, possible values: matt,glossy,textured.
  • quality: print quality, possible values: standard,premium
  • ink_color: printing ink, choose cmyk if title contains color pages, possible values: monochrome, cmyk.
  • colored_pages: Some printers require to specify the position of the colored pages if cmyq was selected as color.
  • height and width: format, in millimeter. null if not specified.
  • cover_height and cover_width: format of the cover, in millimeter. null if not specified. Width is the full width of the cover page, which means the the width of U1 and U4 plus the thickness.
  • number_of_pages: number of pages of the book block.
  • weight: in grams. null if not specified.
  • thickness: in millimeters. If not specified or set to null it will fallback to an calculated value.
  • bookblock_trim: in millimiters. Specifies the trim size of the book block. If this value is set to null, the book block trim is not checked.
  • cover_trim: in millimiters. Specifies the trim size of the cover. If this value is set to null, the cover trim is not checked.

Prices

The prices is a dict for all formats, each of which has a list of current prices for different countries. Example:

"prices": {
   "audiobook": [],
   "book": [],
   "ebook": [
      {
         "countries": [
            "DE"
         ],
         "currency": "EUR",
         "gross": 999,
         "net": 933.65,
         "vat": 65.36,
         "vat_percentage": 7
      },
      {
         "countries": [],
         "currency": "EUR",
         "gross": null,
         "net": 2000,
         "vat": null,
         "vat_percentage": null
      }
   ],
   "software": []
}

The detailled price definition can be read and written using the product prices resource.

Publication Date

The publication_date is a dict containing the publication date for each product type. Values are a date encoded as a string or null if no publication date is specified. Example:

    "publication_date": {
       "audiobook": "2019-06-02",
       "book": "2019-06-02",
       "ebook": "2019-06-02",
       "software": "2019-06-02"
    }

Publication status

The status field contains an enum describing the publication status of the product. Possible values are:

  • NEW: New unpublished products.
  • PUBLISHED: Products in active distribution.
  • DELETED: Products withdrawn from distribution / publication.

Subtitle

The field subtitle contains the subtitle of the product. The value can be a string or null.

Table of content

table_of_content is a field describing the table of content of the text. The value can be a string or null.

Thema categories

The field thema contains a list of thema categories. The thema categories are listed with their identifiers as strings.

Title

title is a field describing the biographical notes of the text. Title s a required field for each product.

External Identifiers

external_identifiers: List of external/foreign identifiers, e.g. the id of the business partner within Klopotek, Paypal or Amazon. The listed objects are dicts with the values type for the type of the identifier and value for the identifier itself.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Example JSON

{
    "_id": 1387,
    "abstract": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat",
    "audience": {
       "age_range_from": null,
       "age_range_to": null,
       "audience_code": "01",
       "description": null,
       "onix_adult_audience_rating": "00"
    },
    "biographical_note": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat",
    "bisac": [
        "SPO024000"
    ],
    "contributors": [
          {
             "academic_title": "Dr.",
             "company_account": false,
             "corporate_name": null,
             "first_name": "John",
             "gender": "m",
             "last_name": "Doe",
             "last_name_first": false,
             "prefix": null,
             "role": "A01",
             "suffix": null
          }
       ],
    "copyright_year": null,
    "eans": [],
    "external_identifiers": [
          {
             "type": "klopotek",
             "value": "110952107"
          }
    ],
    "formats": [
          "epub",
          "mobi"
    ],
    "identifier": "product.1393",
    "identifiers": {
       "isbns": {}
    },
    "imprint": {
       "city": "Munich",
       "country": "DE",
       "email": null,
       "fax": null,
       "id": 1429,
       "imprint_name": "Test Publisher",
       "phone": null,
       "publisher_name": "Test Publisher"
    },
    "keywords": [
          "lorem", "ipsum", "dolor", "si", "amet"
    ],
    "labels": [
          "summer2020", "kindledeal"
    ],
    "language": "ger",
    "pod": {
       "back": null,
       "binding": "booklet",
       "finish": "matt",
       "height": 210,
       "ink_color": "monochrome",
       "number_of_pages": null,
       "paper": "cream90gsm",
       "quality": "standard",
       "weight": null,
       "width": 148,
       "thickness": 12.5,
       "cover_trim": 3,
       "bookblock_trim": null
    },
    "publication_date": {
       "audiobook": "2019-06-02",
       "book": "2019-06-02",
       "ebook": "2019-06-02",
       "software": "2019-06-02"
    },
    "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
    },
    "status": "PUBLISHED",
    "subtitle": "Test subtitle",
    "table_of_content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat",
    "thema": [
           "AB"
    ],
    "title": "Test title"
}