Bowker Book Meta Data Documentation

Book Meta Data Service Documentation

Overview
Authentication
Identification of Records
Application Programming Interface
Reference Clients
Field Groups
- Basic
- Value-Added

Overview

The primary function of the Book Meta Data Service (hereto forth, BMS) is to allow a client program to access the information that Bowker maintains on books and other media.

The client can obtain a list of records that satisfy a request or it can obtain details about a single record. The client can indicate what information it wants for each record, or it can simply state that it wants all information available for each record.

For example, to obtain the title and author associated with an ISBN, a client could issue a request like this one:

http://bms.bowker.com/rest/books/isbn/0-262-19502-X?fields=title,author

If the client wanted the result as an HTML page, it could tack a format parameter to the above request, like this:

http://bms.bowker.com/rest/books/isbn/0-262-19502-X?fields=title,author&format=html

Authentication

The BMS uses HTTP Basic Authentication. The client program must provide credentials using Basic Authentication. The Perl reference client described later shows how to easily authenticate in Perl.

Based on the ID of an authenticated user, the BMS will provide the user with access to one or more markets and will allow the user to request specific fields. A user with the highest access level would be able to view records in every market and would have unrestricted access to fields so that, for a given record, all the information available to the BMS would be available also to the user.

A user with a low access level might, for example, be able to view records in the USA market and might be able to retrieve only Title, Subtitle, Author, and ISBN information for any record.

Identification of Records

Because the BMS tracks multiple records with the same ISBN, an ISBN alone is not sufficient to identify a record uniquely. And some records don't even have an ISBN. The BMS provides a special ID that identifies a record uniquely, the BMSID. When a client issues a query that includes a BMSID, the query is guaranteed to return a single record.

Where a record identified by a BMSID contains an ISBN, ISBN-13, EAN, or UPC, the BMSID can be considered immutable; it will always point to the same book. Most of the records that Bowker maintains (by far) fall into this catetgory. However, there are some records for which Bowker doesn't have a formal identifier. For these records, the BMSID is not guaranteed to always point to the same book. However, when the BMS uses a BMSID to reference one of these records, the reference will work for some time (most likely a long time).

Application Programming Interface

Overview of API

The BMS uses a RESTful interface to expose book meta data. URIs are meaningful and for the most part static. They are easy to share. Consuming data is simple for any kind of client, including Web browsers, Perl, C#, Python, Ruby, XQuery, and even JavaScript.

Requests

The BMS allows you to obtain information about books in several ways. You can request information by providing a BMSID (which is a number that Bowker assigns to each book that it tracks -- see the section "Resource Representation," ahead), a standard ISBN, a DOI, a title, an author, a subject, or a more complex search that involves one or more of ISBN, DOI, Title, Author, or Subject. The general URI format for these requests is as follow:

ID: http://bms.bowker.com/rest/books/id/[number]
One field: http://bms.bowker.com/rest/books/isbn/[number]
Multiple fields: http://bms.bowker.com/rest/books/search?title=[text]&subject=[text]

Strings that you provide for search parameters should be URL encoded.

String Searches

If you provide more than one of the search parameters (ISBN, DOI, Title, Author, Subject), the BMS returns only records that meet all the supplied criteria. (The search values are logically ANDed). Also, when you provide a search string for one of the parameters title, author, or subject, the BMS tokenizes the search string (splits it into words) so that the string will match records where the words are out of order. This allows the search title=things little to match the record with title "All the Little Things." However, you when you enclose a string in quotes, the string is processed as a single word. Thus, the search title="things little" will not match the aforementioned title.

Responses

The BMS responds with two types of resources when successful:

search results — A list of resources that satisfy the client's request
record details — Detailed information about a specific record (like a book, for example)

The BMS always returns a search results resource except when the query includes a BMSID, in which case the BMS understands that only one record could ever satisfy the query and the BMS returns a record details resource.

The search results resource contains one or more records that, by default, consist only of a reference to a record details resource. Using the fields parameter, however, clients can specify the fields that the BMS should include in each record of a search results resource.

The record details resource also allows the client to specify the fields that the BMS should provide.

Rather than listing fields individually for the field parameter, the client can provide the value 'all', which the BMS will interpret depending on whether the BMS is returning a search results resource or a record details resource. When returning a search results resource, the BMS interprets the fields value 'all' to mean that the user wants all the fields that are not too long. So annotations, chapter1, and other such fields will be excluded from the records in the search results resource. However, the client can override this behavior by explicitly listing the fields that the BMS should display for records in the search results resource.

When returning a record details resource, the BMS interprets the fields value 'all' to mean exactly that, all, and the BMS returns every field that the client has access to and that is available for each record, including long fields.

Resource Representation

Each record details resource or search results resource that the BMS exposes to clients is in actuality the result of a search. The BMS performs the search using the parameters that the client provides. The BMS then formats the result from the Mark Logic server and possibly excludes certain fields depending on the client's access rights.

