Search
This is the main request of the service, and it returns a list of complex products (with images, offers, etc.) matching a search string. The arguments are passed as query parameters.
Request
Query parameters
| Parameter | Type | Description |
|---|---|---|
| q | Text | Users’ search string. The maximum length is 2,048 characters, the remainder will be discarded. The parameter needs to be URL encoded. Quote operator and negated terms are supported. |
| k | Integer? | Number of results to return (default 10) between 1-100. |
| filterSku | Text | Remove products from the result that matches the given stock keeping unit (SKU). Multiple SKUs can be delimited with |. For example, filterSku=52293|182491 ensure that no product with SKU 52293 or 182491 are included in the results. A match is counted if the SKU starts with the given filter, so in the previous example the SKU 52293-v2 would also get removed. |
| filterMpn | Text | See filterSku. |
| filterGtin | Text | See filterSku. |
Pagination
More results for a given query can be retrieved by using the next link of the ResultList. This is an absolute URL to the API that includes the state needed to generate more results. As such, pagination does not support a deep link that users can copy/paste. The query parameters used in the original request will be copied to the next link. The included q-parameter cannot be changed (it would give incorrect results), but filter (e.g. filterSku) and k query parameters may be changed.
Note that, there is no guarantee that you will get exactly the same results if you do a request with a large k and compare those with sequential paginated results with a smaller k.
Sorting results
Affecting the search results by business rules is possible but is not yet part of the public API. This includes prioritizing, e.g., new products, cheap or expensive items, products with many clicks, adding randomness to the results, ratings, etc.
Response
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 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 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
Minimal JSON request
Theca-Client-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
"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
Theca-Client-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/ld+json
{
"@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"
}
]
}