GetCategories

The GetCategories-request resemble the GetProducts-request very much. In fact, most of the parameters are shared between the two.

GetCategories
Parameters	Name	Mandatory	Description
	Channel	Yes	The channel you want categories from must be supplied.
	Keys	No	The list of KeyField values for the categories you want fetched. If no Keys supplied, all categories will be fetched.
	SiteKey	No	Only fetch categories for some site denoted by is KeyField.
	IncludeMappings	No	Specifies which mappings should be included for the fetched categories. If nothing is specified here all mappings are included.
	ExcludeMappings	No	Specifies which mappings should be excluded. If nothing is specified here, it is assumed that no mappings are excluded.
	ForceBinaryOutputKind	No	How binaries are output is controlled on the mapping. This parameter overrides that setting on the mapping and forces binaries to be output as specified. Possible values are None, Url, File and Embedded.
	IncludeModificationDates	No	When set to true, modification dates will be output on all elements in result.
	IncludePerfionNamesOnFields	No	When set to true, the name of the feature from which a field comes from is added to output.
	IncludePerfionItemIdsOnSelectables	No	When set to true, the id of a selectable feature output to a Field will be added to the output.
	RemoveUnwantedFeaturesByConfiguration	No	When set to true, a wild-card mapping will only return Features/Fields which are configured for each individual item.
	FlattenHierarchy	No	When set to true, sub categories will no longer be output as child elements of their parents but all in one big list. Parenthood can still be determined by looking at the output parented-attribute.
	TimeZone	No	Available from Perfion 4.7 this parameter allows you to control in which time zone that is used to output modification dates when IncludeModificationDates is enabled. If this parameter is not supplied, the time zone supplied in Settings will be used (See section Timezone). If no time zone is supplied here either, the time zone of the Perfion Database will be used. This was also the time zone used by the EC API in earlier versions of Perfion.
Sample Mapping
Sample Data
Sample Request	<Execute method="GetCategories" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="IncludeMappings"> <Value>CatId</Value> <Value>Name</Value> </Parameter> <Parameter id="SiteKey" value="Site A" /> </Execute>
Sample result	<Response> <Result> <Channel name="My Channel"> <Categories> <Category id="1084" parentid="0"> <Fields> <Field name="CatId">1084</Field> <Field name="Name" culture="en-US">My Site</Field> </Fields> <Categories> <Category id="1080" parentid="1084"> <Fields> <Field name="CatId">1080</Field> <Field name="Name" culture="en-US">Coffee</Field> </Fields> <Categories> <Category id="1081" parentid="1080"> <Fields> <Field name="CatId">1081</Field> <Field name="Name" culture="en-US">Brewing</Field> </Fields> <Categories /> </Category> <Category id="1082" parentid="1080"> <Fields> <Field name="CatId">1082</Field> <Field name="Name" culture="en-US">Keeping warm</Field> </Fields> <Categories /> </Category> <Category id="1083" parentid="1080"> <Fields> <Field name="CatId">1083</Field> <Field name="Name" culture="en-US">Accessories</Field> </Fields> <Categories /> </Category> </Categories> </Category> </Categories> </Category> </Categories> </Channel> </Result> </Response>

Table 1: GetCategories-method.

Note in Table 1 that only CatId and Name is output. Note further that hierarchy is built into the result in two ways:

Structural, i.e. a category has in a Categories-element its subcategories. This can be omitted by using the FlattenHierarchy-parameter as described in Section GetCategories.
By id and parentid. A category will as parentid point to its parent-category except when it has no in which parentid would be 0.

The following parameters are shared with GetProducts meaning that Channel, IncludeMappings, ExcludeMappings ForceBinaryOutputKind, IncludeModificationDates, IncludePerfionNamesOnFields and RemoveUnwantedFeaturesByConfiguration work for categories exactly as they do for products. If you need info on any of these please go to appropriate sub-section of section GetProducts.

The remaining Parameters supported will be described in sections below.

GetCategories: Keys-Parameter

The Keys-parameter works for categories as they do for Products. There is a small pitfall using it on categories, though, since it will only fetch a single category when used on a KeyField (assuming this holds a unique value). This means that you will not get any sub-categories for this single category (unless they share the same Key).

In most cases, however, you would just want to retrieve all categories.

GetCategories: SiteKey-Parameter

In case you have more sites in your category structure, as seen on below, you can ask for only categories from a particular site.

Example: The following request fetches only categories for site with a key value of “Site B”:

<Execute method="GetCategories" refreshconfiguration="true">
  <Parameter id="Channel" value="My Channel" />
  <Parameter id="SiteKey" value="Site B" />
</Execute>

NOTE: This requires you to have a KeyField-mapping on Site-entity.

GetCategories: FlattenHierarchy-Parameter

As can be seen in Table 1 the ECommerce API outputs categories hierarchically. In case you want to have categories in a flat element-list instead (using id/parentid-relationship to determine hierarchy) you can use the FlattenHierarchy-parameter:

Sample Data

Sample Request

<Execute method="GetCategories" refreshconfiguration="true">
  <Parameter id="Channel" value="My Channel" />
  <Parameter id="SiteKey" value="Site B" />
  <Parameter id="IncludeMappings">
    <Value>CatId</Value>
    <Value>Name</Value>
  </Parameter>
  <Parameter id="FlattenHierarchy" value="true" />
</Execute>

Sample result

<Response>
  <Result>
    <Channel name="My Channel">
      <Categories>
        <Category id="1172" parentid="0">
          <Fields>
            <Field name="CatId">1172</Field>
            <Field name="Name" culture="en-US">My US Site</Field>
          </Fields>
        </Category>
        <Category id="1174" parentid="1172">
          <Fields>
            <Field name="CatId">1174</Field>
            <Field name="Name" culture="en-US">Cars</Field>
</Fields>
        </Category>
        <Category id="1175" parentid="1174">
          <Fields>
            <Field name="CatId">1175</Field>
            <Field name="Name" culture="en-US">Audi</Field>
          </Fields>
        </Category>
        <Category id="1176" parentid="1174">
          <Fields>
            <Field name="CatId">1176</Field>
            <Field name="Name" culture="en-US">BMW</Field>
          </Fields>
        </Category>
        <Category id="1177" parentid="1174">
          <Fields>
            <Field name="CatId">1177</Field>
            <Field name="Name" culture="en-US">Peugeot</Field>
          </Fields>
        </Category>
      </Categories>
    </Channel>
  </Result>
</Response>

Table 2: GetCategories-output is flattened using the FlattenHierarchy-parameter