CategoryList - browsing a list of categories

This is a read-only resource that allows you to retrieve category data about a list of categories under a given parent. It is the sort of data that you would use to render a list of categories (perhaps as cards), a single-level category menu, or category filters.

Data contained includes all of the standard category data - e.g. code, name, description, slug, image etc.

Overview

Supported HTTP "verbs"

VERB	HTTP Method	Description
fetch (default cart)	GET /api/v3/CategoryList/$category_code	Fetch the categories below the specifed level
fetch	GET /api/v3/CategoryList	Get the top-level category list
list	NOT SUPPORTED
create/update	NOT SUPPORTED
update	NOT SUPPORTED

Supported parameters

Parameter	Values	Description
_fallback_images	0 (default) or 1	Attempt to find a fallback image if none specified
_with_ancestors	0 (default) or 1	Attempt to retrieve category ancestors
_with_fields	Colon seperated list of category fields	Category fields to include
_all	0 (default) or 1	Attempt to retrieve all categories

Note there is no pagination support

Retrieving a category list

To pull data from this resource submit a GET request to /API/V3/CategoryList/$code where $code is the parent category code you wish to retrieve under.

To retrieve top level categories, simply omit the code, calling: /API/V3/CategoryList.

Fallback Images

A lot of website administrators don't upload category images for their categories. If your design / layout ideally needs images to represent the category, you can optionally pass the ?_fallback_images=1 querystring parameter. This will perform an additional lookup for any categories that do not have images & attempt to find a useful image for that category by searching for: - any subcategories beneath a given category on the category tree that have images - any products in any of those categories that have an image

Example response

The following response is an example response from a website selling linen products using a fake url:

https://www.mysite.net/API/V3/CategoryList?_fallback_images=1

<?xml version="1.0" encoding="utf-8" ?>
<ResultSet totalResults="2" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://www.mysite.net/API/V3/CategoryList.xsd">
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00367" id="Ecommerce::Category::00367">
        <code>00367</code>
        <description>&lt;p&gt;This is the product description&lt;/p&gt;</description>
        <header_image>https://images.zeald.com/site/mysite/images/originals/dcd9-4354-823e-7ba16cf5463e.jpg</header_image>
        <hide>0</hide>
        <image>https://images.zeald.com/site/mysite/images/items/some-product-image.jpg</image>
        <last_modified>2018-11-26 16:21:34</last_modified>
        <meta_desc>Looking for the best comforters in NZ? Buy comforter sets online. Top brands including Robusta and Super Linen. Delivery worldwide from NZ.</meta_desc>
        <meta_key_words></meta_key_words>
        <meta_page_title>Comforters NZ</meta_page_title>
        <name>Comforters</name>
        <slug></slug>
        <url_override></url_override>
    </Category>
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00291" id="Ecommerce::Category::00291">
        <code>00291</code>
        <description>&lt;p&gt;This is the product description&lt;/p&gt;</description>
        <header_image>https://images.zeald.com/site/mysite/images/originals/Bed_Linen.jpg</header_image>
        <hide>0</hide>
        <image>https://images.zeald.com/site/mysite/images/items/some-category-image.jpg</image>
        <last_modified>2018-12-02 15:01:55</last_modified>
        <meta_desc>Buy luxury bed linen online. Huge range of bedspreads, pillow cases, doonas and duvets available.</meta_desc>
        <meta_key_words></meta_key_words>
        <meta_page_title>Luxury Bed Linen NZ</meta_page_title>
        <name>Bedlinen</name>
        <slug></slug>
        <url_override></url_override>
    </Category>
</ResultSet>

Ancestors

You can retrieve category ancestors by optionally pass the ?_with_ancestors=1 querystring parameter.

Example response

The following response is an example response from a website selling linen products using a fake url:

https://www.mysite.net/API/V3/CategoryList?_fallback_images=1&_with_ancestors=1

<?xml version="1.0" encoding="utf-8" ?>
<ResultSet totalResults="2" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://www.mysite.net/API/V3/CategoryList.xsd">
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00411" id="Ecommerce::Category::00411">
        <ancestors>
            <Category href="http://localhost:8097/gem-fashion-dev/API/V3/BrowseCategory/00367" id="Ecommerce::Category::00367">
                <code>00367</code>
                <name>Comforter</name>
            </Category>
        </ancestors>
        <code>00411</code>
        <description>&lt;p&gt;This is the product description&lt;/p&gt;</description>
        <header_image>https://images.zeald.com/site/mysite/images/originals/dcd9-4354-823e-7ba16cf5463e.jpg</header_image>
        <hide>0</hide>
        <image>https://images.zeald.com/site/mysite/images/items/some-product-image.jpg</image>
        <last_modified>2018-11-26 16:21:34</last_modified>
        <meta_desc>Looking for the best Bianca Lorenne in NZ? Buy comforter sets online. Top brands including Robusta and Super Linen. Delivery worldwide from NZ.</meta_desc>
        <meta_key_words></meta_key_words>
        <meta_page_title>Bianca Lorenne NZ</meta_page_title>
        <name>Bianca Lorenne</name>
        <slug></slug>
        <url_override></url_override>
    </Category>
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00291" id="Ecommerce::Category::00291">
        <code>00291</code>
        <description>&lt;p&gt;This is the product description&lt;/p&gt;</description>
        <header_image>https://images.zeald.com/site/mysite/images/originals/Bed_Linen.jpg</header_image>
        <hide>0</hide>
        <image>https://images.zeald.com/site/mysite/images/items/some-category-image.jpg</image>
        <last_modified>2018-12-02 15:01:55</last_modified>
        <meta_desc>Buy luxury bed linen online. Huge range of bedspreads, pillow cases, doonas and duvets available.</meta_desc>
        <meta_key_words></meta_key_words>
        <meta_page_title>Luxury Bed Linen NZ</meta_page_title>
        <name>Bedlinen</name>
        <slug></slug>
        <url_override></url_override>
    </Category>
</ResultSet>