{ "openapi": "3.0.0", "info": { "title": "Tallybuy public API", "version": "1", "description": "Read-only price-comparison facts for Germany and Austria: markets, products, offers with delivered totals, price history, and observed item-price drops measured against each listing's own history. No account or key is needed. Limits apply per caller address; a 429 answer carries Retry-After. Money is a string of minor units with the currency exponent beside it; null means unknown, never zero. purchase_url is a Tallybuy link that passes to the shop; Tallybuy may earn a commission when someone buys, at no extra cost to them. Only sources that permit assistant access are included. The same facts are offered over MCP at https://tallybuy.com/mcp." }, "externalDocs": { "url": "https://tallybuy.com/developers" }, "servers": [ { "url": "https://tallybuy.com", "description": "Production" } ], "paths": { "/v1/comparisons/batch": { "post": { "operationId": "POST:comparison.Batch", "requestBody": { "content": { "application/json": { "schema": { "properties": { "audience": { "type": "string" }, "context_key": { "type": "string" }, "currency": { "type": "string" }, "destination_country": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/comparison.Item" }, "type": "array" }, "market_id": { "type": "string" }, "page_size": { "format": "int64", "type": "integer" }, "sort": { "type": "string" } }, "required": [ "market_id", "currency", "destination_country", "context_key", "audience", "sort", "page_size", "items" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "results": { "items": { "$ref": "#/components/schemas/comparison.Result" }, "type": "array" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "results" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } } } }, "/v1/locales": { "get": { "operationId": "GET:market.Locales", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "locales": { "items": { "$ref": "#/components/schemas/market.Locale" }, "type": "array" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "locales" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Locales lists the reference locales a market can publish.\n" } }, "/v1/markets": { "get": { "operationId": "GET:market.List", "parameters": [ { "allowEmptyValue": true, "explode": true, "in": "query", "name": "status", "required": true, "schema": { "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "markets": { "items": { "$ref": "#/components/schemas/market.Market" }, "type": "array" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "markets" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } } } }, "/v1/markets/{id}/price-drops": { "get": { "description": "A listing is listed when its latest item price, observed within 24 hours, is at least 3% below the same listing's own lowest observed daily item price in the 30 full UTC days before the day the drop was first observed (the pre-drop low), with at least 7 observed days. A drop stays listed for up to 7 days, counting that first day, while the price stays at least 3% below the pre-drop low, and leaves once a day's price reaches the low or the price is less than 3% below it. No list or former price is the reference, and delivery is not included. Largest relative drop first (then listing ID), in pages of limit with a cursor, or as numbered pages with page\\_count. Only products with a picture, outside accessory categories and at or above the item-price floor are listed; method states the rule. An agent caller sees only sources that permit agent access, and seller\\_count counts those.\n", "operationId": "GET:offers.PriceDrops", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "currency", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "locale", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "category_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "limit", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "form" }, { "allowEmptyValue": true, "description": "Cursor is the previous response's next\\_cursor; it is bound to the market, currency, locale and category it came from.\n", "explode": true, "in": "query", "name": "cursor", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "description": "Page asks for numbered page Page (from 1) at this limit instead of a cursor, so a page has an address that does not expire. It excludes a cursor; a page past the last one answers not found (page\\_out\\_of\\_range).\n", "explode": true, "in": "query", "name": "page", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "attribution": { "items": { "$ref": "#/components/schemas/offers.ContentAttribution" }, "title": "Attribution for the content (images) in this response.\n", "type": "array" }, "basis": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "format": "int64", "type": "integer" }, "drops": { "items": { "$ref": "#/components/schemas/offers.PriceDrop" }, "type": "array" }, "has_more": { "type": "boolean" }, "market_id": { "type": "string" }, "method": { "type": "string" }, "next_cursor": { "title": "NextCursor is set when has_more is true: pass it as cursor for the next page.\n", "type": "string" }, "page": { "description": "0\\. A page request carries no next\\_cursor; the next page is page+1 while has\\_more.\n", "format": "int64", "title": "Page is the numbered page returned when the request asked for one, else\n", "type": "integer" }, "page_count": { "description": "the request asked for a page (0 when there is no drop), else 0, so a pager can link the last page.\n", "format": "int64", "title": "PageCount is how many numbered pages the drops fill at this limit when\n", "type": "integer" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "market_id", "currency", "currency_exponent", "basis", "method", "drops", "has_more", "next_cursor", "page", "page_count", "attribution" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "PriceDrops lists observed item-price drops in a market.\n" } }, "/v1/markets/{id}/search": { "post": { "description": "from the offers that satisfy every selected offer constraint together.\n\nWithout a sort, a search with text is ordered by relevance and one without by most\\_sellers: the variants most sellers offer first, and the variants of categories that hold accessories (categories.is\\_accessory) after all others, so a walk through the market starts with what is compared, not with what is cheapest. A result's sort\\_group is 1 for such an accessory under this sort.\n", "operationId": "POST:offers.SearchProducts", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "category_id": { "type": "string" }, "context": { "$ref": "#/components/schemas/offers.SearchContext" }, "cursor": { "type": "string" }, "filters": { "$ref": "#/components/schemas/offers.SearchFilters" }, "identifier": { "allOf": [ { "$ref": "#/components/schemas/offers.SearchIdentifier" } ], "nullable": true }, "limit": { "format": "int64", "type": "integer" }, "locale": { "type": "string" }, "page": { "description": "cursor's continuation, in the order the cursor walks. Only an unfiltered browse of a category or brand has pages (any search with text, an attribute or an offer filter does not), and it excludes a cursor. A page past the last answers not found. The address of a page does not expire.\n", "format": "int64", "title": "Page asks for numbered page Page (from 1) of the listing instead of a\n", "type": "integer" }, "query": { "type": "string" }, "sort": { "type": "string" }, "sort_attribute_key": { "type": "string" } }, "required": [ "query", "identifier", "locale", "context", "category_id", "filters", "sort", "sort_attribute_key", "cursor", "page", "limit" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "attribute_facets": { "items": { "$ref": "#/components/schemas/offers.SearchAttributeFacet" }, "type": "array" }, "attribution": { "items": { "$ref": "#/components/schemas/offers.ContentAttribution" }, "type": "array" }, "catalog_scope": { "type": "string" }, "category_id": { "type": "string" }, "context": { "$ref": "#/components/schemas/offers.ComparisonContext" }, "count_capped": { "description": "and attribute facet counts then cover the best TotalCount matches in the search's order, not every match.\n", "title": "CountCapped is true when more variants match than TotalCount. The facet\n", "type": "boolean" }, "count_relation": { "description": "counting at its cap of 1,000 matches. A search without text counts exactly.\n", "title": "CountRelation is \"exact\", or \"at_least\" when a text search stopped\n", "type": "string" }, "effective_filters": { "$ref": "#/components/schemas/offers.SearchFilters" }, "evaluated_at": { "type": "string" }, "facets": { "items": { "$ref": "#/components/schemas/offers.SearchFacet" }, "type": "array" }, "has_more": { "type": "boolean" }, "locale": { "type": "string" }, "market_id": { "type": "string" }, "next_cursor": { "type": "string" }, "page": { "description": "the page returned and the number of pages at this limit. A page request carries no next\\_cursor; the next page is Page+1 while has\\_more.\n", "format": "int64", "title": "Page and PageCount are set when the request asked for a page number:\n", "type": "integer" }, "page_count": { "format": "int64", "type": "integer" }, "price_coverage": { "$ref": "#/components/schemas/offers.SearchPriceCoverage" }, "query": { "type": "string" }, "result_unit": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/offers.SearchResult" }, "type": "array" }, "revision": { "format": "int64", "type": "integer" }, "schema_version": { "type": "string" }, "sort": { "type": "string" }, "sort_attribute_key": { "type": "string" }, "total_count": { "description": "\"at\\_least\" it is the count's cap, a lower bound.\n", "format": "int64", "title": "TotalCount is the number of matching variants; when CountRelation is\n", "type": "integer" } }, "required": [ "schema_version", "result_unit", "market_id", "locale", "query", "context", "category_id", "effective_filters", "catalog_scope", "sort", "sort_attribute_key", "total_count", "count_relation", "count_capped", "facets", "attribute_facets", "price_coverage", "results", "has_more", "next_cursor", "page", "page_count", "revision", "evaluated_at", "attribution" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "SearchProducts returns one row per exact variant. Each price and count comes\n" } }, "/v1/products": { "get": { "operationId": "GET:catalog.Search", "parameters": [ { "allowEmptyValue": true, "explode": true, "in": "query", "name": "q", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "description": "MarketID, when set, limits results to products with a public offer in that active market (identifier lookup per market).\n", "explode": true, "in": "query", "name": "market_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "brand_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "limit", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "products": { "items": { "$ref": "#/components/schemas/catalog.ProductSummary" }, "type": "array" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "products" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } } } }, "/v1/products/{id}": { "get": { "operationId": "GET:catalog.Get", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "description": "Locale selects content and specifications; empty returns none.\n", "explode": true, "in": "query", "name": "locale", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "description": "MarketID scopes content-source permissions for public reads.\n", "explode": true, "in": "query", "name": "market_id", "required": true, "schema": { "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content": { "$ref": "#/components/schemas/catalog.ProductContent" }, "locale": { "title": "Locale is the content locale requested; content is empty without one.\n", "type": "string" }, "product": { "$ref": "#/components/schemas/catalog.Product" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "product", "locale", "content" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } } } }, "/v1/regions": { "get": { "description": "created for, with their time zones. Reference data, not coverage: a region listed here has no market until one is created and activated.\n", "operationId": "GET:market.Regions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "regions": { "items": { "$ref": "#/components/schemas/market.Region" }, "type": "array" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "regions" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Regions lists the reference regions (ISO 3166-1 alpha-2) a market can be\n" } }, "/v1/variants/{id}/history": { "get": { "operationId": "GET:history.List", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "market_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "from", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "to", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "cursor", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "limit", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "has_more": { "type": "boolean" }, "history": { "items": { "$ref": "#/components/schemas/history.Point" }, "type": "array" }, "market_id": { "type": "string" }, "next_cursor": { "type": "string" }, "schema_version": { "type": "string" }, "variant_id": { "type": "string" } }, "required": [ "schema_version", "variant_id", "market_id", "history", "has_more", "next_cursor", "effective_from", "effective_to" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } } } }, "/v1/variants/{id}/offers": { "get": { "description": "No currency conversion or winner selection is performed.\n", "operationId": "GET:offers.List", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "market_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "currency", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "destination_country", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "context_key", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "quantity", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "quantity_unit", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "audience", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "sort", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "condition", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "availability", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "merchant_id", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "cursor", "required": true, "schema": { "type": "string" }, "style": "form" }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "limit", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "context": { "$ref": "#/components/schemas/offers.ComparisonContext" }, "has_more": { "type": "boolean" }, "market_id": { "type": "string" }, "next_cursor": { "type": "string" }, "offers": { "items": { "$ref": "#/components/schemas/offers.Offer" }, "type": "array" }, "schema_version": { "type": "string" }, "variant_id": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "schema_version", "variant_id", "market_id", "context", "offers", "has_more", "next_cursor", "warnings" ], "type": "object" } } }, "description": "Success response" }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "List compares same-currency offers explicitly targeting the requested market.\n" } } }, "components": { "responses": { "APIError": { "content": { "application/json": { "schema": { "externalDocs": { "url": "https://pkg.go.dev/encore.dev/beta/errs#Error" }, "properties": { "code": { "description": "Error code", "example": "not_found", "externalDocs": { "url": "https://pkg.go.dev/encore.dev/beta/errs#ErrCode" }, "type": "string" }, "details": { "description": "Error details", "type": "object" }, "message": { "description": "Error message", "type": "string" } }, "title": "APIError", "type": "object" } } }, "description": "Error response" } }, "schemas": { "catalog.Attribution": { "properties": { "source_key": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string", "nullable": true } }, "required": [ "source_key", "text", "url" ], "title": "Attribution is what a page showing this content must display.\n", "type": "object" }, "catalog.Content": { "properties": { "description": { "type": "string", "nullable": true }, "source_key": { "type": "string" }, "source_updated_at": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "title": { "type": "string" } }, "required": [ "title", "summary", "description", "source_key", "source_updated_at" ], "type": "object" }, "catalog.Identifier": { "properties": { "namespace": { "type": "string" }, "scheme": { "type": "string" }, "value": { "type": "string" } }, "required": [ "scheme", "namespace", "value" ], "type": "object" }, "catalog.Image": { "properties": { "height": { "format": "int64", "type": "integer", "nullable": true }, "main": { "type": "boolean" }, "url": { "type": "string" }, "width": { "format": "int64", "type": "integer", "nullable": true } }, "required": [ "url", "width", "height", "main" ], "type": "object" }, "catalog.Product": { "properties": { "brand_name": { "type": "string", "nullable": true }, "canonical_name": { "type": "string" }, "category_id": { "type": "string" }, "id": { "type": "string" }, "locales": { "items": { "type": "string" }, "type": "array" }, "status": { "type": "string" }, "variants": { "items": { "$ref": "#/components/schemas/catalog.Variant" }, "type": "array" } }, "required": [ "id", "brand_name", "canonical_name", "category_id", "status", "locales", "variants" ], "type": "object" }, "catalog.ProductContent": { "properties": { "attribution": { "items": { "$ref": "#/components/schemas/catalog.Attribution" }, "type": "array" }, "content": { "items": { "$ref": "#/components/schemas/catalog.Content" }, "type": "array" }, "identifiers": { "items": { "$ref": "#/components/schemas/catalog.Identifier" }, "type": "array" }, "images": { "items": { "$ref": "#/components/schemas/catalog.Image" }, "type": "array" }, "specs": { "items": { "$ref": "#/components/schemas/catalog.Spec" }, "type": "array" } }, "required": [ "content", "specs", "images", "identifiers", "attribution" ], "type": "object" }, "catalog.ProductSummary": { "properties": { "brand_name": { "type": "string", "nullable": true }, "canonical_name": { "type": "string" }, "category_id": { "type": "string" }, "id": { "type": "string" }, "locales": { "items": { "type": "string" }, "type": "array" }, "status": { "type": "string" } }, "required": [ "id", "brand_name", "canonical_name", "category_id", "status", "locales" ], "type": "object" }, "catalog.Spec": { "properties": { "group": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "group", "name", "value" ], "type": "object" }, "catalog.Variant": { "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "variant_key": { "type": "string" } }, "required": [ "id", "variant_key", "label", "status" ], "type": "object" }, "comparison.Item": { "properties": { "availability": { "type": "string" }, "condition": { "type": "string" }, "cursor": { "type": "string" }, "merchant_id": { "type": "string" }, "quantity": { "type": "string" }, "quantity_unit": { "type": "string" }, "reference": { "description": "labels it \"item-N\" by position.\n", "title": "Reference is the caller's label for the item; when omitted the answer\n", "type": "string" }, "variant_id": { "type": "string" } }, "required": [ "reference", "variant_id", "quantity", "quantity_unit", "condition", "availability", "merchant_id", "cursor" ], "type": "object" }, "comparison.Result": { "properties": { "context": { "$ref": "#/components/schemas/offers.ComparisonContext" }, "error": { "type": "string" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "offers": { "items": { "$ref": "#/components/schemas/offers.Offer" }, "type": "array" }, "reference": { "type": "string" }, "status": { "type": "string" }, "variant_id": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "reference", "variant_id", "status", "offers", "context", "has_more", "next_cursor", "warnings", "error" ], "type": "object" }, "history.Point": { "properties": { "condition": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "format": "int32", "maximum": 32767, "minimum": -32768, "type": "integer" }, "day": { "type": "string" }, "last_minor": { "type": "string" }, "listing_id": { "type": "string" }, "maximum_minor": { "type": "string" }, "minimum_minor": { "type": "string" }, "sample_count": { "format": "int64", "type": "integer" }, "series_kind": { "type": "string" } }, "required": [ "listing_id", "day", "currency", "currency_exponent", "series_kind", "condition", "minimum_minor", "maximum_minor", "last_minor", "sample_count" ], "type": "object" }, "market.Coverage": { "description": "public offer, public offers (one per listing), and stores (sellers) with at least one. They count the offers search shows (readmodel's SearchPublicListingsSQL), so they equal what the market's product and store reads list.\n", "properties": { "offer_count": { "format": "int64", "type": "integer" }, "product_count": { "format": "int64", "type": "integer" }, "store_count": { "format": "int64", "type": "integer" } }, "required": [ "product_count", "offer_count", "store_count" ], "title": "Coverage is a market's public listing counts: products with at least one\n", "type": "object" }, "market.Locale": { "properties": { "english_name": { "type": "string" }, "language": { "type": "string" }, "native_name": { "type": "string" }, "region_code": { "type": "string", "nullable": true }, "tag": { "type": "string" } }, "required": [ "tag", "language", "region_code", "english_name", "native_name" ], "type": "object" }, "market.Market": { "properties": { "country_code": { "type": "string" }, "coverage": { "allOf": [ { "$ref": "#/components/schemas/market.Coverage" } ], "description": "currency, so a page can show it without summing. Counts, not a quality or popularity measure.\n", "title": "Coverage counts what the market publicly lists right now, in its default\n" }, "currency_exponent": { "format": "int32", "maximum": 32767, "minimum": -32768, "type": "integer" }, "default_currency": { "type": "string" }, "default_locale": { "type": "string" }, "id": { "type": "string" }, "indexable": { "description": "(shared/indexing). When false every page of the market still answers, with \\`noindex, follow\\`, and none is in the sitemap or named as an hreflang alternate.\n", "title": "Indexable is whether search engines may index the market's pages\n", "type": "boolean" }, "locales": { "items": { "type": "string" }, "type": "array" }, "region_name": { "title": "RegionName is the region's reference name in English; pages localize it.\n", "type": "string" }, "status": { "type": "string" }, "time_zone": { "description": "day-based rules. Null only for a planned market not yet configured.\n", "title": "TimeZone is the market's IANA zone for rendering provenance times and\n", "type": "string", "nullable": true } }, "required": [ "id", "country_code", "region_name", "default_currency", "currency_exponent", "default_locale", "time_zone", "locales", "status", "indexable", "coverage" ], "type": "object" }, "market.Region": { "properties": { "code": { "type": "string" }, "default_time_zone": { "type": "string", "nullable": true }, "name": { "type": "string" }, "time_zones": { "description": "suggestion for a new market.\n", "items": { "type": "string" }, "title": "TimeZones are the zones in use in the region; DefaultTimeZone is the\n", "type": "array" } }, "required": [ "code", "name", "time_zones", "default_time_zone" ], "type": "object" }, "offers.ComparisonContext": { "properties": { "audience": { "type": "string" }, "context_key": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "format": "int64", "type": "integer" }, "destination_country": { "type": "string" }, "filters": { "$ref": "#/components/schemas/offers.Filters" }, "market_id": { "type": "string" }, "quantity": { "type": "string" }, "quantity_unit": { "type": "string" }, "sort": { "type": "string" } }, "required": [ "market_id", "currency", "currency_exponent", "destination_country", "context_key", "quantity", "quantity_unit", "audience", "sort", "filters" ], "type": "object" }, "offers.ContentAttribution": { "description": "a page showing it must display the text, linked.\n", "properties": { "text": { "type": "string" }, "url": { "type": "string", "nullable": true } }, "required": [ "text", "url" ], "title": "ContentAttribution is a content source whose material a response carries;\n", "type": "object" }, "offers.Delivery": { "properties": { "additional_tax_minor": { "type": "string", "nullable": true }, "completeness": { "type": "string" }, "mandatory_fees_minor": { "type": "string", "nullable": true }, "missing_fields": { "items": { "type": "string" }, "type": "array" }, "shipping_minor": { "type": "string", "nullable": true } }, "required": [ "shipping_minor", "additional_tax_minor", "mandatory_fees_minor", "completeness", "missing_fields" ], "type": "object" }, "offers.Filters": { "properties": { "availability": { "type": "string" }, "condition": { "type": "string" }, "merchant_id": { "type": "string" } }, "required": [ "condition", "availability", "merchant_id" ], "type": "object" }, "offers.Offer": { "properties": { "availability": { "type": "string" }, "condition": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "format": "int64", "type": "integer" }, "delivery": { "$ref": "#/components/schemas/offers.Delivery" }, "destination_url": { "type": "string" }, "freshness_status": { "type": "string" }, "item_price_minor": { "type": "string", "nullable": true }, "listing_id": { "type": "string" }, "merchant_id": { "type": "string" }, "merchant_name": { "type": "string" }, "minimum_quantity": { "type": "string", "nullable": true }, "observed_at": { "type": "string" }, "pack_quantity": { "type": "string", "nullable": true }, "pack_unit": { "type": "string", "nullable": true }, "price_quantity": { "type": "string", "nullable": true }, "price_unit": { "type": "string", "nullable": true }, "pricing": { "$ref": "#/components/schemas/offers.Pricing" }, "purchase_url": { "description": "or null where no link may be given.\n", "title": "PurchaseURL is the Tallybuy short link to hand a person (see links.go),\n", "type": "string", "nullable": true }, "quantity_eligibility": { "type": "string" }, "quantity_step": { "type": "string", "nullable": true }, "regular_difference_minor": { "type": "string", "nullable": true }, "regular_price_basis": { "type": "string", "nullable": true }, "regular_price_minor": { "description": "feed (regular\\_price\\_basis \"merchant\\_feed\"), only when the feed states one above the item price. It is not a manufacturer's recommended price. RegularDifferenceMinor is regular minus item price, computed here.\n", "title": "RegularPriceMinor is the merchant's own stated regular price from its\n", "type": "string", "nullable": true }, "seller_country": { "type": "string", "nullable": true }, "source_name": { "type": "string" }, "tax_inclusion": { "type": "string" } }, "required": [ "listing_id", "merchant_id", "merchant_name", "seller_country", "source_name", "condition", "destination_url", "purchase_url", "currency", "currency_exponent", "item_price_minor", "regular_price_minor", "regular_price_basis", "regular_difference_minor", "price_quantity", "price_unit", "pack_quantity", "pack_unit", "minimum_quantity", "quantity_step", "quantity_eligibility", "tax_inclusion", "availability", "observed_at", "freshness_status", "delivery", "pricing" ], "type": "object" }, "offers.PriceDrop": { "properties": { "condition": { "type": "string" }, "drop_basis_points": { "format": "int64", "type": "integer" }, "drop_minor": { "type": "string" }, "drop_percent": { "description": "down (1,899 basis points is 18, never 19), so a badge never overstates. It is the same fact as drop\\_minor over reference\\_low\\_minor, stated once here so no channel computes it.\n", "format": "int64", "title": "DropPercent is the drop as whole percent of the reference low, rounded\n", "type": "integer" }, "image_url": { "description": "An agent caller is handed no raw image address (null), as in search.\n", "title": "ImageURL is the product's main image from an approved content source.\n", "type": "string", "nullable": true }, "item_price_minor": { "type": "string" }, "listing_id": { "type": "string" }, "merchant_id": { "type": "string" }, "merchant_name": { "type": "string" }, "name": { "type": "string" }, "name_locale": { "description": "authoring name.\n", "title": "NameLocale is the locale of the label Name comes from, or null for the\n", "type": "string", "nullable": true }, "observed_at": { "type": "string" }, "product_id": { "type": "string" }, "reference_days_observed": { "format": "int64", "type": "integer" }, "reference_from": { "type": "string" }, "reference_low_day": { "title": "ReferenceLowDay is the latest day in the window with the reference low.\n", "type": "string" }, "reference_low_minor": { "type": "string" }, "reference_series": { "description": "reference window (reference\\_from to reference\\_to, its currency and condition), oldest first: the drop's sparkline. Days without an observation are absent; it is empty when the source does not permit history.\n", "items": { "$ref": "#/components/schemas/offers.PriceDropDay" }, "title": "ReferenceSeries is the listing's observed daily item price in the\n", "type": "array" }, "reference_to": { "type": "string" }, "seller_count": { "description": "the market and currency.\n", "format": "int64", "title": "SellerCount is how many sellers have a public offer for this variant in\n", "type": "integer" }, "slug": { "type": "string", "nullable": true }, "variant_id": { "type": "string" }, "variant_label": { "type": "string" } }, "required": [ "listing_id", "product_id", "variant_id", "variant_label", "name", "name_locale", "slug", "merchant_id", "merchant_name", "condition", "item_price_minor", "reference_low_minor", "reference_low_day", "drop_minor", "drop_basis_points", "drop_percent", "reference_from", "reference_to", "reference_days_observed", "observed_at", "seller_count", "image_url", "reference_series" ], "type": "object" }, "offers.PriceDropDay": { "description": "seen that day, in minor units.\n", "properties": { "day": { "type": "string" }, "last_minor": { "type": "string" } }, "required": [ "day", "last_minor" ], "title": "PriceDropDay is one observed day of a drop's listing: the last item price\n", "type": "object" }, "offers.Pricing": { "properties": { "additional_tax_minor": { "type": "string", "nullable": true }, "completeness": { "type": "string" }, "conditions": { "items": { "type": "string" }, "type": "array" }, "delivered_total_minor": { "type": "string", "nullable": true }, "item_subtotal_minor": { "type": "string", "nullable": true }, "mandatory_fees_minor": { "type": "string", "nullable": true }, "missing_fields": { "items": { "type": "string" }, "type": "array" }, "shipping_minor": { "type": "string", "nullable": true } }, "required": [ "item_subtotal_minor", "shipping_minor", "additional_tax_minor", "mandatory_fees_minor", "delivered_total_minor", "completeness", "missing_fields", "conditions" ], "type": "object" }, "offers.SearchAttributeFacet": { "properties": { "buckets": { "items": { "$ref": "#/components/schemas/offers.SearchFacetBucket" }, "type": "array" }, "conflict_count": { "format": "int64", "type": "integer" }, "has_more_values": { "type": "boolean" }, "key": { "type": "string" }, "known_count": { "format": "int64", "type": "integer" }, "known_max": { "type": "string", "nullable": true }, "known_min": { "type": "string", "nullable": true }, "not_applicable_count": { "format": "int64", "type": "integer" }, "unknown_count": { "format": "int64", "type": "integer" }, "value_type": { "type": "string" } }, "required": [ "key", "value_type", "known_count", "conflict_count", "unknown_count", "not_applicable_count", "known_min", "known_max", "buckets", "has_more_values" ], "type": "object" }, "offers.SearchAttributeFilter": { "description": "Decimal bounds travel as strings; false and missing remain distinct.\n", "properties": { "boolean_value": { "type": "boolean", "nullable": true }, "include_unknown": { "type": "boolean" }, "key": { "type": "string" }, "max": { "type": "string", "nullable": true }, "min": { "type": "string", "nullable": true }, "operator": { "type": "string" }, "option_ids": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "operator", "min", "max", "option_ids", "boolean_value", "include_unknown" ], "title": "SearchAttributeFilter uses a reviewed category definition's canonical unit.\n", "type": "object" }, "offers.SearchContext": { "properties": { "audience": { "type": "string" }, "context_key": { "type": "string" }, "currency": { "type": "string" }, "destination_country": { "type": "string" }, "quantity": { "type": "string" }, "quantity_unit": { "type": "string" } }, "required": [ "currency", "destination_country", "context_key", "quantity", "quantity_unit", "audience" ], "type": "object" }, "offers.SearchFacet": { "properties": { "buckets": { "items": { "$ref": "#/components/schemas/offers.SearchFacetBucket" }, "type": "array" }, "key": { "type": "string" } }, "required": [ "key", "buckets" ], "type": "object" }, "offers.SearchFacetBucket": { "description": "applied. Counts are self-excluding: selecting a brand does not hide its alternatives inside the brand facet.\n", "properties": { "count": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "selected": { "type": "boolean" }, "value": { "type": "string" } }, "required": [ "value", "name", "count", "selected" ], "title": "SearchFacetBucket counts distinct variants after all other groups are\n", "type": "object" }, "offers.SearchFilters": { "properties": { "attributes": { "items": { "$ref": "#/components/schemas/offers.SearchAttributeFilter" }, "type": "array" }, "availability": { "items": { "type": "string" }, "type": "array" }, "brand_ids": { "items": { "type": "string" }, "type": "array" }, "merchant_ids": { "items": { "type": "string" }, "type": "array" }, "price": { "allOf": [ { "$ref": "#/components/schemas/offers.SearchPriceFilter" } ], "nullable": true } }, "required": [ "brand_ids", "merchant_ids", "availability", "price", "attributes" ], "type": "object" }, "offers.SearchIdentifier": { "properties": { "brand_id": { "type": "string" }, "scheme": { "type": "string" }, "value": { "type": "string" } }, "required": [ "scheme", "value", "brand_id" ], "type": "object" }, "offers.SearchPriceCoverage": { "properties": { "complete_total": { "format": "int64", "type": "integer" }, "item_only": { "format": "int64", "type": "integer" }, "unpriced": { "format": "int64", "type": "integer" } }, "required": [ "complete_total", "item_only", "unpriced" ], "type": "object" }, "offers.SearchPriceFilter": { "properties": { "basis": { "type": "string" }, "include_unknown": { "type": "boolean" }, "max_minor": { "type": "string", "nullable": true }, "min_minor": { "type": "string", "nullable": true } }, "required": [ "basis", "min_minor", "max_minor", "include_unknown" ], "type": "object" }, "offers.SearchQuote": { "description": "DeliveryKnown says whether that offer's delivery cost for the request's context is stated: always true for the lowest complete total; for the lowest item subtotal, true only when no delivery field is among MissingFields (its total can still be unknown for another reason, such as tax or fees).\n\nA quote names its own money: AmountMinor is in minor units of Currency, with CurrencyExponent decimal places, so a quote read on its own is not ambiguous. PurchaseURL is the Tallybuy short link to the offer, null when none may be given.\n", "properties": { "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "format": "int64", "type": "integer" }, "delivery_known": { "type": "boolean" }, "listing_id": { "type": "string" }, "merchant_id": { "type": "string" }, "merchant_name": { "type": "string" }, "missing_fields": { "items": { "type": "string" }, "type": "array" }, "observed_at": { "type": "string" }, "purchase_url": { "type": "string", "nullable": true }, "source_name": { "type": "string" } }, "required": [ "listing_id", "merchant_id", "merchant_name", "source_name", "observed_at", "amount_minor", "currency", "currency_exponent", "missing_fields", "delivery_known", "purchase_url" ], "title": "SearchQuote is the offer behind one of a result's lowest prices.\n", "type": "object" }, "offers.SearchResult": { "properties": { "brand_id": { "type": "string", "nullable": true }, "brand_name": { "type": "string", "nullable": true }, "category_id": { "type": "string" }, "complete_offer_count": { "format": "int64", "type": "integer" }, "image_url": { "type": "string", "nullable": true }, "lowest_complete_total_quote": { "allOf": [ { "$ref": "#/components/schemas/offers.SearchQuote" } ], "nullable": true }, "lowest_item_subtotal_quote": { "allOf": [ { "$ref": "#/components/schemas/offers.SearchQuote" } ], "nullable": true }, "match_reason": { "type": "string" }, "matching_offer_count": { "format": "int64", "type": "integer" }, "matching_seller_count": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "name_locale": { "type": "string", "nullable": true }, "product_id": { "type": "string" }, "product_url": { "description": "locale, where every offer is compared; null when the site address is not configured, the product has no slug or the locale is not one the market publishes.\n", "title": "ProductURL is the product's page on the website in the request's\n", "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "sort_group": { "format": "int64", "type": "integer" }, "variant_id": { "type": "string" }, "variant_label": { "type": "string" } }, "required": [ "product_id", "variant_id", "variant_label", "name", "name_locale", "slug", "brand_id", "brand_name", "category_id", "product_url", "image_url", "matching_offer_count", "matching_seller_count", "complete_offer_count", "lowest_complete_total_quote", "lowest_item_subtotal_quote", "match_reason", "sort_group" ], "type": "object" } } } }