Find out how to get your data programmatically via our API

Overview

The Consonance API gives you access to secure client product data for use in your own app. It strives to be RESTful and is organised around the main resources you’re familiar with from the Consonance interface.

Product API Basics

Before you do anything, contact us to register for an API key to make API calls. In the meantime, use the demo credentials on this page.

An example response

Paste the following into a terminal window, including the sample authorisation token provided.

  curl -g -H "Authorization: Token token=b0c15687c2c3483b9efca116db0917b9" "https://demo.consonance.app/api/v2/products.json"

The response is as follows.

{
   "current_page": 1,
   "per_page": 50,
   "total_pages": 10,
   "url": "https://demo.consonance.app/api/v2/products.json",
   "products": [
      {
         "id": 3384,
         "work_id": 714,
         "full_title": "Adept",
         "subtitle": null,
         "pub_date": "2004-05-01",
         "publishing_status": "04",
         "out_of_print_date": null,
         "product_form": "BC",
         "edition_type_codes": null,
         "edition_statement": null,
         "proprietary_format_description": "B format paperback",
         "isbn": "978-0-9545759-1-5",
         "edition_number": 1,
         "extents": {
            "page_count": 416,
            "main_content_page_count": 416,
            "number_of_words": null,
            "front_matter_page_count": null,
            "back_matter_page_count": null,
            "total_numbered_pages": null,
            "production_page_count": null,
            "absolute_page_count": null,
            "number_of_pages_in_print_counterpart": null,
            "notional_number_of_pages_in_print_counterpart": null,
            "content_page_count": null,
            "total_unnumbered_insert_page_count": null,
            "filesize_bytes": null
         },
         "measurements": {
            "product_dimensions_mm": "178 x 110",
            "product_dimensions_in": "7.01 x 4.33",
            "page_trim_dimensions_mm": null,
            "page_trim_dimensions_in": null,
            "page_trim_height_mm": null,
            "page_trim_height_in": null,
            "page_trim_width_mm": null,
            "page_trim_width_in": null,
            "product_height_mm": 178.0,
            "product_height_in": 7.008,
            "product_width_mm": 110.0,
            "product_width_in": 4.331
         },
         "authorship": "Robert Finn",
         "authorship_overridden": false,
         "series_ids": [
         ],
         "prices": [
            {
               "id": 168748,
               "currency_code": "GBP",
               "price_amount": 7.99,
               "includes_tax": true,
               "price_qualifier": "05"
            }
         ],
         "contributors": [
            {
               "id": 120,
               "sequence_number": 9,
               "contributor_role": "A01",
               "biographical_note": null,
               "name": "Robert Finn"
            }
         ],
         "supportingresources": [
            {
               "id": 206878,
               "resource_content_type": "07",
               "image_fingerprint": "0d396c690873bb44a641ddcfa17817b6",
               "style_urls": [
                  {
                     "style": "jpg_rgb_0050w",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0050w.jpg"
                  },
                  {
                     "style": "jpg_rgb_0075w",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0075w.jpg"
                  },
                  {
                     "style": "jpg_rgb_0250w",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0250w.jpg"
                  },
                  {
                     "style": "jpg_rgb_0150h",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0150h.jpg"
                  },
                  {
                     "style": "jpg_rgb_0250h",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0250h.jpg"
                  },
                  {
                     "style": "jpg_rgb_0400h",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0400h.jpg"
                  },
                  {
                     "style": "jpg_rgb_0650h",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_0650h.jpg"
                  },
                  {
                     "style": "jpg_rgb_1500h",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_1500h.jpg"
                  },
                  {
                     "style": "jpg_rgb_original",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_rgb_original.jpg"
                  },
                  {
                     "style": "jpg_cmyk_original",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_jpg_cmyk_original.jpg"
                  },
                  {
                     "style": "tiff_original",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_tiff_original.tiff"
                  },
                  {
                     "style": "png_original",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_png_original.png"
                  },
                  {
                     "style": "original",
                     "url": "https://bibliocloudimages.s3-eu-west-1.amazonaws.com/1/206878/714/714_original.jpg"
                  }
               ]
            }
         ],
         "marketingtexts": [
            {
               "id": 16269,
               "code": "01",
               "external_text": "It's a strange kind of robbery: nothing is missing and the only damage done is to the criminals. David Braun, star investigator for an exclusive insurance firm, discovers the truth that the crime was intended to conceal. Behind it all, a ruthless thief, who is intent on acquiring a priceless antique - an antique with a bloody history its owners would prefer to keep hidden. Susan Milton, an expert in exotic antiques, must unearth the object's past to make sense of the present. When she takes on the project she has no idea that her research will put her life in danger. As David and Susan learn to work together the pieces begin to fall into place, but the more they find out, the less they believe. Caught between powerful enemies and being hunted by a killer the police cannot catch, their only hope is to stay one step ahead. They know enough to put them in the worst danger of their lives. Will it also be enough to save them?",
               "internal_text": "It's a strange kind of robbery: nothing is missing and the only damage done is to the criminals. David Braun, star investigator for an exclusive insurance firm, discovers the truth that the crime was intended to conceal. Behind it all, a ruthless thief, who is intent on acquiring a priceless antique - an antique with a bloody history its owners would prefer to keep hidden. Susan Milton, an expert in exotic antiques, must unearth the object's past to make sense of the present. When she takes on the project she has no idea that her research will put her life in danger. As David and Susan learn to work together the pieces begin to fall into place, but the more they find out, the less they believe. Caught between powerful enemies and being hunted by a killer the police cannot catch, their only hope is to stay one step ahead. They know enough to put them in the worst danger of their lives. Will it also be enough to save them?",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16270,
               "code": "02",
               "external_text": "It's a British variant on The Da Vinci Code and The Rule of Four - Andrew Taylor",
               "internal_text": "It's a British variant on The Da Vinci Code and The Rule of Four - Andrew Taylor",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16275,
               "code": "25",
               "external_text": "Bestselling author with 70,000 copies sold; Top Ten Small Publisher Bestseller chart position for over a year; Sequel available - Ex Machina; Numerous foreign rights and film discussions underway - Italian, Serbian, Bulgarian, Russian, French and audio rights sold.",
               "internal_text": "Bestselling author with 70,000 copies sold; Top Ten Small Publisher Bestseller chart position for over a year; Sequel available - Ex Machina; Numerous foreign rights and film discussions underway - Italian, Serbian, Bulgarian, Russian, French and audio rights sold.",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16276,
               "code": "08",
               "external_text": "\"An impressively ambitious debut that marries the crime novel with the occult thriller...It's a British variant on The Da Vinci Code and The Rule of Four.\" Andrew Taylor, twice winner of the CWA Ellis Peters Dagger",
               "internal_text": "\"An impressively ambitious debut that marries the crime novel with the occult thriller...It's a British variant on The Da Vinci Code and The Rule of Four.\" Andrew Taylor, twice winner of the CWA Ellis Peters Dagger",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16437,
               "code": "25",
               "external_text": "Popular acclaim and word of mouth bestseller; Adept was compared to The Da Vinci Code and The Rule of Four; Sales have been consistently strong and this omnibus presents excellent value for money. Prequel to \u003ci\u003eAdept\u003c/i\u003e and \u003ci\u003eEx Machina\u003c/i\u003e out now --\u0026nbsp;\u003ci\u003eUnderlife\u003c/i\u003e.",
               "internal_text": "Popular acclaim and word of mouth bestseller; Adept was compared to The Da Vinci Code and The Rule of Four; Sales have been consistently strong and this omnibus presents excellent value for money. Prequel to Adept and Ex Machina out now - Underlife.",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16511,
               "code": "25",
               "external_text": "Bestselling author with 40,000 copies sold; Top Ten Small Publisher Bestseller chart position for over a year; Sequel available - Ex Machina; Numerous foreign rights and film discussions underway - Italian, Serbian, Bulgarian, Russian, French and audio rights sold. Prequel to Adept and Ex Machina coming out Summer 2007 - Underlife.",
               "internal_text": "Bestselling author with 40,000 copies sold; Top Ten Small Publisher Bestseller chart position for over a year; Sequel available - Ex Machina; Numerous foreign rights and film discussions underway - Italian, Serbian, Bulgarian, Russian, French and audio rights sold. Prequel to Adept and Ex Machina coming out Summer 2007 - Underlife.",
               "alternate_external_text": null,
               "alternate_internal_text": null
            },
            {
               "id": 16512,
               "code": "08",
               "external_text": "The Observer Review (World of Books) said it had achieved \"a measure of success rare among new, small publishers\" newBOOKSmagazine said it was \"a very stylish thriller... witty, entertaining and totally original.\"",
               "internal_text": "The Observer Review (World of Books) said it had achieved \"a measure of success rare among new, small publishers\" newBOOKSmagazine said it was \"a very stylish thriller... witty, entertaining and totally original.\"",
               "alternate_external_text": null,
               "alternate_internal_text": null
            }
         ],
         "subject_ids": [
            9
         ],
         "main_subject_id": 9,
         "all_related_products": [
            {
               "relation_code": "06",
               "product_id": 3728,
               "isbn": "978-1-907777-01-1"
            },
            {
               "relation_code": "22",
               "product_id": 3407,
               "isbn": "978-1-905005-06-2"
            },
            {
               "relation_code": "22",
               "product_id": 3418,
               "isbn": "978-1-905005-30-7"
            },
            {
               "relation_code": "22",
               "product_id": 3447,
               "isbn": "978-1-905005-64-2"
            },
            {
               "relation_code": "22",
               "product_id": 3461,
               "isbn": "978-1-905005-69-7"
            },
            {
               "relation_code": "22",
               "product_id": 3465,
               "isbn": "978-1-905005-70-3"
            },
            {
               "relation_code": "22",
               "product_id": 3470,
               "isbn": "978-1-905005-92-5"
            },
            {
               "relation_code": "22",
               "product_id": 3663,
               "isbn": "978-1-907777-15-8"
            },
            {
               "relation_code": "22",
               "product_id": 3668,
               "isbn": "978-1-907777-20-2"
            },
            {
               "relation_code": "22",
               "product_id": 3726,
               "isbn": "978-1-905005-57-4"
            },
            {
               "relation_code": "22",
               "product_id": 3728,
               "isbn": "978-1-907777-01-1"
            },
            {
               "relation_code": "27",
               "product_id": 3728,
               "isbn": "978-1-907777-01-1"
            }
         ],
         "marketing_highlight_work_ids": [

         ],
         "rights_available_countries": [
            "AD",
            "AE",
            "AF",
            "AG",
            "AI",
            "AL",
            "AM",
            "AO",
            "AQ",
            "AR",
            "AS",
            "AT",
            "AU",
            "AW",
            "AX",
            "AZ",
            "BA",
            "BB",
            "BD",
            "BE",
            "BF",
            "BG",
            "BH",
            "BI",
            "BJ",
            "BL",
            "BM",
            "BN",
            "BO",
            "BQ",
            "BR",
            "BS",
            "BT",
            "BV",
            "BW",
            "BY",
            "BZ",
            "CA",
            "CC",
            "CD",
            "CF",
            "CG",
            "CH",
            "CI",
            "CK",
            "CL",
            "CM",
            "CN",
            "CO",
            "CR",
            "CU",
            "CV",
            "CW",
            "CX",
            "CY",
            "CZ",
            "DE",
            "DJ",
            "DK",
            "DM",
            "DO",
            "DZ",
            "EC",
            "EE",
            "EG",
            "EH",
            "ER",
            "ES",
            "ET",
            "FI",
            "FJ",
            "FK",
            "FM",
            "FO",
            "FR",
            "GA",
            "GB",
            "GD",
            "GE",
            "GF",
            "GG",
            "GH",
            "GI",
            "GL",
            "GM",
            "GN",
            "GP",
            "GQ",
            "GR",
            "GS",
            "GT",
            "GU",
            "GW",
            "GY",
            "HK",
            "HM",
            "HN",
            "HR",
            "HT",
            "HU",
            "ID",
            "IE",
            "IL",
            "IM",
            "IN",
            "IO",
            "IQ",
            "IR",
            "IS",
            "IT",
            "JE",
            "JM",
            "JO",
            "JP",
            "KE",
            "KG",
            "KH",
            "KI",
            "KM",
            "KN",
            "KP",
            "KR",
            "KW",
            "KY",
            "KZ",
            "LA",
            "LB",
            "LC",
            "LI",
            "LK",
            "LR",
            "LS",
            "LT",
            "LU",
            "LV",
            "LY",
            "MA",
            "MC",
            "MD",
            "ME",
            "MF",
            "MG",
            "MH",
            "MK",
            "ML",
            "MM",
            "MN",
            "MO",
            "MP",
            "MQ",
            "MR",
            "MS",
            "MT",
            "MU",
            "MV",
            "MW",
            "MX",
            "MY",
            "MZ",
            "NA",
            "NC",
            "NE",
            "NF",
            "NG",
            "NI",
            "NL",
            "NO",
            "NP",
            "NR",
            "NU",
            "NZ",
            "OM",
            "PA",
            "PE",
            "PF",
            "PG",
            "PH",
            "PK",
            "PL",
            "PM",
            "PN",
            "PR",
            "PS",
            "PT",
            "PW",
            "PY",
            "QA",
            "RE",
            "RO",
            "RS",
            "RU",
            "RW",
            "SA",
            "SB",
            "SC",
            "SD",
            "SE",
            "SG",
            "SH",
            "SI",
            "SJ",
            "SK",
            "SL",
            "SM",
            "SN",
            "SO",
            "SR",
            "SS",
            "ST",
            "SV",
            "SX",
            "SY",
            "SZ",
            "TC",
            "TD",
            "TF",
            "TG",
            "TH",
            "TJ",
            "TK",
            "TL",
            "TM",
            "TN",
            "TO",
            "TR",
            "TT",
            "TV",
            "TW",
            "TZ",
            "UA",
            "UG",
            "UM",
            "US",
            "UY",
            "UZ",
            "VA",
            "VC",
            "VE",
            "VG",
            "VI",
            "VN",
            "VU",
            "WF",
            "WS",
            "YE",
            "YT",
            "ZA",
            "ZM",
            "ZW"
         ],
         "rights_not_available_countries": [

         ],
         "digest": "cecf19a3deff6ac9e08e1967136b50ad"
      }
   ]
}

