Common Parameters

There are many common parameters that apply to any of the endpoints.

Paging and Sorting

These parameters are available on the common request object that all resources consume but obviously only make sense when generating a list of objects.

start

(numeric,default=0) the index of the first row to be returned. Zero-based so 'start=10' indicates to start with the eleventh record.

rows

(numeric,default=10) the number of rows to be returned. Set to zero to return all available rows.

sort

one of id, name, onsale, frontlistiest_onsale, title, authorLast, score, random, award, awardDate, eventdate, frontlistiest, seq, seriesDate, seriesNumber, printScore, price, format, permissionsPopularity or weight. Not all choices work/make sense with all resources. If price is selected, you must also specify sortPriceTypeCode to indiciate which pricing value should be used for sorting.

dir

either asc or desc

zoom

(list) specify which objects should be included with the response (see the "Zoom/Embed" documentation page).

suppressLinks

(boolean) set to 'true' to have all _links array elements returned as empty.

suppressRecordCount

(boolean) set to 'true' to have the top-level recordCount element returned with a null. Since computing the number of records in the results usually requires a separate query, this may reduce the processing time for requests that don't require this data.

returnEmptyLists

(boolean) in cases where a request returns no objects, the default behavior of the API is to return an HTTP 404. However you can set this parameter to 'true' to have it instead return an HTTP 200 and an empty results array.

preferLanguage

you may specify a single language code (e.g. 'E', 'SP') to have the first sort criteria be a boolean match against a TITLE or WORK record's language; this supersedes and is independent of the specified sort

sortPriceTypeCode

restrict a price sort to a valid price type identifier (e.g. 'USD', 'CAD')

Filters

Many of the common parameters are filters on titles (i.e. ISBN-based) or works (i.e. a collection of titles identified by a work ID). When these parameters are supplied to an endpoint that returns other types of results such as authors or categories, then the filters should be interpreted as "return only items that have at least one work that satisfies all the supplied criteria".

List filters

All of these parameters can be specified multiple times. For example you could specify "/works?workId=123&workId=456" to generate a listing of two work records. In terms of SQL, these parameters are implemented with an "IN" clause.

workId

(numeric,list) restrict results based on one or more work IDs (see /works)

isbn

(numeric,list) restrict results based on one or more ISBNs (see /titles)

authorId

(numeric,list) restrict results based on one or more author IDs (see /authors)

divisionCode

(list) restrict results based on one or more division codes (see /divisions)

imprintCode

(list) restrict results based on one or more imprint codes (see /imprints)

seriesCode

(list) restrict results based on one or more series codes (see /series)

format

(list) restrict results based on one or more format codes (see /formats)

formatFamily

(list) restrict results based on one or more format family labels (one of Paperback, Hardcover, Ebook, Board Book, Boxed Set, Audio, App, or Merchandise)

eventId

(numeric,list) restrict results based on one or more event IDs (see /events)

catId

(numeric,list) restrict results based on one or more category IDs (see /categories)

catUri

(list) restrict results based on one or more category alternate identifiers. Using 'catUri' instead of 'catId' can be useful to make parameters more readable.

catSetId

(list) restrict category listings to one or more category groups

titleWebLinkAttr

(numeric, list) results must contain a title weblink entry with one of the specified attrs

authorWebLinkAttr

(numeric, list) results must contain an author weblink entry with one of the specified attrs

contribRoleCode

(list) restrict by one or more contributor role codes (e.g. 'A', '4')

consumerImprint

(list) restrict results based on one or more consumer imprint values (e.g. 'BlueRiderPress','Penguin Audio')

language

(list) restrict results based on one or more language values (e.g. 'E', 'SP')

catSeq

(numeric, list) restrict results based on the sequencing of the categories assigned to title records. This is typically used to select the a title's primary BISAC code.

productLine

(list) restrict results based on one or more title product line values

productType

(list) restrict results based on one or more title product type values

ageRange

