Skip to main content

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 and in a JPEG format. 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).

Types

The primitive types used are Integer, Float, and Text; these follow the JSON standard. Decimal values will always use dots. 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

PropertyTypeDescription
itemListElementList of ProductProducts that match the search string.
itemScoreList of FloatRelative score of each result in the list.
queryDurationIntegerTime 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

PropertyTypeDescription
nameTextThe name of the product.
imageImageObject?Extracted from the first image or logo URL. The images are extracted from targets and served from our CDN.
descriptionText?Text description of the product. There is a risk of having multiple languages in the description of a ResultList of products if some of the targets used does not translate the descriptions.

Extracted from description, slogan, disambiguatingDescription, or alternateName †.
brandBrand?Extracted from brand or manufacturer †.
offersOffer or AggregateOfferOffers of the product with price, URL, and availability. Product variants found in model is merged into offers.
aggregateRatingAggregateRating?Normalized and aggregated rating of the product. Extracted from aggregateRating or review †.
mpnText?Manufacturer Part Number (MPN). Not guaranteed to be comparable across different targets’ product catalogue.
gtinText?Global Trade Item Number (GTIN).

Extracted from gtin, gtin14, gtin13, gtin12, gtin8, isbn, productID, or identifier †.

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


schema:ImageObject

PropertyTypeDescription
urlTextURL to large 512px product image.
thumbnailTextURL to smaller 256px product image. The original thumbnail will be used if available, otherwise it will be automatically converted from the larger image.

schema:Brand

PropertyTypeDescription
nameTextName of the brand. Not guaranteed to be equivalent across targets.
urlTextURL of the brand. Can be either an internal or external link depending on targets.
logoText?URL to 256px logo image.

While no property is mandatory here, at least one of them will be present if the Brand is present.


schema:Offer

PropertyTypeDescription
urlTextURL to a targets’ product page where the product is sold.
sellerOrganizationURL to landing page and display name of the target where the offer is extracted from.
priceText?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 (though passed as Text) 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".
priceCurrencyText?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.
availabilityEnum?Availability of the product, one of: BackOrder, Discontinued, InStock, InStoreOnly, LimitedAvailability, OnlineOnly, OutOfStock, PreOrder, PreSale, SoldOut.

InStock is the assumed default value which will not be serialized.
itemConditionEnum?Condition of the product, one of: DamagedCondition, NewCondition, RefurbishedCondition, UsedCondition.

NewCondition is the assumed default value which will not be serialized.
categoryText?The product category in the target's category taxonomy. Categories are separated by forward slashes (' / ').
nameText?Overriden Product name of this offer, present only in case it differs from the parent Product.
skuText?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.
mpnText?Overriden Product mpn of this offer, present only in case it differs from the parent Product.
gtinText?Overriden Product gtin of this offer, present only in case it differs from the parent Product.

schema:AggregateOffer

PropertyTypeDescription
offersList of OfferWill 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.
highPriceText?Highest price of the offers list †.
lowPriceText?Lowest price of the offers list †.
priceCurrencyText?Price currency of the highPrice and lowPrice properties†.

† These properties will only be included if all prices in the offers are well formed and able to be parsed and have the same priceCurrency.


schema:Organization

PropertyTypeDescription
nameTextName of the organization.
urlTextRoot-path URL of the organization.

While no property is mandatory here, at least one of them will be present if the Organization is present.


schema:AggregateRating

PropertyTypeDescription
ratingValueFloatNormalized 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.
ratingCountIntegerNumber of ratings that the ratingValue is based on.

Example requests

Minimal Request

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

Successful response
HTTP/1.1 200 OK
{"itemListElement":[{"name":"Product 1","image":{"url":"https://cdn.theca.com/abcd-abcd-abcd-abcd.png"},"offers":{"url":"https://www.theca.com/test-product-1","seller":{"name":"Theca"}}}],"itemScore":[1.0],"queryDuration":101}

GET https://api.theca.com/v1/search?q=search+string&k=1 HTTP/1.1
Theca-Client-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/ld+json

Successful response with all possible fields present
{
"itemListElement": [
{
"@type": "Product",
"name": "Sample Product",
"image": {
"@type": "ImageObject",
"url": "https://cdn.theca.com/abcd-abcd-abcd-abcd.png",
"thumbnail": "https://cdn.theca.com/efgh-efgh-efgh.png"
},
"description": "This is a sample product for demonstration purposes.",
"brand": {
"@type": "Brand",
"name": "Sample Brand",
"url": "https://www.samplebrand.com",
"logo": "https://cdn.theca.com/brand-logo.png"
},
"offers": {
"@type": "AggregateOffer",
"offers": [
{
"@type": "Offer",
"url": "https://www.sampletarget.com/product-page",
"seller": {
"@type": "Organization",
"name": "Sample Seller",
"url": "https://www.sampletarget.com"
},
"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"
},
"price": "89.99",
"priceCurrency": "SEK",
"availability": "InStock",
"itemCondition": "NewCondition"
"category": "Stuff / Sample",
"name": "Variant 2",
"sku": "SKU-2",
"mpn": "MPN1234-2",
"gtin": "GTIN1234-2",
}
],
"highPrice": "89.99",
"lowPrice": "99.99",
"priceCurrency": "SEK"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": 4.5,
"ratingCount": 100
},
"mpn": "MPN1234",
"gtin": "GTIN1234"
}
],
"itemScore": [1.0],
"queryDuration": 101
}