Skip to content

xml-feed-format.md

Latest commit

 

History

History
115 lines (89 loc) · 3.88 KB

xml-feed-format.md

File metadata and controls

115 lines (89 loc) · 3.88 KB
Raw

XML feed format

A Find-iQ XML feed describes the whole catalogue as a single file: categories on top, products (offers) below. See examples/findiq_price_example.xml for a complete reference.

Document shape

<?xml version="1.0" encoding="UTF-8"?>
<findiq_catalog date="YYYY-MM-DD HH:MM">
<shop>
    <name>...</name>
    <url>...</url>

    <currencies>
        <currency id="UAH" rate="1"/>
    </currencies>

    <categories>
        <category id="10">Electronics</category>
        <category id="42" parentId="10">Smartphones</category>
        ...
    </categories>

    <offers>
        <offer id="12345" available="true">
            ...
        </offer>
        ...
    </offers>
</shop>
</findiq_catalog>

Category fields

Field Required Description
id yes Unique category identifier
parentId optional Parent id; 0 or absent = root category
tag text yes Category name
url recommended Link to the category page (for facets / redirects)

Offer (product) fields

Field Required Description
id yes External product identifier (stable across updates)
name yes Product name
description yes Full description — indexed for search
url yes Product page URL
categoryId yes Category id; must match one in <categories>
price yes Main retail price
quantity yes Stock quantity (integer)
picture yes Product image URL (one per product)
sale_price optional Promotional / discounted price
specialprice optional Special price for second tier (wholesale, registered users)
currencyId optional Currency code (UAH, USD, EUR, ...)
available optional true / false
vendor optional Manufacturer / brand name
vendorCode optional Manufacturer SKU
model optional Model name
sku optional Shop SKU
ean optional European barcode
upc optional American barcode
jan optional Japanese barcode
isbn optional Book ISBN
stock_status_id optional Stock status id (internal shop value)
status optional 1 = active, 0 = disabled (hidden)
rating optional Average rating 0-5
param optional Attribute — name and group as XML attributes, value as tag text

Attributes (param)

<param name="Colour" group="General">Titanium Black</param>
<param name="Width" group="Dimensions">61 cm</param>
  • name — attribute label (e.g. "Screen size")
  • group — parent group for UI grouping (e.g. "Display")
  • tag text — value

Multilingual shops

Supply one XML per language and register each file separately in the Find-iQ admin. The admin panel lets you attach multiple feeds to the same site.

Encoding

  • Use UTF-8 (<?xml version="1.0" encoding="UTF-8"?>)
  • Special characters in names / descriptions must be escaped (&amp;, &lt;, &gt;, &quot;)
  • Wrap long content in <![CDATA[...]]> if it contains HTML

Size and performance

  • Keep a single feed under ~200 MB when possible
  • Serve with gzip content encoding if the web server supports it
  • Update the feed on a regular cadence (hourly for prices, daily for full data is typical)

Validation

The example file uses a DOCTYPE declaration (<!DOCTYPE findiq_catalog SYSTEM "findiq.dtd">). A DTD is not required at fetch time — the parser ignores the system identifier — but leaving it in makes the format self-documenting.

You can test your feed before publishing:

xmllint --noout your-feed.xml

If xmllint reports no errors the feed is well-formed.

See also