Result format

The request returns a ResultList containing Products in JSON or LD-JSON format. The tables below describe the RDF schema of the resulting data. The schema is based on https://schema.org, denoted as schema:Class, and custom classes are denoted theca:Class.

Images

All images are served from our CDN in a standardized size. Images are resized, but they keep the original aspect ratio. For example, a product image of size 400x200px width and height will be resized to size 512x256px (keeping the aspect ratio 2:1). They are in a JPEG, PNG, or WebP format depending on your configuration.

Types

The objects returned in the search result are all of a specified type as described below. The primitive type literals include Integer, Float, and Text. Other types include: Enum is a string from a pre-defined set of values and List is a JSON array literal with a specified type.

note

Prices are always given in Text to preserve currency specific number of decimals.

theca:ResultList

The root type of the search request. The main contents are placed in the itemListElement, which will include up to the specified k number of elements. The score of each item relative to the query is included in the itemScore in the same position, i.e. the score of the first item will be in the first position in the itemScore list. The score list is placed separately from the items in the ResultList because it is relative to each query rather than intrinsic to the item.

Property	Type	Description
itemListElement	List of Product	Products that are relevant to the search string.
next	Text?	URL to next search query result, if available. See pagination for more information.
itemScore	List of Float	Score of each item in the `itemListElement` relative to the query.
queryDuration	Integer	Time spent in milliseconds by the server to process the request.

This is a custom type extending https://schema.org/ItemList with itemScore and queryDuration.

schema:Product

Property	Type	Description
name	Text	The name of the product.
image	ImageObject?	Extracted from the first `image` or `logo` URL. The size will 512px, the thumbnail will be 256px.
description	Text?	Text description of the product. Extracted from `description`, `slogan`, `disambiguatingDescription`, or `alternateName` †.
brand	Brand?	Extracted from `brand` or `manufacturer` †.
offers	Offer or AggregateOffer	Offers of the product with price, URL, availability, etc. Product variants found in `model` is merged into this as separate Offers.
aggregateRating	AggregateRating?	Normalized and aggregated rating of the product. Extracted from `aggregateRating` or `review` lists †.
mpn	Text?	Manufacturer Part Number (MPN). MPNs are specific to each manufacturer/brand and does not follow any particular standard.
gtin	Text?	Validated Global Trade Item Number (GTIN) according to the GS1 standard. Extracted from `gtin`, `gtin14`, `gtin13`, `gtin12`, `gtin8`, or `isbn` (ISBN-10 is converted to GTIN compliant ISBN-13) †.
productID	Text?	Non-standard product identifier that's not a SKU or GTIN.

† The first valid property of the target’s data will be used.

schema:ImageObject

Property	Type	Description
url	Text	URL to large image. For product images it will be 512px and for organization and brand logos it will be 192px.
thumbnail	Text	URL to smaller image. The original thumbnail will be used if available, otherwise it will be automatically converted from the larger image. For product images it will be 256px and for organization and brand logos it will be 96px.

schema:Brand

Property	Type	Description
name	Text?	Name of the brand. Not guaranteed to be equivalent across targets.
url	Text?	URL of the brand. Can be either an internal or external link depending on targets.
logo	ImageObject?	URL to 192px icon image, the thumbnail will be 96px. Note that, there is usually no consistent format for these images since they can be used in different contexts across targets.

schema:Offer

Property	Type	Description
url	Text	URL to a targets’ product page where the product is sold.
seller	Organization	URL to landing page and display name of the target where the offer is extracted from.
price	Text?	Price of the product as reported by the target. Automatic currency conversion is not supported. If `price` is included, then `priceCurrency` will also always be included. The `price` is formatted according to the ISO 4217 standard. That is, as a decimal number with a fixed number of decimals decided by the currency. Currency codes and symbols will be removed. No thousands separator or whitespace is used. For example, the value "4,999 kr" extracted from a target will be formatted as "4999.00".
priceCurrency	Text?	The currency of the offer. This will be a value from the ISO 4217 format. For example, `SEK` for Swedish krona. Note that, `price` and `priceCurrency` can also be extracted from `priceSpecification`.
availability	Enum?	Availability of the product, one of: BackOrder, Discontinued, InStock, InStoreOnly, LimitedAvailability, OnlineOnly, OutOfStock, PreOrder, PreSale, SoldOut.
itemCondition	Enum?	Condition of the product, one of: DamagedCondition, NewCondition, RefurbishedCondition, UsedCondition.
category	List? of CategoryCode	The product category in the target's category taxonomy.
name	Text?	Overridden Product name of this offer, present only in case it differs from the parent Product.
image	ImageObject?	Overridden Product image of this offer, present only in case it differs from the parent Product.
sku	Text?	Stock Keeping Unit (SKU). Note that, `sku` is placed with Offer rather than Product because it is internal to each seller.
mpn	Text?	Overridden Product mpn of this offer, present only in case it differs from the parent Product.
gtin	Text?	Overridden Product gtin of this offer, present only in case it differs from the parent Product.
productID	Text?	Overridden Product productID of this offer, present only in case it differs from the parent Product.

schema:AggregateOffer

Represents multiple Offers joined by deduplication or by there being multiple variants.

