XML Product Feed Specification

This document describes the structure of the XML file required for product cataloging in our service. We accept a variety of XML formats as long as the required product attributes are included. The system can parse product data enclosed in <product> tag.

Requirements

The XML file must meet the following requirements:

• Includes document's creation date
• XML validates according to standard XML rules
• Doesn't repeat the same products more than once (see Unique ID)
• Product images must be accessible via standard HTTP/HTTPS protocols

Technical Specifications

Our service uses a crawler to download XML feeds. It is identified with the HTTP header "User-Agent: InstaFindAgent/1.0". The crawler will:

• Download the feed URL
• Download the feed file images URLs

The crawler accepts https links with valid certificates. Self-signed certificates are not supported.

To ensure our crawler can access your feed, please configure your server to allow requests from the User-Agent "InstaFindAgent/1.0".

Our crawler handles gzip and zip compression if your server sends the appropriate Content-Encoding headers.

Product Feed

XML Declaration

The XML declaration head must include the encoding of the file as well as the date it was created:

<?xml version="1.0" encoding="UTF-8"?>
<products>
   <created_at>2023-05-21 12:32</created_at>
   ...
</products>

The encoding declared must match the actual encoding of the file. We recommend using UTF-8 encoding for all feeds.

If your feed is cached, please ensure it is regenerated at least once daily.

Attributes

The table below summarizes the product attributes recognized by our service:

In addition to the attributes listed in the table above, clients have the option to include their own custom fields in the XML product feed. These custom fields will also be processed and can be mapped within the system as needed.

Unique ID (unique_id)

This attribute represents the unique identifier of a product in your database. The value of this field must remain the same through a product's lifecycle and cannot be reused.

Example:

<unique_id>322</unique_id>

Name (name)

The title of the product. It should include all necessary attributes even if those attributes are included in other parts of the XML.

Example:

<name>Samsung Galaxy S22 Ultra 256GB Phantom Black</name>

Product URL (product_url)

The URL that links to your shop's page for the specified product. It must be a valid URL starting with http or https.

Example:

<product_url>https://www.example.com/products/samsung-galaxy-s22-ultra</product_url>

Image URL (image_url)

The product's image location. It must be a valid URL starting with http or https.

Example:

<image_url>https://www.example.com/images/samsung-galaxy-s22-ultra.jpg</image_url>

Category Path (category_path)

The product's category path. Include the full path of the product's category, with categories separated by " > ".

Example:

<category_path>Electronics > Smartphones > Android Phones</category_path>

Main Category (main_category)

The name of the main, top-level category for the product. This is often the first part of the category_path.

Example:

<main_category>Smartphones</main_category>

Main Category URL (main_category_url)

The URL that links to the main, top-level category page on your shop.

Example:

<main_category_url>https://www.example.com/categories/smartphones</main_category_url>

Price (price)

The product's retail price. Ensure all taxes are included if applicable.

Example:

<price>899.99</price>

Brand (brand)

The manufacturer or brand of the product.

Example:

<brand>Samsung</brand>

SKU / MPN (sku or mpn)

The unique manufacturer or shop identifier of the product.

Example:

<sku>SM-S908B</sku>

Barcode / UPC / EAN (barcode, upc, or ean)

The international article number (EAN/UPC) used for the identification of retail products.

Example:

<barcode>8806092879089</barcode>

Size (size)

The product's size. If the product is available in multiple sizes that are not treated as separate product entries, you can list them separated by commas.

Example:

<size>S,M,L,XL</size>

<size>6.8 inch</size>

Color (color)

The color of the product.

Example:

<color>Phantom Black</color>

Description (description)

The product description explaining what a product is and its features.

Example:

<description>
  The Samsung Galaxy S22 Ultra features a 6.8-inch Dynamic AMOLED display with 120Hz refresh rate, 
  Snapdragon 8 Gen 1 processor, 12GB RAM, 256GB storage, 108MP main camera, and 5000mAh battery with fast charging.
</description>

XML Examples

Simple XML

The XML excerpt below is an example of a compatible XML product feed:

<?xml version="1.0" encoding="UTF-8"?>
<products>
   <created_at>2023-05-21 12:32</created_at>
   <product>
      <unique_id>1001</unique_id>
      <name>Samsung Galaxy S22 Ultra 256GB Phantom Black</name>
      <product_url>https://www.example.com/products/samsung-galaxy-s22-ultra</product_url>
      <image_url>https://www.example.com/images/samsung-galaxy-s22-ultra.jpg</image_url>
      <category_path>Electronics > Smartphones > Android Phones</category_path>
      <main_category>Electronics</main_category>
      <main_category_url>https://www.example.com/categories/electronics</main_category_url>
      <price>899.99</price>
      <brand>Samsung</brand>
      <sku>SM-S908B</sku> <!-- Main product SKU -->
      <barcode>8806092879089</barcode>
      <size>6.8 inch</size>
      <color>Phantom Black</color>
      <description>
         The Samsung Galaxy S22 Ultra features a 6.8-inch Dynamic AMOLED display with 120Hz refresh rate, 
         Snapdragon 8 Gen 1 processor, 12GB RAM, 256GB storage, 108MP main camera, and 5000mAh battery with fast charging.
      </description>
   </product>
</products>