Search Products By Image URL
products.search.image_urlSearch PoloPan catalog products using visual image similarity from a publicly accessible image URL with optional multi-attribute filters. Returns visually similar products with available sizes, pricing, and verified purchase URLs (https://s.polopan.com/p/{handle}). Automatically localized to active country / 240+ destination regions.
PURPOSE & DISAMBIGUATION:
Performs reverse visual search using computer-vision embeddings for a remote image URL.
Distinct from 'products.search.text': Use this tool when you have an image URL, NOT for textual keyword queries.
Distinct from 'products.search.image_upload': Use this tool for publicly hosted HTTP(S) image URLs, NOT for local file paths or base64 data.
Distinct from 'vision.outfit.detect_pieces': Use this tool to search catalog items matching an entire single-garment image, NOT for segmenting multi-garment influencer photos into bounding boxes.
WHEN TO USE:
When the user shares a web link to an image (e.g. Pinterest, Instagram, blog post) and wants to find visually matching products in the PoloPan catalog.
WHEN NOT TO USE:
Do NOT use when the image is stored on local disk or as base64 data (use 'products.search.image_upload').
Do NOT use when searching by text descriptions (use 'products.search.text').
Do NOT use when you need to crop/isolate individual outfit pieces from a full-body model photo (use 'vision.outfit.detect_pieces').
BEHAVIOR & SAFETY:
Read-only and idempotent with no persistent state modifications.
Downloads the image, generates visual embeddings, and retrieves ranked catalog matches.
Enriches all returned items with verified PoloPan purchase links and stock metadata.
PARAMETERS & CONSTRAINTS:
'image_url' (string, required): Publicly accessible HTTP(S) URL of the image to search for visual matches.
'country' (string, optional): Target country name, city, currency, or ISO-2 code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region.
'mode' (enum, optional): Catalog mode: 'global' (ships to country) or 'local' (domestic only).
'page' (integer >= 1, default 1): Pagination page number.
'page_size' (integer 1-100, default 20): Number of candidate items returned per page.
'sort_by' (enum, default 'relevance'): Ranking attribute ('relevance', 'price', 'title').
'sort_order' (enum, default 'desc'): Sort order ('asc' or 'desc').
'gender' (string, optional): Target gender filter ('men', 'women', or 'unisex').
'size' (array of strings, optional): Filter by available size labels.
'price_min' (number, optional): Minimum price threshold.
'price_max' (number, optional): Maximum price threshold.
'vendor' (array of strings, optional): Brand filter array.
'personalize' (boolean, default false): Whether to apply personalized ranking weights.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Catalog mode: 'global' (ships to country) or 'local' (domestic only). Defaults to active saved region. | |
| page | No | Page number for pagination (1-indexed) | |
| size | No | Array of sizes to filter by (e.g. ['S', 'M', 'L']) | |
| gender | No | Target gender filter: 'men', 'women', or 'unisex' | |
| vendor | No | List of brand names to filter by | |
| country | No | Country name, city, currency, or 2-letter ISO code (e.g. 'US', 'United States', 'UK', 'Dubai', 'CA', 'IN'). Defaults to active saved region. | |
| sort_by | No | Sorting criteria for search results: 'relevance', 'price', or 'title' | relevance |
| image_url | Yes | Publicly accessible HTTP(S) URL of the fashion image to search for visual matches | |
| page_size | No | Number of items to return per page (1 to 100, default 20) | |
| price_max | No | Maximum price in local currency | |
| price_min | No | Minimum price in local currency | |
| sort_order | No | Sort order: 'asc' for ascending, 'desc' for descending | desc |
| personalize | No | Whether to apply personalized ranking based on user style profile |