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