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.

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

Please refer to resource queries sytax to filter and refine your search results.

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.

General fulltext query:

https://api.openpublishing.com/resource/v3/products?q=american%20studies

Search for the specified string in all text fields. Must not be combined with other filters.

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 (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 (integer number or null).
age_range_to: Age to which the book is recommended (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 (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. 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 ONIX Codelist 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.

Copyright year

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.

The related_products field contains a list of other products that have a specific relationship to the product.

Every item in related_products has the following structure:

_id: ID of the relation
ean: EAN of the related product (string or null).
relation_code: relation code which identifies the nature of the relationship between two products ONIX Codelist 51.
product: reference to the related product object
redirect: boolean value that indicates whether the visitor to the product page in the shop should be redirected to the related product. Note: if several related products have the value set to true, the visitor will be redirected to the first one.
combine_product_information: boolean value that indicates whether the information (e.g. EAN) of the related product should be displayed on the page of the product in the shop.

Read Example:

"related_products": [
    {
        "_id": 3633,
        "combine_product_information": true,
        "ean": null,
        "redirect": false,
        "product": {
            "_id": 56221,
            "_links": {
               "files": "https://api.openpublishing.com/resource/v3/products/56221/files",
               "prices": "https://api.openpublishing.com/resource/v3/products/56221/prices",
               "self": "https://api.openpublishing.com/resource/v3/products/56221",
               "storefronts": "https://api.openpublishing.com/resource/v3/products/56221/storefronts",
               "suppliers": "https://api.openpublishing.com/resource/v3/products/56221/suppliers"
            },
            "eans": [
               {
                  "ean": "9787980293820",
                  "formats": [
                     "epub",
                     "ibooks",
                     "mobi",
                     "pdf"
                  ],
                  "isbn": "978-7-9802-9382-0"
               }
            ],
            "title": "The Quantum Mosaic: Unraveling the Universe's Smallest Mysteries"
        },
        "relation_code": "23"
    },
    {
        "_id": 9548,
        "combine_product_information": false,
        "ean": "9788604053325",
        "redirect": false,
        "product": {
            "_id": 56642,
            "_links": {
               "files": "https://api.openpublishing.com/resource/v3/products/56642/files",
               "prices": "https://api.openpublishing.com/resource/v3/products/56642/prices",
               "self": "https://api.openpublishing.com/resource/v3/products/56642",
               "storefronts": "https://api.openpublishing.com/resource/v3/products/56642/storefronts",
               "suppliers": "https://api.openpublishing.com/resource/v3/products/56642/suppliers"
            },
            "eans": [
               {
                  "ean": "9788604053325",
                  "formats": [
                     "epub",
                     "ibooks",
                     "mobi",
                     "pdf"
                  ],
                  "isbn": "978-8-6040-5332-5"
               }
            ],
            "title": "Energy Horizons: The Science of Sustainable Power"
        },
        "relation_code": "05"
    }
]

Write Example:

"related_products": [
    {
        "_id": 3633,
        "combine_product_information": false,
    },
    {
        "ean": "9788604053325",
        "relation_code": "27"
    }
]

Series

The series field contains a list of series to which the product belongs. Each entry contains a reference to the series _id (s. series) and a volume number number. Each series is represented with a basic set of metadata, providing an overview of its key attributes. For comprehensive information about a specific series, refer to the URL provided for the corresponding series resource (_links.self).

Read Example:

"series": [
   {
      "_id": 16077,
      "_links": {
         "metrics": "https://api.openpublishing.com/resource/v3/series/16077/metrics",
         "self": "https://api.openpublishing.com/resource/v3/series/16077"
      },
      "issn_online": null,
      "issn_print": null,
      "name": "Oriental University Studies",
      "number": "551"
   }
]

When saving, only the fields _id, which is required for series assignment, and the field number are saved.

Write Example:

"series": [
   {
      "_id": 16077,
      "number": "551"
   },
   {
      "_id": 16096,
      "number": "13"
   }
]

Sets

The sets field contains a list of sets to which the product belongs. Each entry contains a reference to the set _id (s. set) and a volume number number. Each set is represented with a basic set of metadata, providing an overview of its key attributes. For comprehensive information about a specific sets, refer to the URL provided for the corresponding sets resource (_links.self).

Read Example:

"sets": [
   {
      "_id": 361,
      "_links": {
         "metrics": "https://api.openpublishing.com/resource/v3/sets/361/metrics",
         "self": "https://api.openpublishing.com/resource/v3/sets/361"
      },
      "identifier": "CHILDREN_LITERATURE",
      "name": "Classic Children's Literature Set",
      "number": "3"
   }
]

When saving, only the fields _id, which is required for sets assignment, and the field number are saved.

Write Example:

"sets": [
   {
      "_id": 361,
      "number": "3"
   },
   {
      "_id": 557,
      "number": "4"
   }
]

Subtitle

The field subtitle contains the subtitle of the product (string or null).

Table of content

table_of_content is a field describing the table of content of the text (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"
}

Product Resource

Introduction

Example URL

Search Filters

Search Options

Fields

Abstract

Audience

Biographical note

Bisac categories

VLB Categories

Authors and other Contributors

Copyright year

Eans

Product format

Identifier

Imprint

Keywords

Labels

Language

POD Settings

Prices

Publication Date

Publication status

Related Products

Series

Sets

Subtitle

Table of content

Thema categories

Title

External Identifiers

Realm

Example JSON