Clients that request XHTML-formatted resources have the option of using CSS to format the resources in any way they see fit for consumption by end users. When the BMS returns a resource in XHTML format (pursuant to the client's format parameter submission), the XHTML code is tagged so that creating a CSS style sheet for the XHTML fragment is easy. Every XHTML tag contains a class attribute that is fairly unique and that can be referenced in CSS.

Bowker references each unique resource that resolves to a record in BIPOL with a Book Meta Data Service ID (BMSID). A BMSID is a number that uniquely identifies records in Bowker's database. A given title, like "Cryptonomicon," might have a dozen records in our database; a BMSID can identify only one of them.

Resource URIs

The resources listed here support only the HTTP GET method. In essence, you can request a record list or the details for a record with one of the following types of URIs:

/rest/books/id/[number]
/rest/books/isbn/[number]
/rest/books/upc/[number]
/rest/books/oclc/[number]
/rest/books/anyof?isbn=[number]&upc=[number]&oclc=[number]
/rest/books/doi/[number]
/rest/books/title/[text]
/rest/books/author/[text]
/rest/books/subject/[text]
/rest/books/binding/[text]
/rest/books/status/[text]
/rest/books/publisher/[text]
/rest/books/search?query_string
/rest/books/extract/[text]?resume=[text]

/rest/books/id/[number]

This resource consists of one element: details about a unique item. The number is a BMSID.

The resource accepts the following parameters:

Results Details
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter.
- filterdata
  See the section The filterdata Parameter.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.
Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/isbn/[number]

This resource consists of book records that share the specified ISBN. The URI returns a list with one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- upc
- oclc
- doi
- title
- author
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains contain these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.
- merge
  Setting this parameter to 1 causes the BMS to merge all the market records into a single ISBN record. This allows the BMS to return a single "book" record when many market records are found but they all represent a single ISBN.

/rest/books/upc/[number]

This resource consists of book records that share the specified UPC. The URI returns a list with one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- oclc
- doi
- title
- author
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains contain these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/oclc/[number]

This resource consists of book records that share the specified OCLC number. The URI returns a list with one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- doi
- title
- author
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains contain these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/anyof

This resource consists of book records that shared the specified ISBN, UPC, or OCLC. The caller must provide one or more of the following parameters: isbn, upc, oclc. The BMS attempts to find one or more records that match one of the parameters. If the client provides more than one of the parameters, the BMS tries to find matching records using isbn first (if the client provided a value for that parameter), then upc, then oclc. Where the BMS would normally return an error when there's a problem with one of the parameters, the BMS instead proceeds to the next client-supplied parameter. Only when the BMS encounters errors for every parameter does the BMS return an error to the client.

As soon as the BMS finds matching records for a type, it returns results as if the caller had requested a resource in one of these ways:

/rest/books/isbn/[number]
/rest/books/upc/[number]
/rest/books/oclc/[number]

When the client requests a resource with anyof, the BMS includes an additional matchtype attribute in the root tag (the <result> tag). The matchtype attribute tells the client which ID type of the ones that the client provided (isbn, upc, or oclc) allowed the BMS to match records.

When attempting to retrieve metadata for a record for which several ID types are known, the client can significantly speed up the search and delivery of that metadata by using the anyof parameter. The alternative is for the client to make separate calls with each ID type until the BMS returns results.

/rest/books/doi/[number]

This resource consists of book records that share the specified DOI. The URI returns a list with one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- title
- author
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains contain these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/title/[text]

This resource represents a list of elements: all the books that contain the specified keywords in their title, subtitle and or series title. This URI returns a list with one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- author
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains contain these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/author/[text]

This resource represents a list of elements: all the books that share the given author. This URI will return a list with more one or more elements.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- title
- subject
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, and xml. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/book/subject/[text]

This resource represents a list of elements: all the books that share the given subject. This URI returns a list with more than one element.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- title
- author
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/binding/[text]

This resource represents a list of elements: all the books that share the given binding. This URI returns a list with more than one element.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- title
- author
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/status/[text]

This resource represents a list of elements: all the books that share the given status. This URI returns a list with more than one element.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- title
- author
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/publisher/[text]

This resource consists of book records that share the specified publisher name. This URI returns a list with more than one element.

Each item in the result list represents a specific resource (a unique book) and includes a reference to the details for that resource.

The list resource accepts the following parameters:

Limiters
- isbn
- upc
- oclc
- doi
- title
- author
- binding
- status
- publisher
- qtext

Results Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/search

Search Criteria
- isbn
- upc
- oclc
- doi
- title
- author
- subject
- binding
- status
- publisher
- qtext

Result Details
- descending
  When you sort search results with the sort parameter, the BMS sorts in ascending order by default. If you provide the parameter descending=true, the BMS will sort results in descending order instead.
- fields
  A comma-separated list of fields that you want in the response. The section Fields lists valid values for this parameter. Each element in the response list contains these fields. Although it is possible to obtain all the information for each record in the list, Bowker advises that clients obtain a search-results list first, then use the BMSID provided with each record in the list to obtain details of the record in a separate call. In most cases, details for a record should be presented to the end user as one page.
- filterdata
  See the section The filterdata Parameter.
- page
  When the BMS returns a large result set, it splits up the result into pages, with each page containing a portion of the results. If the result set is large enough to spread over more than one page and the client doesn't specify which page it wants, the BMS assumes the client wants page 1.
- pagesize
  The maximum number of results to display per page (see the page parameter).
- sort
  Use this parameter to sort the search results. The following values are legal: title, author, price, isbn, binding, and pubdate.
- userinfo
  When the client sets this parameter to the value 1, the BMS returns user-information attributes in the parent tag.

Result Format
- format
  Valid formats are html_fragment, html_page, xml, and js. If the BMS doesn't see this parameter within the query string, the BMS assumes the value xml for this parameter.

/rest/books/extract/[text]

This resource supports the bulk extraction, also known as harvesting, of all book meta data records. Harvesting allows clients to keep remote databases synchronized with changes to the book records that the BMS exposes.

When issuing a request to this resource with no parameters, the BMS will return the BMSIDs for all of the book records in the order that each record has been modified, starting with the earliest. These results will be segmented into separate pages so as to not overload our servers. The size of each page can be controlled with the count parameter. Results from this resource will always contain a resume attribute, which represents the resumption token. A resumption token is a string that signifies to the BMS which record to start with to resume the harvesting of data. A client should parse the resumption token from a response, and issue a subsequent request using that token as the value for the resume parameter. This should be repeated continuously to keep a remote database synchronized.

The resource accepts the following query parameters:

resume
Resumption token instructing the BMS which record to start with to resume the harvesting of data.
count
A positive integer indicating number of records to return (default: 10000).

The resource accepts the following URL path parameter, [text], which is an optional string that constrains the list of book meta-data records to be extracted. All book meta data records will be extracted when this parameter is not provided. The following values are supported:

ice: Extract book meta data records that contain Syndetics ICE meta-data.

Please note that each BMSID returned uniquely identifies one specific book record, and a subsequent call to the /rest/books/id/ resource must be issued to grab the necessary meta-data.

Parameter Description

The resource URIs described in the previous section accept a number of parameters. Most of them are easy to understand and use. This section describes a couple of those parameters, the fields and format parameters, in more detail.

Fields

Most of the resources that the section "Resource URIs" describes accept a fields parameter that allows the client to specify the fields that the client wants the BMS to include in the response. The following are legal values for the fields parameter: Not all fields are available to all clients because each client subscribes to subset of the fields.

When a field is not available to a client or the BMS finds no data for the field, the document that the BMS returns to the client lacks the field altogether. The BMS doesn't return empty fields.

When a client makes a valid request to the BMS, the BMS returns one of two kinds of responses: a search results page or a details page. The BMS returns a search results page always, unless you request a resource using the resource's BMSID, which is the only time that the BMS can be certain that only one record satisfies the request.

When a client specifies the field "all" among the fields that it wants (or as the only field), the BMS assembles a list of all the fields that the client has access to. When returning a details page, the BMS will include all the fields in that list. However, when returning a search results page, the BMS omits some fields to try to make each record smaller, to constrain the size of the search results page. The server never omits any fields that the client requests explicitly.

The following query, for example, returns a search results page:

http://bms.bowker.com/rest/books/title/pox%20americana?fields=all

You'll notice that the BMS has omitted the annotation field from the search results. If you specify the field explicitly, the BMS will not omit it:

http://bms.bowker.com/rest/books/title/pox%20americana?fields=all,annotation

When a client requests HTML, the BMS returns a label for each field. For example, the label for the editiondesc field is "Edition Description". When a client requests XML, the BMS returns the data for a field within an XML element of the same name as the field that the client requested. For example, the XML element that contains the data for the editiondesc field is the <editiondesc> element.

The following sections describe in detail the data that the BMS returns for each field and how the BMS collects and assembles that data.

abreview

Formats: XML
Field name: Bookseller Publisher Review
Description: This field is like the review field. The data for this field comes from one of the review_rec elements that are associated with our record for the given book. But the review source code has to be "AB" and the reviews are returned in order or review date.

agemin

Formats: XML
Field name: Lower Age Range
Description: The lower age description text for the given record.

agemax

Formats: XML
Field name: Upper Age Range
Description: The upper age description text for the given record.

anannotation

Formats: XML
Field name: Author Notes/Biography
Description: To obtain the data for this field, the BMS first attempts to find an associated contributor record of type "Author". If it fails to find such a record, the BMS attempts to get the data from the first associated annotation record of type "AA".

annotation

Formats: XML, HTML
Field name: Annotation
Description: The BMS collects the data for this field by selecting all the text of the last updated annotation that is associated with our record for the given book and that is not of the type "FC" (First Chapter) does not have an annotation source code of "AVAMG", "AVMID", "GM", "ITA", "SP", "SWE", "UKVID", "SYN", "LBR".

The BMS omits this field from the search results page when the client specifies a field of "all".

audience

Formats: XML, HTML
Field name: Audience
Description: The BMS returns audience information in a field labeled "Audience". The data for the field comes unaltered from the audience_desc field of our record for the given book.

author

Formats: XML, HTML
Field name: Author
Description: The BMS collects the data for this field by assembling a list of the contributors that are associated with our records for the given book, ordering the list according to the contributor sequence number that Bowker assigns, and collapsing the list into a string in which each contributor name is separated from the next by a semicolon and a space: '; '.
The BMS assembles contributor names in regular order (first name, last name) and appends the contributor's role when the contributor is not the author. The contributor's role is enclosed within parenthesis.

avannotation

Formats: XML
Field name: Audio/Video Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code that is "AVAMG" or "AVMID". When possible, the BMS includes track information from the associated TOC record (when that record has a toc_source_code value of "AVAMG" or "AVMID") in the avannotation field.

avprofile

Formats: XML
Field name: Audio/Video Profile
Description: The boc_rec or vid_rec element associated with the given record. These elements provide audio/video profile information.

awards

Formats: XML
Field name: Awards
Description: For each award that is associated with the given record, the BMS returns an award_record element with award name, year, award type description subelements. The award type description subelement indicates how the award relates to the given record.

bestseller

Formats: XML, HTML
Field name: Bestseller
Description: For each best seller record that is associated with the given book record, the BMS returns a description of the best-seller list. The BMS returns a string with semicolon-separated best-seller list descriptions.

bicsubject

Formats: XML
Field name: BIC Subject
Description: The data for this field consists of a string with one or more BIC subjects. Each subject is separated from the next by a semicolon and a space: '; '.

binding

Formats: XML, HTML
Field name: Binding
Description: The data for the field is a string containing the data from the various binding_desc elements in our record for the given book. In the string, the various binding descriptions are separated by a semicolon and a space ('; ').

blreview

Formats: XML
Field name: Book List Review
Description: The BMS obtains the data from this record from the review records that are associated with the given book and that have a review source code of "BL".

cartonquantity

Formats: XML
Field name: Case Pack Quantity
Description: The value from the case_pack_carton_qty field associated with the given record.

chapter1

Formats: XML, HTML
Field name: Chapter 1
Description: The BMS tries first to obtain the data for this field from the chapter record that's associated with the given book. If no chapter such record is found, the BMS obtains the data from the first annotation that is associated with our record for the given book and that has the type "FC".

chreview

Formats: XML
Field name: Choice Review
Description: The BMS retrieves the data for this field from the first review record that is associated with the given book and that has a review source code of "CH".

contrib

Formats: XML, HTML
Field name: Author
Description: The data for this field is similar to the data for the author field. But the name of the contributor in this field appears last-name first.

copyright

Formats: XML, HTML
Field name: Copyright
Description: The data comes from the copyright_date_composite field of our record for the given book. The data consists of a date in the format YYYY-MM-DD.

crreview

Formats: XML
Field name: Criticas Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code of "CR".

currency

Formats: XML, HTML
Field name: Currency
Description: When the client requests HTML, the data comes from the currency_desc, and currency_code elements of our record for the given book. When the client requests XML, the data is assembled from the currency_desc, currency_code, and currency_symbol elements. The currency_desc, currency_code, and currency_symbol elements are contained in a price_rec element, many of which can exist in our record for a given book. To choose the price_rec element from which to extract the data, the BMS creates a list of the price_rec elements in the record that have a price_status_code of "A", orders the list by date in descending order, and then picks the first price_rec element in the list. This basically allows the BMS to return the latest price for the record. When the client requests XML, the BMS assembles the data so that it looks like this: Australian Dollars (AUD, $). And the number in the price field (a separate field described later in this document) contains no currency symbol. When the client requests HTML, however, the data looks like this: US Dollars (USD). And the number in the price field is preceded by a currency symbol. This field will return a currency code for a retail or a net price, whichever is more recent. Please use netcurrency or retailcurrency to retrieve the currency code for the net and retail prices respectively.

currlanguage

Formats: XML
Field name: Current Language
Description: The data for this field consists of a string with one or more languages. Each language is separated from the next by a semicolon and a space: '; '.

deweyedition

Formats: XML
Field name: Dewey Edition number
Description: This number comes from the dewey_edition_num element of our record for the given book.

deweynum

Formats: XML
Field name: Dewey Number
Description: This number comes from the dewey_num element of our record for the given book.

doi

Formats: XML, HTML
Field name: DOI
Description: This number comes from the doi element of our record for the given book.

ebookformat

Formats: XML
Field name: E-book Format
Description: The data for this field consists of a string with one or more e-book formats. Each format is separated from the next by a semicolon and a space: '; '.

editiondesc

Formats: XML, HTML
Field name: Edition Description
Description: The data for the field comes from the edition_desc element of our record for the given book.

editionnum

Formats: XML, HTML
Field name: Edition Number
Description: The data for the field comes from the edition_num element of our record for the given book.

gameprofile

Formats: XML
Field name: Game Profile
Description: This data for this field contains video game profile information from the game_rec element associated with the given record.

gmannotation

Formats: XML
Field name: German Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code that is "GM".

gradelower

Formats: XML
Field name: Lower Grade
Description: The lower grade description for the given record.

gradeupper

Formats: XML
Field name: Upper Grade
Description: The upper grade description for the given record.

hmreview

Formats: XML
Field name: Horn Book Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "HM".

imprint

Formats: XML
Field name: Imprint
Description: The imprint name for the given record.

isbn

Formats: XML, HTML
Field name: ISBN
Description: The ISBN-13 for the given book. To obtain the ISBN-13, the BMS looks in these elements (in order): isbn13_hyphen, isbn13, ean.

isbn10

Formats: XML, HTML
Field name: ISBN-10
Description: The ISBN-10 for the given book. The BMS obtains this data from the isbn element.

itaannotation

Formats: XML
Field name: Italian Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code that is "ITA".

itadvdannotation

Formats: XML
Field name: Italian DVD Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code that is "IEDVD".

kireview

Formats: XML
Field name: Kirkus Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have an review source code value of "KI".

ljreview

Formats: XML
Field name: Library Journal Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have an review source code value of "LJ".

market

Formats: XML, HTML
Field name: Market
Description: The data comes from the market_code element of our record for the given book. The BMS returns a 3-letter code that indicates the market for this particular book.

market_uid

Formats: XML, HTML
Field name: Market UID
Description: The BMS returns a UID that Bowker uses internally to identify the specific market. This field is for internal use only.

mediamention

Formats: XML, HTML
Field name: Media Mentions
Description: The BMS gathers the data for this field from the media_mention_rec element of our record for the given book. The BMS essentially creates a single string with semicolon-separated media mentions. Each media mention includes a description and the date of the mention.

netcurrency

Formats: XML
Field name: Net Currency
Description: The currency code of the most recent net price, the data is assembled from the currency_desc, currency_code, and currency_symbol elements. The currency_desc, currency_code, and currency_symbol elements are contained in a price_rec element, many of which can exist in our record for a given book. To choose the price_rec element from which to extract the data, the BMS creates a list of the price_rec elements in the record that have a price_status_code of "A" and a price_type_code of "N", orders the list by date in descending order, and then picks the first price_rec element in the list. This basically allows the BMS to return the latest net price for the record. The BMS assembles the currency data so that it looks like this: Australian Dollars (AUD, $).

netprice

Formats: XML
Field name: Net Price
Description: The most recent net price. Like the data for the netcurrency field, the data for price comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the netcurrency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A" and a price_type_code of "N", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the price_rec elements in our record for the given book. The BMS returns a price value for this field.

netpricedate

Formats: XML
Field name: Price Date
Description: The most recent net price date. Like the data for the netcurrency field, the data for netpricedate comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the netcurrency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A" and a price_type_code of "N", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the net price_rec elements in our record for the given book.

nyreview

Formats: XML
Field name: New York Times review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "NT".

numvolumes

Formats: XML
Field name: Number of Volumes
Description: The value from the mvs_num_volumes element for the given record.

oclc

Formats: XML, HTML
Field name: OCLC
Description: The data comes from the oclc element of our record for the given book.

onixbinding

Formats: XML
Field name: ONIX Binding
Description: The data for the field is a string containing the data from the onix_product_desc elements in our record for the given book. In the string, the various binding descriptions are separated by a semicolon and a space ('; ').

origlanguage

Formats: XML
Field name: Original Language
Description: The data for this field consists of a string with one or more languages. Each language is separated from the next by a semicolon and a space: '; '.

othereditions

Formats: XML
Field name: Other Editions
Description: The data for this field contains a comma-separated list of ISBNs that are related to the given book by work identifier, also known as other editions of the same work.

pagecount

Formats: XML, HTML
Field name: Page Count
Description: The BMS gathers the data for this field from the num_pages element of our record for the given book.

parentcompany

Formats: XML
Field name: Parent Company
Description: The data for this field contains the parent company name of the publisher for the given book.

price

Formats: XML, HTML
Field name: Price
Description: Like the data for the currency field, the data for price comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the currency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the price_rec elements in our record for the given book. When the client requests XML, the BMS returns a price value for this field. When the client requests HTML, the BMS returns a price value preceded immediately by a currency symbol. The BMS obtains the currency symbol from the currency_symbol element of the price_rec element. This field will return the net or retail price, whichever is more recent. Please use netprice or retailprice to retrieve the net and retail prices respectively.

pricedate

Formats: XML
Field name: Price Date
Description: Like the data for the currency field, the data for pricedate comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the currency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the price_rec elements in our record for the given book. This field will return a pricedate for a retail or a net price, whichever is more recent. Please use netpricedate or retailpricedate to retrieve the pricedate for the net and retail prices respectively.

pub_co_uid

Formats: XML
Field name: Publisher Company UID
Description: The BMS returns a UID that Bowker uses internally to identify the specific publisher. This field is for internal use only.

pubdate

Formats: XML, HTML
Field name: Publication Date
Description: The data comes from the pub_date_composite element of our record for the given book.

publisher

Formats: XML, HTML
Field name: Publisher
Description: The data for this field comes from the publisher_name element of our record for the given book.

pwreview

Formats: XML
Field name: Publishers Weekly Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "PW".

qqreview

Formats: XML
Field name: Quill and Quire Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code of "QQ".

retailcurrency

Formats: XML
Field name: Retail Currency
Description: The currency code of the most recent retail price, the data is assembled from the currency_desc, currency_code, and currency_symbol elements. The currency_desc, currency_code, and currency_symbol elements are contained in a price_rec element, many of which can exist in our record for a given book. To choose the price_rec element from which to extract the data, the BMS creates a list of the price_rec elements in the record that have a price_status_code of "A" and a price_type_code of "R", orders the list by date in descending order, and then picks the first price_rec element in the list. This basically allows the BMS to return the latest retail price for the record. The BMS assembles the currency data so that it looks like this: Australian Dollars (AUD, $).

retailprice

Formats: XML
Field name: Retail Price
Description: The most recent retail price. Like the data for the retailcurrency field, the data for price comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the retailcurrency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A" and a price_type_code of "R", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the price_rec elements in our record for the given book. he BMS returns a price value for this field.

retailpricedate

Formats: XML
Field name: Retail Price Date
Description: The most recent retail price date. Like the data for the retailcurrency field, the data for retailpricedate comes from one of the price_rec elements in our record for the given book. The price_rec element is chosen in the same way that the retailcurrency element is chosen: the BMS assembles a list of the price_rec elements that have a price_status_code of "A" and a price_type_code of "R", sorts the list first by descending order of price_date_composite and second by seq_num, then selects the first price_rec in the list. This has the effect of selecting the latest of the retail price_rec elements in our record for the given book.

review

Formats: XML, HTML
Field name: Review
Description: The data for this field comes from one of the review_rec elements that are associated with our record for the given book. When more than one review record is associated with the book, the BMS chooses the review record with the lowest seq_num value. The data that the BMS displays comes from the review element of the review_rec record that the BMS chooses.

runningtime

Formats: XML
Field name: Running Time
Description: The running time of the audiobook or video. The data for this field comes directly from publishers in a free text string format and excludes meta-data provided by AMG, Midwest and Rovi as that data can only be shown in Syndetics.

seriessubtitle

Formats: XML
Field name: Series Subtitle
Description: The series subtitle for the given record.

seriestitle

Formats: XML
Field name: Series Title
Description: The series title for the given record.

seriesvolnum

Formats: XML
Field name: Series Volume Number
Description: The series volume number for the given record.

similar

Formats: XML
Field name: Similar Items
Description: Returns items that are most similar to the returned matching item. The way this works is the BMS uses an algorithm which finds the most "relevant" terms in specific elements within the matching item and then issues a weighted query to retrieve the 10 most relevant items that contain those terms. To avoid duplicates, items that share the same title-uid will only be returned once. Finally, since an additional search is performed for each item in the result set, this field should only be requested when retrieving a single item's details, and not during a search request that returns multiple items.

size

Formats: XML
Field name: Size
Description: Where available, the BMS returns a size element with length, width, height, and units subelements.

slreview

Formats: XML
Field name: School Library Journal Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "SL".

spannotation

Formats: XML
Field name: Spanish Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code of "SP".

spreview

Formats: XML
Field name: Spanish Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "SP".

status

Formats: XML, HTML
Field name: Status
Description: The data for this field comes from the item_status_desc element of our record for the given book.

subject

Formats: XML, HTML
Field name: Subject
Description: The data for this field consists of a string with one or more subjects (from all the subject_rec types that apply to the given book). Each subject is separated from the next by a semicolon and a space: '; '.
The subject data comes from the subject_rec elements of our record for the given book. The BMS orders the subjects by the value of the seq_num element and obtains the text for the subjects comes from the subject element.

subtitle

Formats: XML, HTML
Field name: Subtitle
Description: The data for the field comes from the sub_title element of our record for the given book.

sweannotation

Formats: XML
Field name: Swedish Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code of "SWE".

swetoc

Formats: XML, HTML
Field name: Swedish Table of Contents
Description: The BMS collects the information for this field from our toc_rec elements for the given book. The toc_rec elements must have a toc_source_code value of "SWE".

swreview

Formats: XML
Field name: Swedish Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code value of "SW".

synanannotation

Formats: XML
Field name: Author Notes/Biography
Description: To obtain the data for this field, the BMS first attempts to find an associated contributor record of type "Author". If it fails to find such a record, the BMS attempts to get the data from the first associated annotation record of type "AA" without a source of "BW".

synannotation

Formats: XML
Field name: Annotation
Description: To assemble the data for this record, the BMS first finds the last-updated associated annotation record with an annot_type_code of "MD" and with an annot_source_code that is not among "AVAMG", "AVAMID", "GM", "ITA", "SP", "SWE", "BW" and "UKVID". It then finds the last-updated associated review record with a review source code value of "RR", "SC" or "UN". Finally, of the resulting annotation and review data, the BMS returns the newest.

synaward

Formats: XML
Field name: Syndetics Award
Description: For this field, the BMS returns data from the associated award_rec documents in our records for the given book. The BMS assembles relevant data from those records into multiple award_record elements each with several subelements: award_uid, award, from_date_year, award_type_desc, award_desc, and url.

synchapter1

Formats: XML
Field name: Chapter 1
Description: If the BMS finds an associated chapter_rec document for the given book, then the BMS uses data from that document to assemble the node for this field. Otherwise, the BMS attempts to obtain the data from the associated annot_rec document of type "FC". What the BMS ends up returning is a chapter element that includes chapter_text, chapter_copyright, and chapter_update_date subelements.

synfiction

Formats: XML
Field name: Fiction Profile
Description: For the given book, the BMS returns the profile_xml node of the associated synd_profile_rec document.

synseries

Formats: XML
Field name: Series Information
Description: For the given book, the BMS returns series_rec elements that it assembles from the associated synd_series_rec documents. The series_rec element can include the following subelements: series_title, series_sub_title, seq_num, series_xml, and update_date.

synserieslite

Formats: XML
Field name: Series Information
Description: For the given book, the BMS returns series_rec elements that contain nothing but the sequence number of the associated synd_series_rec documents.

syntoc

Formats: XML, HTML
Field name: Table of Contents (U.S.)
Description: The BMS collects the information for this field from our toc_rec elements for the given book. The toc_rec elements must not have a toc_source_code value of "SWE", "AVAMG", "AVMID" or "BLW".

title

Formats: XML, HTML
Field name: Title
Description: This is the title of the given book, taken from the title_rec/title element of our record for the book.

title_uid

Formats: XML, HTML
Field name: Title UID
Description: This value is a unique identifier for the title of the book. A given title can have several ISBNs and each ISBN can have several market records. The Title UID value tiles all of the records that relate to a single title.

Formats: XML, HTML
Field name: Table of Contents
Description: The data for this field comes from the toc_rec elements in our record for the given book. The BMS creates a list of the toc_rec elements, orders the list by the value of toc_rec/seq_num, and then extracts data from the toc_rec/toc1 and toc_rec/page_num elements to build each entry in the table of contents.

ukvidannotation

Formats: XML
Field name: UK Video Annotation
Description: The BMS collects the information for this field from the last-updated associated annotation record with an annot_type_code of "MD" and an annot_source_code of "UKVID".

upc

Formats: XML, HTML
Field name: UPC
Description: The data for this field comes from the upc tag of our record for the given book.

videoclip

Formats: XML
Field name: Video Clip
Description: The BMS gets the data for this field from the video records that are associated with the given item and that have a an IVA video ID populated.

volumenum

Formats: XML
Field name: Volume Number
Description: The multi-volume-set volume number for the given record.

voreview

Formats: XML
Field name: VOYA Publisher Review
Description: The BMS gets the data for this field from the review records that are associated with the given book and that have a review source code of "VO".

weight

Formats: XML, HTML
Field name: Weight
Description: The weight of the given book.

xquery

Formats: XML
Field name: XQuery
Description: This field shows the XQuery code that the BMS assembled to search for, obtain, and transform the data for the fields that you requested.

format

The section Resource URIs, which first presents the format parameter, describes the format parameter as accepting the legal values: html_fragment, html_page, xml, and js. You can also use html instead of html_page. In general, the BMS is designed to provide XML data to clients, who then transform the data as necessary for end-user consumption. In some cases, the html formats can be delivered to end users as well. But the js format should never be forwarded to end users; it exists for internal testing purposes only.

When you request HTML from the BMS, the BMS returns HTML that is extensively marked for CSS. Almost every tag contains a class attribute that you can use with CSS to manipulate the look and the location of the data in the tag. The BMS also returns proper labels for each field. For example, when you request the field pubdate, the BMS returns the data together with the corresponding field label "Publication Date". However, the BMS does not return HTML for many of the fields that provide more complex, multi-node, multi-level data structures.

When you request XML, the BMS returns the data itself, without field labels other than the tag names. The tag names correspond exactly to the field names that you specify using the fields parameter. The BMS tries as much as possible to return simple strings for field values. But in many cases those values are fairly complex data structures.

When you request JavaScript (format=js), the BMS returns data formatted for a widget. See the section Widgets for details on BMS widgets and for instructions on when and how to use the format=js parameter.

filterdata

The filter data parameter allows the client to provide a comma-separated list of fields for which the client needs only to know if data exists.

When returning a record, the BMS will--as for any field--hide a filterdata field if the field doesn't contain data. But if the field contains data and is part of the filterdata list, then the BMS will return the string "data-available" rather than the data that it found for the field. This allows clients to conserve bandwidth when they need only know if data exists for the field.

For example, if a client wants to include in an item page a link that takes the end user to book reviews, the client doesn't actually need the review data. Knowing that review data is sufficient. In such a case, the client can call the BMS with filterdata=review. If the BMS returns the field, the client knows that it can put a reviews link in the item page. Otherwise, if the field is not in the BMS's response, the client can avoid including the link.

The BMS returns the string "data available" for any field that is listed in the filterdata parameter and for which the BMS found data. That string is longer than the actual value that several fields might return.

Furthermore, because of how the data for some of the fields is assembled, the filterdata parameter is innefectual in some cases.

For these reasons, when providing a list of fields with the filterdata parameter, clients should follow the general rule of listing fields that meet the following conditions:

normally return a lot of data
are listed in the [[#Fields][Fields] section
are not the coverimage field

Excellent candidates for the filterdata parameter are:

annotation
author
chapter1
review
subject
subtitle
title
toc

qtext

The qtext parameter allows the client to issue text based searches composed of terms, phrases, and operators that can easily be composed by end users typing into an application search box. For example, "cat AND dog" is a string query for finding books that contain both the keyword "cat" and the keyword "dog".

The syntax of the qtext string query is determined by a grammar that is similar to those exposed by google and other search applications. This grammar enables clients to execute complex queries against the BMS database based on simple strings. A complete description of the grammar including query components and operators is described in the following table:

Query	Example	Description
any keywords	dog cat	Match one or more keywords. Adjacent terms and phrases are implicitly joined with AND. For example, dog cat is the same as dog AND cat.
" "	"dog tail" "dog tail" "cat whisker" dog "cat whisker"	Terms in double quotes are treated as a phrase. Adjacent terms and phrases are implicitly joined with AND. For example, dog "cat whisker" matches books containing both the term dog and the phrase cat whisker.
( )	(cat OR dog) zebra	Parenthesis indicate grouping. The example matches books containing at least one of the terms cat or dog, and also contain the term zebra.
-query	-dog -(dog OR cat) cat -dog	A NOT operation, for example cat -dog matches books that contain the term cat but that do not contain the term dog.
query1 AND query2	dog AND cat (cat OR dog) AND zebra	Matches two query expressions. For example, dog AND cat matches books containing both the term dog and the term cat. AND is the default way to combine terms and phrases, so the previous example is equivalent to dog cat.
query1 OR query2	dog OR cat	Match either of two queries. The examples matches books containing at least one of either of the terms cat or dog.
constraint:value	author:shakespeare publisher:hachette title:"Wuthering Heights"	Find books that match the named constraint with the given value. Please consult the full list of all available constraints below.
query1 BOOST query2	george BOOST washington	Find books that match query1. Boost the relevance score of books that also match query2. The example returns all matches for the term george, with matches in books that also contain washington having a higher relevance score.

The following lists all available qtext search constraints:

author: Find books whose author name matches the provided value.
binding: Find books whose binding description matches the provided value.
doi: Find books whose DOI matches the provided value.
isbn: Find books whose ISBN matches the provided value.
oclc: Find books whose OCLC number matches the provided value.
publisher: Find books whose publisher name matches the provided value
status: Find books whose publication status matches the provided value.
subject: Find books whose subject matches the provided value.
title: Find books whose title matches the provided value.
upc: Find books whose UPC number matches the provided value.

Reference Clients

The reference client implementations in this section, a Perl client, an HTML form client, and an HTML widget, demonstrate how to access a resource on the BMS. They illustrate how to request data for one or more books.

HTML Client

The following HTML code produces a Web page with a form that allows you to request information about a specific book or to search for a book by subject, title, author, or ISBN. The form also lets you specify if you want the information in HTML format or in XML format.

<html><head>
<link rel="stylesheet" href="%PUBURL%/%TWIKIWEB%/HeadlinesPlugin/style.css" type="text/css" media="all" />
  <title>Book Meta Data Service Search Form</title>
  <link rel="stylesheet" type="text/css" href="/css/bookforms.css"/>
</head><body>

<h1>Book Meta Data Service Search Form</h1>

<p>This form allows you to search for a book on a variety of fields or to
retrieve details about specific book if you have the book's BMSID.</p>

<form method="GET" action="http://bms.bowker.com/rest/books/search">
<input type="hidden" name="fields" value="all"/>
<table>
<!-- id --><tr>
  <td class="label">BMSID</td>
  <td class="input"><input type="text" name="id"/></td>
</tr>

<!-- isbn --><tr>
  <td class="label">ISBN</td>
  <td class="input"><input type="text" name="isbn"/></td>
</tr>

<!-- title --><tr>
  <td class="label">Title</td>
  <td class="input"><input type="text" name="title"/></td>
</tr>

<!-- author --><tr>
  <td class="label">Author or Contributor</td>
  <td class="input"><input type="text" name="author"/></td>
</tr>

<!-- subject --><tr>
  <td class="label">Subject</td>
  <td class="input"><input type="text" name="subject"/></td>
</tr>

<!-- format --><tr>
  <td class="label">Data Format</td>
  <td class="input"><select name="format">
    <option value="xml" selected>XML</option>
    <option value="html">HTML</option>
  </select></td>
</tr>

<tr><td class="spacer_row" colspan="2">&nbsp;</td></tr>

<!-- submit --><tr>
  <td class="submit" colspan="2"><input type="submit" value="Search"/></td>
</tr>
</table>
</form>

</body>
</html>

Perl Client

The following Perl code fetches XML with a specific book's title and prints the XML to the screen.

#!/usr/bin/perl

use LWP::UserAgent;
use HTTP::Headers;

$username= 'john';
$password= 'hellokitty';
$uri= 'http://bms.bowker.com/rest/books/id/12n4ei0z2xghy4?fields=title';

$headers= HTTP::Headers->new;
$headers->authorization_basic($username, $password);
$ua= LWP::UserAgent->new;
$r= $ua->get($uri, Authorization => $headers->authorization);
print $r->is_success ? $r->content : $r->status_line;

C# Client

The following C# code fetches XML with a specific book's title and prints the XML to the screen.

using System;  
using System.IO;  
using System.Net;  
using System.Text;  

// Create the web request  
HttpWebRequest request   
  = WebRequest.Create("http://bms.bowker.com/rest/books/id/12n4ei0z2xghy4?fields=title") as HttpWebRequest;  

// Add authentication to request  
request.Credentials = new NetworkCredential("username", "password");  

// Get response  
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)  
{  
  // Get the response stream  
  StreamReader reader = new StreamReader(response.GetResponseStream());  

  // Console application output  
  Console.WriteLine(reader.ReadToEnd());  
}

Widgets

A widget is a chunk of code from a Web service or Web site that can be easily embedded in the HTML of any Web page. These embeddable chunks of code typically consist of a couple of lines of HTML that when inserted into the content of a Web page, provide useful dynamic content that is powered by a separate Web site.

BMS Widgets

The BMS supports Widgets via its format parameter. But this support is available for internal applications only, applications that Bowker or its partners develop for convenience or for testing. Furthermore, the BMS provides this support exclusively for fields for which the BMS can display HTML. (See the #Fields section to determine if the BMS supports HTML for a particular field.)

If you request data with the parameter format=js, the BMS returns exactly the same information as if you had specified format=html_fragment, but the information is wrapped in a small JavaScript program that auto-loads and executes when a JavaScript-capable browser displays it in a certain way. Though you can issue a format=js request by typing the URI in a browser's address bar, the need for this parameter becomes clear when you have to insert a widget in an existing Web page.

The widget, in this case, consists of one line of HTML code (a <script> tag) that causes the browser to fetch the JavaScript code from the server and to run that code. The browser ends up displaying content in place of the script tag.

Widgets have been around for a long time and are in widespread use today in the World Wide Web. A multitude of web sites such as Google AdSense, Flickr, Bubble Share, Delicious, Last FM, and YouTube use widgets. Widgets are a powerful content distribution mechanism.

Widget Deployment Demonstration

The following sections describe how to insert a BMS Widget into an HTML page.

No Widget

Here's the source code for a very simple HTML page:

<html>
  <head>
    <title>BMS Widget Test</title>
  </head>
  <body>
    <h2>BMS Widget Test</h2>
  </body>
</html>

A browser displays that page as follows:

Widget

To insert content from the Book Meta Data Service into this Web page is easy. Just add one line of HTML code anywhere within the body of the Web page, like this:

<html>
  <head>
    <title>BMS Widget Test</title>
  </head>
  <body>
    <h2>BMS Widget Test</h2>

      <script id="bmsw_sr" type="text/javascript"
             src="http://bms.bowker.com/rest/books/subject/neural%20networks?fields=all&pagesize=7&page=10&format=js"></script>

  </body>
</html>

The line we added is in blue and appears as two lines here for convenience. When the browser sees the new line (when you display the Web page), the browser fetches Javascript code from the BMS and runs it, replacing the script tag with the requested content. The <script> tag causes the browser to render the page as follows:

The difference between the HTML for the first page and the HTML for the second page amounts to 1 line of HTML code (a <script> tag).

Widget with Formatting

For formatting flexibility, the HTML that the widget generates is extensively marked for CSS. Every tag contains a class attribute that you can reference from CSS to format the results. This means that the widget can easily be made to look like it was designed for your Web page.

To format the widget in the Web page, you can add the following line of HTML code to the head of the Web page:

<html>
  <head>
    <title>BMS Widget Test</title>

    <link rel="stylesheet" type="text/css" href="sr_help.css"/>

  </head>
  <body>
    <h2>BMS Widget Test</h2>
      <script id="bmsw_sr" type="text/javascript"
              src="http://bms.bowker.com/rest/books/subject/neural%20networks?fields=all&pagesize=7&page=10&format=js">&lt;/script></font>
  </body>
</html>

The new link tag references the file sr_help.css, which is a style sheet that dictates how the data in the widget will be formatted. The browser now displays the page as follows:

The sr_help.css file contains the following CSS code:

span.search_results_summary { visibility: hidden; }

/*
   BEGIN Search Results
*/

/* attributes for search-results table */
table.search_results { border-collapse: collapse; width: 100%; }

/* even search-result rows */
tr.item_odd {background-color: #f0f0ff}
tr.item_sep_odd {background-color: #f0f0ff}

/* odd search-result rows */
tr.item_even {background-color: white}
tr.item_sep_even {background-color: white}

.srs_name { font-weight: bold; }

.item_field_name { font-weight: bold; }

.item_title { font-size:110%; font-style: oblique; }

/*
  END Search Results
*/


/* 
   BEGIN Details
*/

img.d_item_coverimage {float: right; }
table.d_item { border-collapse: collapse; width: 80%; }
tr.d_field_odd { background-color: #f0f0ff; }
tr.d_field_even { background-color: white; }
td.d_field_name { width: 175px; font-weight: bold; vertical-align: top; }

/*
  END Details
*/

Field Groups

Basic

The following fields are associated with the 'basic' role.

field
author
audience
all
bestseller
bicsubject
binding
contrib
copyright
currency
currlanguage
doi
editiondesc
editionnum
isbn
isbn10
market
market_uid
mediamention
pagecount
oclc
origlanguage
price
pricedate
pubdate
pub_co_uid
publisher
size
status
subject
subtitle
title
title_uid
upc
weight

Value-Added

The following fields are associated with the 'value_added' role.

anannotation
avannotation
awards
bestseller
blreview
chreview
contrib
crreview
gmannotation
hmreview
itaannotation
kireview
ljreview
market_uid
mediamention
oclc
pagecount
pwreview
size
slreview
spannotation
spreview
sweannotation
swetoc
swreview
synanannotation
synannotation
synaward
synfiction
synseries
synserieslite
syntoc
title_uid
weight

Revision: r1.5 - 28 Feb 2022 - 15:12:36