(list) restrict results based on one or more title age range values (e.g. '0005', '0408')

salesRestriction

(list) restrict results based on one or more sales restriction codes (e.g. '00', '01')

saleStatus

(list) restrict results based on one or more sale status codes (e.g. 'IP','OS')

subFormat

(list) restrict results based on one or more subformat codes (e.g. '001','BE')

subSeries

(list) restrict results based on one or more subseries values (e.g. 'The Rift')

propertyName

restrict results based on one or more propertyname values (e.g. 'Sesame Street')

List filters - exclusive

These filters are used to omit certain items from the result set. In terms of SQL, these parameters are implemented with a "NOT IN" clause.

ignoreIsbn

(numeric,list) omit one or more ISBNs or any records linked to those titles

ignoreWork

(numeric,list) omit one or more work IDs or any records linked to those works

ignoreAuthor

(numeric,list) omit one or more author IDs or any records linked to those authors

ignoreFormatFamily

(list) omit records linked to one or more format families

ignoreFormatCode

(list) omit records linked to one or more format codes

ignoreCatUri

(list) omit records linked to one or more category URIs -- only works with /categories, /titles and /works

ignoreSeries

(list) omit records linked to one or more series codes

ignoreContribRole

(list) omit records linked to one or more contrib role codes

ignoreSubFormat

(list) omit records linked to one or more sub format codes

ignoreProductLine

(list) omit records linked to one or more product line codes

ignoreProductType

(list) omit records linked to one or more product type codes

Single value filters - numeric

These filter parameters can only take a single numeric value.

minInPrint

(numeric) works must have a LTD in-print across all titles greater than the specified number

minPrintScore

(numeric,default=0) same as 'minInPrint' except that the LTD in-print value is adjusted according to business rules (e.g. MM titles are not counted)

awardMaxSeq

(numeric) restrict results to award winners where the award sequence is less than or equal to the specified value

ageRangeMin

(numeric) restrict results to titles with an age range greater than or equal to the specified value

ageRangeMax

(numeric) restrict results to titles with an age range less than or equal to the specified value

Single value filters - date

onSaleFrom

(date) restrict results to on-sale dates on or after the supplied date (MM/dd/yyyy)

onSaleTo

(date) restrict results to on-sale dates on or before the supplied date (MM/dd/yyyy)

workOnSaleFrom

(date) restrict results to works with on-sale dates on or after the supplied date (MM/dd/yyyy)

workOnSaleTo

(date) restrict results to works with on-sale dates on or before the supplied date (MM/dd/yyyy)

Boolean flags

These filter parameters take a boolean either as text like true' or false' or as a numeric like '1' or '0'.

showAwards

(boolean) results must have an awards record

showBestsellers

(boolean) results must have a bestsellers record

showNewReleases

(boolean) results must have an on-sale date between today and 180 days ago

showComingSoon

(boolean) results must have an on-sale date between today and 90 days from now

showPublishedBooks

(boolean) results must have an on-sale date of today or earlier

showCovers

(boolean) titles must have a cover image

showReadingGuides

(boolean) results must have reading guide content

showTeachersGuides

(boolean) results must have teachers guide content

showBoxBundles

(boolean) restrict results to include or exclude titles that have the 'Boxed Set' format family or are identified by their short title as E-book bundles

showNoTitleBlock

(boolean) restrict results to only include titles that have a NULL 'titleBlock' element

showMovieTieIn

restrict results to only include titles with the 'MOVIE_TIE_IN' flag set

showExportOnly

restrict results based on the presence of the 'flag' value 'EXPORT' on the Title record

hasSeriesNumber

(boolean) restrict results to titles that have their series number field populated

Performance

These parameters toggle certain elements of the standard representation which can improve performance if they are not required by the client.

suppressLinks

(boolean,default=false) don't populate the "_links" elements

suppressRecordCount

(boolean,default=false) don't populate the top-level "recordCount" element; this can be a big time savings for certain queries that are listing unusual populations