# Product - Search V2 ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/item/v2/search: get: summary: Product - Search V2 deprecated: false description: >- Product search V2. discoverTime and Top 3 video times are shifted from the stored UTC+8 wall clock to the timezone of x-selected-lng. The discover-date filter is converted from the user's local day back to UTC+8 before querying. zh-CN does not shift; ja-JP adds 1 hour to returned times. Category names follow this header. Language values come from GET /api/meta/language. tags: - Data APIs/Item parameters: - name: period in: query description: 'Time period. Enum: 1d, 7d, 30d, 90d, 180d, 365d' required: true example: 7d schema: type: string enum: - 1d - 7d - 30d - 90d - 180d - 365d - name: itemName in: query description: Item name, supports fuzzy search required: false example: '' schema: type: string - name: region in: query description: Country/region code, e.g. US, GB, TH required: false example: US schema: type: string - name: tkCategoryLv1Id in: query description: TK Level-1 Category ID required: false example: '' schema: type: string - name: tkCategoryLv2Id in: query description: TK Level-2 Category ID required: false example: '' schema: type: string - name: tkCategoryLv3Id in: query description: TK Level-3 Category ID required: false example: '' schema: type: string - name: localPriceBegin in: query description: Local price lower bound required: false example: 0 schema: type: number - name: localPriceEnd in: query description: Local price upper bound required: false example: 0 schema: type: number - name: soldCountTotalBegin in: query description: Historical total sales volume lower bound required: false example: 0 schema: type: integer - name: soldCountTotalEnd in: query description: Historical total sales volume upper bound required: false example: 0 schema: type: integer - name: discoverTimeStartDs in: query description: 'Discover time start, format: yyyyMMdd, e.g. 20251201' required: false example: '20251201' schema: type: string - name: discoverTimeEndDs in: query description: 'Discover time end, format: yyyyMMdd, e.g. 20251231' required: false example: '20251231' schema: type: string - name: fullManagedFlag in: query description: Full managed flag. 0 - No, 1 - Yes required: false example: 0 schema: type: integer enum: - 0 - 1 - name: sellerTypes in: query description: >- Seller type list, multiple values allowed, e.g. sellerTypes=LOCAL_SHOP&sellerTypes=CROSS_BORDER required: false example: '' schema: type: array items: type: string - name: commissionRateBegin in: query description: Commission rate lower bound (e.g. 0.05 means 5%) required: false example: 0 schema: type: number - name: commissionRateEnd in: query description: Commission rate upper bound required: false example: 0 schema: type: number - name: sortField in: query description: >- Sort field. Enum: periodSoldCount, periodGmv, periodSoldCountGrowthRate, periodGmvGrowthRate, periodAvgPrice, commissionRate, discoverTime, creatorSoldCountRate, soldCountTotal, gmvTotal required: false example: periodSoldCount schema: type: string enum: - periodSoldCount - periodGmv - periodSoldCountGrowthRate - periodGmvGrowthRate - periodAvgPrice - commissionRate - discoverTime - creatorSoldCountRate - soldCountTotal - gmvTotal - name: sortType in: query description: 'Sort direction. Enum: desc, asc' required: false example: desc schema: type: string enum: - desc - asc - name: gmvBegin in: query description: Period GMV lower bound (local currency) required: false example: 0 schema: type: number - name: gmvEnd in: query description: Period GMV upper bound (local currency) required: false example: 0 schema: type: number - name: gmvGrowthRateBegin in: query description: Period GMV growth rate lower bound (e.g. 0.1 means 10%) required: false example: 0 schema: type: number - name: gmvGrowthRateEnd in: query description: Period GMV growth rate upper bound required: false example: 0 schema: type: number - name: soldCountBegin in: query description: Period sold count lower bound required: false example: 0 schema: type: integer - name: soldCountEnd in: query description: Period sold count upper bound required: false example: 0 schema: type: integer - name: creatorTotalBegin in: query description: Period related creator count lower bound required: false example: 0 schema: type: integer - name: creatorTotalEnd in: query description: Period related creator count upper bound required: false example: 0 schema: type: integer - name: creatorSoldCountRateBegin in: query description: Period creator conversion rate lower bound (e.g. 0.1 means 10%) required: false example: 0 schema: type: number - name: creatorSoldCountRateEnd in: query description: Period creator conversion rate upper bound required: false example: 0 schema: type: number - name: primarySaleMode in: query description: 'Primary sales mode in the period. Enum: video, live, other' required: false example: '' schema: type: string enum: - video - live - other - name: primarySaleChannel in: query description: >- Primary sales channel in the period. Enum: mainCreator, nonMainCreator, other required: false example: '' schema: type: string enum: - mainCreator - nonMainCreator - other - name: pageNo in: query description: Page number, default 1, minimum 1 required: false example: 1 schema: type: integer - name: pageSize in: query description: Page size, default 10, minimum 1, maximum 3000 required: false example: 10 schema: type: integer - name: valid in: query description: The item for sale, 0-Delisted, 1-On sale required: false schema: type: integer enum: - 0 - 1 - name: x-appKey in: header description: App key required: false example: '{{appKey}}' schema: type: string - name: x-timestamp in: header description: Timestamp required: false example: '{{x-timestamp}}' schema: type: string - name: x-sign in: header description: Signature required: false example: '{{x-sign}}' schema: type: string - name: x-selected-lng in: header description: >- Category language and timezone. Category names follow this language. discoverTime and Top 3 video times are shifted from the stored UTC+8 wall clock to this timezone. The discover-date filter is converted from the user's local day back to UTC+8 before querying. zh-CN does not shift; ja-JP adds 1 hour to returned times. Values: zh-CN, en, id-ID, ms-MY, fil-PH, th-TH, vi-VN, ja-JP. See GET /api/meta/language. required: false example: ja-JP schema: type: string enum: - zh-CN - en - id-ID - ms-MY - fil-PH - th-TH - vi-VN - ja-JP responses: '200': description: '' content: json: schema: type: object properties: code: type: string description: Response code examples: - '200' message: type: string description: Response message examples: - Success! result: type: object description: Response data properties: total: type: integer title: Total records pageNo: type: integer title: Current page number pageSize: type: integer title: Page size data: type: array title: Item list items: type: object properties: itemId: type: string title: Item ID itemName: type: string title: Item name region: type: string title: Country/region categoryId: type: string title: Category ID categoryName: type: string title: Category name tkCategoryLv1Id: type: string title: TK Level-1 Category ID tkCategoryLv1Name: type: string title: TK Level-1 Category name tkCategoryLv2Id: type: string title: TK Level-2 Category ID tkCategoryLv2Name: type: string title: TK Level-2 Category name tkCategoryLv3Id: type: string title: TK Level-3 Category ID tkCategoryLv3Name: type: string title: TK Level-3 Category name itemPicUrl: type: string title: Item image URL priceList: type: array title: Price list items: type: object properties: local: type: number title: Local currency amount region: type: number title: USD amount required: - local - region x-apifox-orders: - local - region currencySymbolInfo: type: object title: Currency symbol information properties: local: type: string title: Local currency symbol region: type: string title: USD symbol required: - local - region x-apifox-orders: - local - region period: type: string title: >- Requested period, consistent with the input parameter periodGmv: type: object title: Period GMV properties: local: type: number title: Local currency amount region: type: number title: USD amount required: - local - region x-apifox-orders: - local - region periodGmvGrowthRate: type: number title: Period GMV growth rate periodSoldCount: type: integer title: Period sold count periodSoldGrowthRate: type: number title: Period sold count growth rate periodAvgPrice: type: object title: Period average selling price properties: local: type: number title: Local currency amount region: type: number title: USD amount required: - local - region x-apifox-orders: - local - region periodCreatorSoldCountRate: type: number title: Period creator conversion rate top3VideoList: type: array title: Top 3 best-selling videos in the period items: type: object properties: video_id: type: string title: Video ID video_title: type: string title: Video title discover_time: type: string title: >- Video discover time, format: yyyy-MM-dd HH:mm:ss create_time: type: string title: >- Video create time, format: yyyy-MM-dd HH:mm:ss update_time: type: string title: >- Video update time, format: yyyy-MM-dd HH:mm:ss duration: type: integer title: Video duration (in milliseconds) video_sold_count: type: number title: Video sold count rn: type: integer title: Rank, 1-3 videoCoverUrl: type: string title: Video cover URL tkVideoUrl: type: string title: TikTok video play URL playCountTotal: type: integer x-apifox-orders: - video_id - video_title - discover_time - create_time - update_time - duration - video_sold_count - rn - videoCoverUrl - tkVideoUrl - playCountTotal gmvTotal: type: object title: Historical total GMV properties: local: type: number title: Local currency amount region: type: number title: USD amount required: - local - region x-apifox-orders: - local - region soldCountTotal: type: integer title: Historical total sold count commissionRate: type: number title: Commission rate fullManagedFlag: type: integer title: Full managed flag. 0 - No, 1 - Yes sellerId: type: string title: Seller ID sellerName: type: string title: Seller name shopLogoUrl: type: string title: Seller logo URL sellerSoldCountTotal: type: integer title: Seller historical total sold count sellerGmvTotal: type: object title: Seller historical total GMV properties: local: type: number title: Local currency amount region: type: number title: USD amount required: - local - region x-apifox-orders: - local - region sellerType: type: string title: Seller type discoverTime: type: string title: 'Item discover time, format: yyyy-MM-dd HH:mm:ss' relatedVideoCount: type: integer title: Related video count relatedCreatorCount: type: integer title: Related creator count valid: type: integer title: Valid flag. 0 - Invalid, 1 - Valid x-apifox-orders: - itemId - itemName - region - categoryId - categoryName - tkCategoryLv1Id - tkCategoryLv1Name - tkCategoryLv2Id - tkCategoryLv2Name - tkCategoryLv3Id - tkCategoryLv3Name - itemPicUrl - priceList - currencySymbolInfo - period - periodGmv - periodGmvGrowthRate - periodSoldCount - periodSoldGrowthRate - periodAvgPrice - periodCreatorSoldCountRate - top3VideoList - gmvTotal - soldCountTotal - commissionRate - fullManagedFlag - sellerId - sellerName - shopLogoUrl - sellerSoldCountTotal - sellerGmvTotal - sellerType - discoverTime - relatedVideoCount - relatedCreatorCount - valid required: - total - pageNo - pageSize - data x-apifox-orders: - total - pageNo - pageSize - data serverTime: type: string description: Server response time examples: - '2026-02-05 10:53:25' required: - code - message - result - serverTime x-apifox-orders: - code - message - result - serverTime headers: {} x-apifox-name: Success x-200:Parameter Error: description: '' content: application/json: schema: type: object properties: code: type: string title: Response Code message: type: string title: Response Message result: type: 'null' title: Result serverTime: type: string title: Server Time required: - code - message - result - serverTime x-apifox-orders: - code - message - result - serverTime example: code: '4400' message: Invalid request parameters result: null serverTime: '2026-09-22 15:30:00' headers: {} x-apifox-name: Parameter Error x-200:Signature Error: description: '' content: application/json: schema: type: object properties: code: type: string title: Response Code message: type: string title: Response Message result: type: 'null' title: Result serverTime: type: string title: Server Time required: - code - message - result - serverTime x-apifox-orders: - code - message - result - serverTime examples: '2': summary: Signature does not match value: code: '4205' message: Signature does not match result: null serverTime: '2026-09-22 15:30:00' '3': summary: Missing signature headers value: code: '4202' message: Missing signature headers result: null serverTime: '2026-09-22 15:30:00' headers: {} x-apifox-name: Signature Error x-200:Server Error: description: '' content: application/json: schema: type: object properties: code: type: string title: Response Code message: type: string title: Response Message result: type: 'null' title: Result serverTime: type: string title: Server Time required: - code - message - result - serverTime x-apifox-orders: - code - message - result - serverTime examples: '4': summary: Server is busy value: code: '5003' message: Server is busy, please try again later result: null serverTime: '2026-09-22 15:30:00' '5': summary: Internal server error value: code: '5000' message: Internal server error result: null serverTime: '2026-09-22 15:30:00' headers: {} x-apifox-name: Server Error security: [] x-apifox-folder: Data APIs/Item x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/6636689/apis/api-429410270-run components: schemas: {} securitySchemes: {} servers: - url: http://open.tabcut.com:8090 description: 正式环境 security: [] ```