Property	Type	Description
offers	List of Offer	Will always be more than one. It can be from different sellers or there can be multiple offers from the same, if for example, there is a used one offered at a lower price than a new one.
highPrice	Text?	Highest price of the `offers` list †.
lowPrice	Text?	Lowest price of the `offers` list †.
priceCurrency	Text?	Price currency of the `highPrice` and `lowPrice` properties†.

† These properties will only be included if there are well-formed prices that have the same priceCurrency.

schema:CategoryCode

Property	Type	Description
name	Text	Name of the node in the category tree. If no name is given but an URL is present, then the name will be extracted automatically from the URL.
url	Text?	URL to the listed category page.

schema:Organization

Property	Type	Description
name	Text	Name of the organization.
url	Text	Root-path URL of the organization.
logo	ImageObject?	URL to 192px icon image, the thumbnail will be 96px.

This is identical to Brand but the name and url will be configured rather than extracted from crawling.

schema:AggregateRating

Property	Type	Description
ratingValue	Float	Normalized and aggregated score of the product as rated by users. This only uses the values reported by targets, Theca does not support rating products. The minimum and maximum value is normalized to 1 and 5, respectively.
ratingCount	Integer	Number of ratings that the `ratingValue` is based on.

Example requests

Minimal JSON Request

GET https://api.theca.com/v1/search?q=search+string&k=1 HTTP/1.1

Theca-Client-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

HTTP/1.1 200 OK
{
  "itemListElement": [
    {
      "@type": "Product",
      "name": "Product 1",
      "image": {
        "url": "https://cdn.theca.com/<internal>",
        "thumbnail": "https://cdn.theca.com/<internal>"
      },
      "offers": {
        "@type": "Offer",
        "url": "https://api.theca.com/v1/url/<internal>",
        "seller": {
          "name": "Theca"
        }
      }
    }
  ],
  "itemScore": [
    1.0
  ],
  "queryDuration": 101
}

Full featured LD-JSON request

GET https://api.theca.com/v1/search?q=search+string&k=1 HTTP/1.1

Theca-Client-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/ld+json

HTTP/1.1 200 OK
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "Sample Product",
      "image": {
        "@type": "ImageObject",
        "url": "https://cdn.theca.com/<internal>",
        "thumbnail": "https://cdn.theca.com/<internal>"
      },
      "description": "This is a sample product for demonstration purposes.",
      "brand": {
        "@type": "Brand",
        "name": "Sample Brand",
        "url": "https://api.theca.com/v1/url/<internal>",
        "logo": {
          "@type": "ImageObject",
          "url": "https://cdn.theca.com/<internal>",
          "thumbnail": "https://cdn.theca.com/<internal>"
        }
      },
      "offers": {
        "@type": "AggregateOffer",
        "offers": [
          {
            "@type": "Offer",
            "url": "https://api.theca.com/v1/url/<internal>",
            "seller": {
              "@type": "Organization",
              "name": "Sample Seller",
              "url": "https://api.theca.com/v1/url/<internal>",
              "logo": {
                "@type": "ImageObject",
                "url": "https://cdn.theca.com/<internal>",
                "thumbnail": "https://cdn.theca.com/<internal>"
              }
            },
            "price": "99.99",
            "priceCurrency": "SEK",
            "availability": "InStock",
            "itemCondition": "NewCondition",
            "category": [
              {
                "@type": "CategoryCode",
                "name": "Stuff",
                "url": "https://api.theca.com/v1/url/<internal>"
              },
              {
                "@type": "CategoryCode",
                "name": "Sample",
                "url": "https://api.theca.com/v1/url/<internal>"
              }
            ],
            "name": "Variant 1",
            "sku": "SKU-1"
          },
          {
            "@type": "Offer",
            "url": "https://api.theca.com/v1/url/<internal>",
            "seller": {
              "@type": "Organization",
              "name": "Sample Seller",
              "url": "https://api.theca.com/v1/url/<internal>",
              "logo": {
                "@type": "ImageObject",
                "url": "https://cdn.theca.com/<internal>",
                "thumbnail": "https://cdn.theca.com/<internal>"
              }
            },
            "price": "89.99",
            "priceCurrency": "SEK",
            "availability": "https://schema.org/InStock",
            "itemCondition": "https://schema.org/NewCondition",
            "category":  [
              {
                "@type": "CategoryCode",
                "name": "Stuff",
                "url": "https://api.theca.com/v1/url/<internal>"
              },
              {
                "@type": "CategoryCode",
                "name": "Sample",
                "url": "https://api.theca.com/v1/url/<internal>"
              }
            ],
            "name": "Variant 2",
            "sku": "SKU-2",
            "mpn": "MPN1234-2",
            "gtin": "23456781"
          }
        ],
        "highPrice": "89.99",
        "lowPrice": "99.99",
        "priceCurrency": "SEK"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": 4.5,
        "ratingCount": 100
      },
      "mpn": "MPN1234",
      "gtin": "12345670"
    }
  ]
}

Images​

Types​

theca:ResultList​

schema:Product​

schema:ImageObject​

schema:Brand​

schema:Offer​

schema:AggregateOffer​

schema:CategoryCode​

schema:Organization​

schema:AggregateRating​

Example requests​

Minimal JSON Request​

Full featured LD-JSON request​