Book Meta Data Service Documentation

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/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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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.

coverimage
  • Formats:: XML, HTML
  • Field name: Cover Image
  • Description: The BMS returns a URI for an image that the Bowker Image BMS can serve. The URI causes the Bowker Image BMS to displaying a blank image when an image is not available for the book. The size and type of the image are not specified in the URI so they fall back to image service defaults. This field is deprecated and will not be supported in the future.

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".

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.

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: '; '.

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.

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.

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.

toc
  • 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

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.4 - 29 Aug 2007 - 09:15:40