With query parameters

  curl -g -H "Authorization: Token token=b0c15687c2c3483b9efca116db0917b9" "https://demo.consonance.app/api/v2/products.json?q[id_eq]=[1]"

Predicates

q[id_eq]

int32. Get a product by its Consonance ID

q[id_in][]

int32. Get a set of products by their ID. Can be chained e.g. q[id_in][]=ID&q[id_in][]=ID

q[work_id_eq]

int32. Get products by work id

q[work_title_eq]

string. Get products by title

q[shops_id_eq]

int32. Get the products that belong to a shop

q[subjectcodes_id_eq]

int32. Get the products with a particular subject code

q[seriesnames_id_eq]

int32. Get the products belonging to a particular series

q[publishing_status_eq]

string. Get the products with a particular ONIX product publishing status

digest_only

boolean. Return the digest if you want to check for incremental changes

version

int32

page

int32. Page of the response

page_size

int32. Number of products per page. Defaults to 50.

Incorrect syntax in the query parameters will be silently ignored, so if you used a parameter q[publishing_status] instead of the correct q[publishing_status_eq] then the filter would not be applied. During development we suggest that you use a deliberately incorrect value that should return no products, such as q[subjectcodes_id_eq]=123456789, and if results are returned then the syntax is probably incorrect.

ONIX code lists

The API codes are generally from the ONIX 2.1 codelists. A complete set can be downloaded from the onix_code_lists.json end point, or the Editeur codelist browser can be used.