|
API Description: Categories Collection Specifics
The 'categories' collection provides information about the category
structure used by ISBNdb.com. Categories form a hierarchical structure
by referring to their parents -- see 'parent_id' attribute below.
Most categories list subjects, some list authors and publishers
(alphabetical categories currently), some list books (book shelves
categories that organize books by DDC or LCC numbers).
Categories do not list items contained in them -- instead, items
(subjects, authors, publishers) list categories they belong to.
The base URL for the categories collection access is:
http://isbndb.com/api/categories.xml
Arguments
Categories collection supports the following indexes:
- name
- Performs a search on the category name. For example:
/api/categories.xml?access_key=Z&index1=name&value1=mathematics
The search is performed on the category full path -- names of all its
parent categories combined with the name of the final category.
The search follows the same rules and syntax as the
search on the website itself -- you can group words together using
double quotes, all non-ignored words must be present in the results.
- category_id
- Retrieving category data by ISBNdb.com's category ID. Returns at most
one match. Example:
/api/categories.xml?access_key=Z&index1=category_id&value1=science.mathematics.geometry
- parent_id
- Retrieving the list of categories that are contained inside the
given category. By specifying an empty parent category ID you can get a
list of top-level categories. Example:
/api/categories.xml?access_key=Z&index1=parent_id&value1=science
Results
By default, if no additional 'results' values specified, the
categories collection returns only a set of CategoryData/Name tag
pairs. For example:
/api/categories.xml?access_key=Z&index1=category_id&value1=science.mathematics
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2006-01-23T01:15:04">
<CategoryList total_results="1" page_size="10" page_number="1" shown_results="1">
<CategoryData category_id="science.mathematics" parent_id="science">
<Name>Mathematics</Name>
</CategoryData>
</CategoryList>
</ISBNdb>
In addition to common 'results' blocks the
categories collection adds some that are categories specific. The
syntax remains the same -- comma separated values in the 'results'
argument.
- details
- Shows more details about category. For example:
/api/categories.xml?access_key=Z&results=details&index1=category_id&value1=alphabetically.authors.b.l
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2006-01-23T01:16:28">
<CategoryList total_results="1" page_size="10" page_number="1" shown_results="1">
<CategoryData category_id="alphabetically.authors.b.l" parent_id="alphabetically.authors.b">
<Name>L</Name>
<Details summary="Authors, 'BL'" depth="3" element_count="0"/>
</CategoryData>
</CategoryList>
</ISBNdb>
- subcategories
- Shows subcategories for each category found. For example:
/api/categories.xml?access_key=Z&results=subcategories&index1=category_id&value1=alphabetically
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2006-01-23T01:16:28">
<CategoryList total_results="1" page_size="10" page_number="1" shown_results="1">
<CategoryData category_id="alphabetically" parent_id="">
<Name>Alphabetically</Name>
<SubCategories>
<SubCategory id="alphabetically.publishers"/>
<SubCategory id="alphabetically.authors"/>
</SubCategories>
</CategoryData>
</CategoryList>
</ISBNdb>
|
