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 primitive types used are Integer, Float, and Text; these follow the JSON standard. Numbers passed as Text or Float will always use period as decimal separator. Enum is a string from a pre-defined set of values.

note

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

The following tables describes all the types returned by the search request.

theca:ResultList

Property	Type	Description
itemListElement	List of Product	Products that match the search string.
next	Text?	URL to next search query result, if available. The `q` and `k` should not be changed (it will give incorrect results), but `filter` (e.g. `filterSku`) query parameters may be changed.
itemScore	List of Float	Relative score of each result in the list given in the same order. This is placed separately from the items in the ResultList because it is specific to each query rather than intrinsic to the item.
queryDuration	Integer	Time spent in milliseconds by the server to process the request. Does not include round-trip cost between client and server.

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) †.

† 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	Text?	The product category in the target's category taxonomy. Categories are separated by forward slashes (' / ').
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. Extracted from `sku`, `productID`, `identifier`, or `serialNumber`.
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.

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: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 value is always 1 and the maximum value is always 5.
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/abcd-abcd-abcd-abcd.webp",
        "thumbnail": "https://cdn.theca.com/efgh-efgh-efgh-efgh.webp"
      },
      "offers": {
        "@type": "Offer",
        "url": "https://www.theca.com/test-product-1",
        "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/abcd-abcd-abcd-abcd.webp",
        "thumbnail": "https://cdn.theca.com/efgh-efgh-efgh-efgh.webp"
      },
      "description": "This is a sample product for demonstration purposes.",
      "brand": {
        "@type": "Brand",
        "name": "Sample Brand",
        "url": "https://www.samplebrand.com",
        "logo": {
          "@type": "ImageObject",
          "url": "https://cdn.theca.com/abcd-abcd-abcd-abcd.webp",
          "thumbnail": "https://cdn.theca.com/efgh-efgh-efgh-efgh.webp"
        }
      },
      "offers": {
        "@type": "AggregateOffer",
        "offers": [
          {
            "@type": "Offer",
            "url": "https://www.sampletarget.com/product-page",
            "seller": {
              "@type": "Organization",
              "name": "Sample Seller",
              "url": "https://www.sampletarget.com",
              "logo": {
                "@type": "ImageObject",
                "url": "https://cdn.theca.com/abcd-abcd-abcd-abcd.webp",
                "thumbnail": "https://cdn.theca.com/efgh-efgh-efgh-efgh.webp"
              }
            },
            "price": "99.99",
            "priceCurrency": "SEK",
            "availability": "InStock",
            "itemCondition": "NewCondition",
            "category": "Stuff / Sample",
            "name": "Variant 1",
            "sku": "SKU-1"
          },
          {
            "@type": "Offer",
            "url": "https://www.sampletarget.com/product-page",
            "seller": {
              "@type": "Organization",
              "name": "Sample Seller",
              "url": "https://www.sampletarget.com",
              "logo": {
                "@type": "ImageObject",
                "url": "https://cdn.theca.com/abcd-abcd-abcd-abcd.webp",
                "thumbnail": "https://cdn.theca.com/efgh-efgh-efgh-efgh.webp"
              }
            },
            "price": "89.99",
            "priceCurrency": "SEK",
            "availability": "https://schema.org/InStock",
            "itemCondition": "https://schema.org/NewCondition",
            "category": "Stuff / Sample",
            "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:Organization​

schema:AggregateRating​

Example requests​

Minimal JSON Request​

Full featured LD-JSON request​