2021 UPDATE: This page of documentation about our RESTful JSON API, whilst not deprecated yet, is aging fast. We are currently rolling out GraphQL read and write endpoints. If you want to interact programmatically with Consonance, please email support@consonance.app to begin a conversation about the appropriate tools to use.
Website feeds from Consonance via the product API
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 by raising a support ticket 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/v4/products.json"
The response is as follows.
{
"current_page":1,
"per_page":1,
"total_pages":1,
"url":"https://demo.consonance.app/api/v4/products.json",
"products":[
{
"id":94741,
"work_id":61417,
"full_title":"Consonance sample title",
"subtitle":null,
"pub_date":"2018-03-20",
"publishing_status":"04",
"out_of_print_date":null,
"product_form":"BC",
"edition_type_codes":null,
"edition_statement":null,
"in_house_format":"B format",
"in_house_edition":"Paperback",
"isbn":"No ISBN",
"product_doi":null,
"work_doi":null,
"work_type_name":null,
"season_name":null,
"marketing_tier_name":null,
"project_stage_name":null,
"lc_control_number":null,
"in_house_work_reference":null,
"publishers_url":null,
"imprint":"Api Demo",
"weblinks":[
],
"edition_number":null,
"extents":{
"page_count":320,
"main_content_page_count":null,
"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":"198 × 129 × 14",
"product_dimensions_in":"7.8125 × 5.125 × 0.5625",
"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":198.0,
"product_height_in":7.8125,
"product_width_mm":129.0,
"product_width_in":5.125
},
"authorship":"",
"authorship_overridden":false,
"series":[
],
"prices":[
{
"id":201388,
"currency_code":"GBP",
"price_amount":7.99,
"includes_tax":true,
"price_qualifier":"05"
},
{
"id":201389,
"currency_code":"USD",
"price_amount":14.95,
"includes_tax":false,
"price_qualifier":"05"
}
],
"contributors":[
],
"supportingresources":[
{
"id":254985,
"image_content_type":"image/png",
"onix3_code":"01",
"onix2_code":"04",
"content_audience":"00",
"approval":"approved",
"required_credit":null,
"caption":null,
"copyright":null,
"height":492,
"width":364,
"image_fingerprint":"5f539eff1ecf9a262d013b5f396c72a5",
"style_urls":[
{
"style":"jpg_rgb_0050w",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0050w.jpg"
},
{
"style":"jpg_rgb_0075w",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0075w.jpg"
},
{
"style":"jpg_rgb_0250w",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0250w.jpg"
},
{
"style":"jpg_rgb_0150h",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0150h.jpg"
},
{
"style":"jpg_rgb_0250h",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0250h.jpg"
},
{
"style":"jpg_rgb_0400h",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0400h.jpg"
},
{
"style":"jpg_rgb_0650h",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_0650h.jpg"
},
{
"style":"jpg_rgb_1500h",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_1500h.jpg"
},
{
"style":"jpg_rgb_original",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_rgb_original.jpg"
},
{
"style":"jpg_cmyk_original",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_jpg_cmyk_original.jpg"
},
{
"style":"tiff_original",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_tiff_original.tiff"
},
{
"style":"png_original",
"url":"https://bibliocloud-demo.fake-s3-eu-west-1.amazonaws.com/404/254985//_png_original.png"
}
]
}
],
"marketingtexts":[
{
"id":185527,
"code":"01",
"external_text":"A heartbreaking work of staggering genius.\u0026nbsp;",
"internal_text":"",
"alternate_external_text":"",
"alternate_internal_text":""
}
],
"subjects":{
"bic":{
"main_code":{
"code":"AVGS",
"text":"Reggae"
},
"additional_codes":[
{
"code":"ABC",
"text":"Conservation, restoration \u0026 care of artworks"
}
],
"educational_purpose_qualifiers":[
],
"geographical_qualifiers":[
],
"interest_age_qualifiers":[
],
"language_qualifiers":[
],
"special_interest_qualifiers":[
],
"time_period_qualifiers":[
]
},
"thema":{
"primary":{
"code":"ATFD",
"description":"Film scripts \u0026 screenplays"
},
"additional":[
{
"code":"ABA",
"description":"Theory of art"
}
],
"age":[
{
"code":"5AQ",
"description":"Interest age: from c 14 years"
}
],
"educational":[
{
"code":"4CTB",
"description":"For undergraduate education \u0026 equivalents"
}
],
"geographic":[
{
"code":"1DDB-BE-F",
"description":"Flanders"
}
],
"history":[
{
"code":"3BDK",
"description":"Stone Age: Mesolithic period"
}
],
"interest":[
{
"code":"5HCE",
"description":"Valentine’s Day"
}
],
"language":[
{
"code":"2ADFP",
"description":"Provencal"
}
],
"style":[
{
"code":"6AD",
"description":"Art Nouveau"
}
]
},
"bisac":{
"additional_codes":[
{
"code":"ANT002000"
}
],
"regional_themes":[
],
"merchandising_themes":[
]
},
"keywords":[
"sample book",
"trial",
"api",
"api docs",
"json response",
"restful"
]
},
"subject_ids":[
],
"main_subject_id":null,
"all_related_products":[
],
"marketing_highlight_work_ids":[
],
"audiences":{
"onix":[
]
},
"languages":[
],
"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":[
],
"origination_works":[
],
"derivation_works":[
],
"digest":"2079aba436d74be0dcd248f5dda11ba8"
}
]
}
With query parameters
1
curl -g -H "Authorization: Token token=b0c15687c2c3483b9efca116db0917b9" "https://demo.consonance.app/api/v4/products.json?q[id_eq]=94741"
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 correctq[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 asq[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.