---
openapi: 3.0.0
info:
  title: Target Product API
  version: 1.0.0
  description: The Target Product API returns a Target product as JSON. The product
    comes with its title, brand, images and videos, price and promotions, variants,
    specifications, return policy and protection plans, its rating with recent reviews,
    and its availability for shipping, pickup, same-day delivery and in store.
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Target Product API
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use.
        schema:
          type: string
          enum:
          - "target_product"
      - name: product_id
        in: query
        required: true
        description: Target product to retrieve by its TCIN, a number of up to 12
          digits with no leading zero. Take it from the product_id of a Target Search
          result or of an entry in variants. The ID of a variation family returns
          the family with every product in it.
        schema:
          type: string
          pattern: "^[1-9][0-9]{0,11}$"
      - name: store_id
        in: query
        required: false
        description: Target store whose prices and availability are returned. The
          ID is the number at the end of a store's page address on target.com, such
          as 1771 in /sl/cedar-rapids-south/1771. A number from 1 to 9999 with no
          leading zeros. Without it, prices use online store 3991 and availability
          uses store 1771.
        schema:
          type: string
          pattern: "^[1-9][0-9]{0,3}$"
      - name: postal_code
        in: query
        required: false
        description: Five-digit US ZIP code that shipping dates and delivery availability
          are worked out for, excluding 00000.
        schema:
          type: string
          pattern: "^(?!00000)[0-9]{5}$"
      - name: zero_retention
        in: query
        required: false
        description: Disable persistent request and response storage for Enterprise
          accounts.
        schema:
          type: boolean
      responses:
        '200':
          description: Search completed. The response may contain an error explaining
            an empty result.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Missing or invalid API credentials.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '403':
          description: Account cannot use the requested feature.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: Account usage or rate limit reached.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Target results could not be retrieved.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchMetadata:
      type: object
      required:
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Target URL for this request.
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    SearchParameters:
      type: object
      properties:
        product_id:
          type: string
          pattern: "^[1-9][0-9]{0,11}$"
          description: Target product to retrieve by its TCIN, a number of up to 12
            digits with no leading zero. Take it from the product_id of a Target Search
            result or of an entry in variants. The ID of a variation family returns
            the family with every product in it.
        store_id:
          type: string
          pattern: "^[1-9][0-9]{0,3}$"
          description: Target store whose prices and availability are returned. The
            ID is the number at the end of a store's page address on target.com, such
            as 1771 in /sl/cedar-rapids-south/1771. A number from 1 to 9999 with no
            leading zeros. Without it, prices use online store 3991 and availability
            uses store 1771.
        postal_code:
          type: string
          pattern: "^(?!00000)[0-9]{5}$"
          description: Five-digit US ZIP code that shipping dates and delivery availability
            are worked out for, excluding 00000.
        engine:
          type: string
          enum:
          - "target_product"
        zero_retention:
          type: boolean
          description: Whether persistent request and response storage is disabled.
    SearchResponse:
      type: object
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        search_information:
          type: object
          properties:
            store_id:
              type: string
              description: Store ID used for availability.
            store_name:
              type: string
              description: Name of the store used for availability.
          description: Query and store information returned by Target.
        product:
          type: object
          properties:
            product_id:
              type: string
              description: Target TCIN identifying the returned product.
            title:
              type: string
              description: Title of the product.
            link:
              type: string
              description: URL of the product page on Target.
            brand:
              type: string
              description: Brand name of the product.
            brand_id:
              type: string
              description: Target identifier for the product brand.
            category_id:
              type: string
              description: Target category ID usable with the category_id parameter
                of Target Search.
            dpci:
              type: string
              description: Target department, class, and item identifier.
            upc:
              type: string
              description: Universal Product Code for the selected product.
            origin:
              type: string
              description: Where the product was made, as Target lists it, such as Made
                in the USA or Imported.
            item_type:
              type: string
              description: Kind of product as Target classifies it, such as Blenders.
            classification:
              type: object
              properties:
                department:
                  type: string
                  description: Name of the Target department.
                department_id:
                  type: string
                  description: Target identifier for the department.
                class_id:
                  type: string
                  description: Target identifier for the class within the department.
              description: Target merchandise department and class of the product.
            thumbnail:
              type: string
              description: URL of the primary image.
            images:
              type: array
              items:
                type: string
              description: URLs of additional product images.
            videos:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Title of the video.
                  link:
                    type: string
                    description: URL of the video file.
                  thumbnail:
                    type: string
                    description: URL of the poster image of the video.
                  length_seconds:
                    type: integer
                    description: Video duration in seconds.
                required:
                - link
              description: Videos Target shows for the product.
            price:
              type: string
              description: Formatted current price in US dollars.
            extracted_price:
              type: number
              description: Current price in US dollars.
            original_price:
              type: string
              description: Formatted regular comparison price.
            extracted_original_price:
              type: number
              description: Regular comparison price in US dollars.
            discount:
              type: number
              description: Amount saved against the regular comparison price, in
                US dollars.
            discount_percentage:
              type: integer
              description: Percentage saved against the regular comparison price.
            tag:
              type: string
              description: Pricing label on the current price, one of Sale or Clearance.
            price_note:
              type: string
              description: Target's note about when the current price ends.
              example: Ends Saturday
            price_label:
              type: string
              description: Condition Target shows with the current price, such as When
                purchased online.
            promotions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Target identifier for the offer.
                  text:
                    type: string
                    description: Offer message as Target displays it.
                  reward_type:
                    type: string
                    description: Kind of reward the offer gives, such as NoDiscount,
                      PercentageOff or FixedPrice.
                  reward_value:
                    type: number
                    description: Size of the reward, a percentage for PercentageOff
                      and a dollar price for FixedPrice.
                  threshold_type:
                    type: string
                    description: Kind of condition for earning the reward, such as
                      none or quantity.
                  threshold_value:
                    type: number
                    description: Number of items a shopper must buy to earn the reward.
                  channel:
                    type: string
                    description: Where the offer applies, such as online_and_store
                      or online_only.
                  link:
                    type: string
                    description: URL of the Target page listing the items the offer
                      applies to.
                required:
                - id
              description: Offers eligible for the returned product.
            protection_plans:
              type: array
              items:
                type: object
                properties:
                  product_id:
                    type: string
                    description: Target TCIN of the protection plan.
                  title:
                    type: string
                    description: Name of the protection plan.
                  price:
                    type: string
                    description: Formatted current price in US dollars.
                  extracted_price:
                    type: number
                    description: Current price in US dollars.
                required:
                - product_id
              description: Protection plans Target offers with the product.
            financing_options:
              type: array
              items:
                type: object
                properties:
                  provider:
                    type: string
                    description: Company providing the plan, such as Affirm.
                  installments:
                    type: integer
                    description: Number of payments in the plan.
                  duration:
                    type: string
                    description: Length of the plan, such as 8 weeks or 12 months.
                  cost_per_installment:
                    type: string
                    description: Formatted amount of each payment in US dollars.
                  extracted_cost_per_installment:
                    type: number
                    description: Amount of each payment in US dollars.
                  rate:
                    type: number
                    description: Annual percentage rate of the plan.
                  total_cost:
                    type: number
                    description: Total paid over the plan in US dollars, interest
                      included.
                required:
                - installments
                - cost_per_installment
                - extracted_cost_per_installment
              description: Pay-over-time plans offered for the product at its current
                price.
            rating:
              type: number
              description: Average customer rating on a five-star scale.
            reviews:
              type: integer
              description: Number of customer ratings.
            reviews_with_text:
              type: integer
              description: Number of customer ratings that come with a written review.
            reviews_histogram:
              type: object
              properties:
                '1':
                  type: integer
                  description: Number of customer ratings with 1 star.
                '2':
                  type: integer
                  description: Number of customer ratings with 2 stars.
                '3':
                  type: integer
                  description: Number of customer ratings with 3 stars.
                '4':
                  type: integer
                  description: Number of customer ratings with 4 stars.
                '5':
                  type: integer
                  description: Number of customer ratings with 5 stars.
              description: Rating counts indexed by star value.
            secondary_ratings:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Aspect of the product customers rated, such as value
                      or ease of use.
                  rating:
                    type: number
                    description: Average customer rating of that aspect on a five-star
                      scale.
                required:
                - name
                - rating
              description: Average customer ratings of individual aspects of the product.
            fit_ratings:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Fit aspect customers rated, such as sizing or width.
                  text:
                    type: string
                    description: Target's wording for customers' fit answers, such as
                      true to size.
                  rating:
                    type: number
                    description: Average customer answer on Target's 3-point fit scale.
                required:
                - name
                - rating
              description: Customers' fit ratings of the product, such as sizing.
            recommended_percentage:
              type: integer
              description: Percentage of customer votes recommending the product.
            questions_count:
              type: integer
              description: Number of customer questions about the product.
            loved_for:
              type: string
              description: Review highlights reported by Target.
            badges:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                    description: Target code for the badge, such as highly_rated,
                      low_returns, bestseller, new_at_target or only_at_target.
                  text:
                    type: string
                    description: Badge label as Target displays it, such as Highly
                      rated.
                required:
                - key
                - text
              description: Badges Target shows on the product.
            release_date:
              type: string
              description: Release date Target lists for the product, in YYYY-MM-DD
                format.
            description:
              type: string
              description: Product description as plain text.
            highlights:
              type: array
              items:
                type: string
              description: Highlight bullet points Target lists for the product.
            specifications:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the specification, such as Weight.
                  value:
                    type: string
                    description: Value of the specification.
                required:
                - name
                - value
              description: Specifications Target lists for the product.
            attributes:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the attribute group, such as Wireless Technology.
                  value:
                    type: string
                    description: Attribute value, such as Bluetooth or Gluten Free.
                required:
                - value
              description: Product features and standards Target lists, such as dietary
                or certification attributes.
            dimensions:
              type: object
              properties:
                depth:
                  type: string
                  description: Package depth with its unit, such as 5.86 inches.
                height:
                  type: string
                  description: Package height with its unit.
                width:
                  type: string
                  description: Package width with its unit.
                weight:
                  type: string
                  description: Package weight with its unit, such as 0.15 pounds.
              description: Dimensions and weight of the product's shipping package.
            categories:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Name of the category.
                  category_id:
                    type: string
                    description: Target category ID usable with the category_id parameter
                      of Target Search.
                  link:
                    type: string
                    description: URL of the category page on Target.
                required:
                - category_id
              description: Category path of the product, from the broadest category
                to the most specific.
            max_quantity:
              type: integer
              description: Maximum purchase quantity reported by Target.
            return_policy:
              type: object
              properties:
                text:
                  type: string
                  description: Return policy message Target shows for the product.
                method:
                  type: string
                  description: Target’s return-method restrictions.
                window_days:
                  type: integer
                  description: Return window in days for regular guests.
                link:
                  type: string
                  description: URL of the return policy page on Target.
              description: Return terms for the selected product.
            fulfillment:
              type: object
              properties:
                shipping:
                  type: object
                  properties:
                    availability:
                      type: string
                      description: Shipping status reported by Target, such as IN_STOCK,
                        OUT_OF_STOCK, UNAVAILABLE or PRE_ORDER_SELLABLE.
                    expected_date:
                      type: string
                      description: Latest expected delivery date supplied by Target,
                        in YYYY-MM-DD format.
                    start_date:
                      type: string
                      description: Earliest expected delivery date supplied by Target,
                        in YYYY-MM-DD format.
                    order_cutoff:
                      type: string
                      description: Time by which an order must be placed for these delivery
                        dates, as an ISO 8601 timestamp.
                    text:
                      type: string
                      description: Shipping speed as Target displays it, such as 2-day
                        shipping.
                    stock:
                      type: integer
                      description: Number of units Target reports as available for
                        this fulfillment method.
                  required:
                  - availability
                  description: Availability of shipping to an address.
                pickup:
                  type: object
                  properties:
                    availability:
                      type: string
                      description: Order pickup status reported by Target, such as
                        IN_STOCK, OUT_OF_STOCK or UNAVAILABLE.
                    expected_date:
                      type: string
                      description: Expected pickup or delivery date supplied by Target.
                  required:
                  - availability
                  description: Availability of order pickup at the store.
                delivery:
                  type: object
                  properties:
                    availability:
                      type: string
                      description: Same-day delivery status reported by Target, one
                        of IN_STOCK, OUT_OF_STOCK or UNAVAILABLE.
                    stock:
                      type: integer
                      description: Number of units Target reports as available for
                        this fulfillment method.
                  required:
                  - availability
                  description: Availability of same-day delivery from the store.
                in_store:
                  type: object
                  properties:
                    availability:
                      type: string
                      description: In-store status reported by Target, such as IN_STOCK,
                        LIMITED_STOCK, OUT_OF_STOCK, NOT_SOLD_IN_STORE, DISCONTINUED
                        or UNAVAILABLE.
                    stock:
                      type: integer
                      description: Number of units Target reports as available for
                        this fulfillment method.
                  required:
                  - availability
                  description: Availability on the shelves of the store.
                digital_delivery:
                  type: object
                  properties:
                    availability:
                      type: string
                      description: Digital delivery status reported by Target, such
                        as IN_STOCK.
                  required:
                  - availability
                  description: Availability of digital delivery for items such as
                    gift cards and game codes.
              description: Availability by fulfillment method.
            aisle:
              type: string
              description: Aisle where the store named in search_information shelves
                the product, such as D21.
            is_free_shipping:
              type: boolean
              description: Whether Target advertises free shipping.
            variants:
              type: array
              items:
                type: object
                properties:
                  option_type:
                    type: string
                    description: Variation dimension such as color or size.
                  product_id:
                    type: string
                    description: Target TCIN of the product this option value selects.
                  title:
                    type: string
                    description: Option value, such as a color name or a size.
                  link:
                    type: string
                    description: URL of the Target page for the product this option
                      value selects.
                  thumbnail:
                    type: string
                    description: URL of the primary image of the product this option
                      value selects.
                  swatch_thumbnail:
                    type: string
                    description: URL of the variation swatch image.
                  is_selected:
                    type: boolean
                    description: Whether the requested product has this option value.
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        product_id:
                          type: string
                          description: Target TCIN of a product with this option value.
                        link:
                          type: string
                          description: URL of the Target page for that product.
                        price:
                          type: string
                          description: Formatted current price of that product.
                        extracted_price:
                          type: number
                          description: Current price of that product in US dollars.
                        is_price_hidden:
                          type: boolean
                          description: Whether Target requires viewing that product's
                            price in the cart.
                        is_out_of_stock:
                          type: boolean
                          description: Whether every fulfillment method is unavailable
                            for that product.
                        is_discontinued:
                          type: boolean
                          description: Whether Target marks that product or its family
                            as obsolete.
                      required:
                      - product_id
                      - link
                    description: Every product in the family with this option value.
                required:
                - product_id
                - link
                - products
              description: One entry per option value of the product family, with
                the products that have it.
            price_range:
              type: object
              properties:
                text:
                  type: string
                  description: Displayed price range, such as $9.99 - $99.99.
                from:
                  type: string
                  description: Formatted lower price bound.
                to:
                  type: string
                  description: Formatted upper price bound.
                extracted_from_price:
                  type: number
                  description: Lower price bound in US dollars.
                extracted_to_price:
                  type: number
                  description: Upper price bound in US dollars.
              required:
              - text
              - from
              - to
              - extracted_from_price
              - extracted_to_price
              description: Price range across the product family.
            parent_product_id:
              type: string
              description: Target TCIN identifying the variation family.
            recent_sales:
              type: string
              description: Target’s recent purchase activity label.
            extracted_recent_sales:
              type: integer
              description: Approximate purchase count expanded from the abbreviated
                recent-sales label.
            seller:
              type: object
              properties:
                id:
                  type: string
                  description: Target identifier for the seller.
                name:
                  type: string
                  description: Name of the seller.
                link:
                  type: string
                  description: URL of the seller's page on Target.
              required:
              - name
              description: Seller Target names for the product.
            is_marketplace:
              type: boolean
              description: Whether a Target Plus partner sells the product.
            is_out_of_stock:
              type: boolean
              description: Whether every fulfillment method is unavailable.
            is_out_of_stock_in_all_stores:
              type: boolean
              description: Whether Target reports the product out of stock at every
                store.
            unit_price:
              type: string
              description: Formatted price per unit.
            extracted_unit_price:
              type: number
              description: Price per unit in US dollars.
            ingredients:
              type: string
              description: Ingredient list of the product.
            nutrition_facts:
              type: object
              properties:
                serving_size:
                  type: string
                  description: Serving size with its unit, such as 1 cup.
                serving_description:
                  type: string
                  description: Serving the values are given for as Target describes
                    it, such as per serving (1 cup).
                servings_per_container:
                  type: string
                  description: Number of servings in the package, such as 8 or About
                    13.
                nutrients:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the nutrient, such as Total Fat.
                      quantity:
                        type: number
                        description: Amount of the nutrient per serving.
                      unit:
                        type: string
                        description: Unit of the amount, such as g or mg.
                      daily_value_percentage:
                        type: number
                        description: Percentage of the daily value one serving provides.
                    required:
                    - name
                  description: Nutrients listed on the Nutrition Facts label, per serving.
              description: Nutrition Facts label of the product.
            warnings:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                    description: Code for the warning, such as choking_hazard_small_parts,
                      prop65 or label_warning for the allergen or caution statement
                      on the product's label.
                  value:
                    type: string
                    description: Warning text as Target displays it.
                required:
                - key
              description: Safety and compliance warnings Target shows for the product.
            is_snap_eligible:
              type: boolean
              description: Whether the product is eligible for SNAP benefits.
            is_discontinued:
              type: boolean
              description: Whether Target marks the product or its family as obsolete.
            is_add_on:
              type: boolean
              description: Whether Target marks the product as an add-on item.
            is_price_hidden:
              type: boolean
              description: Whether Target requires viewing the price in the cart.
          required:
          - product_id
          description: Details of the requested product.
        is_partial:
          type: boolean
          description: Whether is_snap_eligible, loved_for, attribute names and the
            AI review summary could not be retrieved for this response.
        review_results:
          type: object
          properties:
            reviews:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Target identifier for the review.
                  text:
                    type: string
                    description: Body of the review.
                  rating:
                    type: integer
                    description: Star rating the reviewer gave, from 1 to 5.
                  iso_date:
                    type: string
                    description: Review publication timestamp.
                  author:
                    type: string
                    description: Display name of the reviewer.
                  title:
                    type: string
                    description: Headline of the review.
                required:
                - id
                - text
                - rating
                - iso_date
              description: Customer review snippets supplied by Target.
            images:
              type: array
              items:
                type: string
              description: URLs of photos customers added to their reviews.
            ai_summary:
              type: object
              properties:
                title:
                  type: string
                  description: Heading Target shows above the summary, such as Guests
                    are saying.
                summary:
                  type: string
                  description: Summary of customer reviews generated by Target.
                pros:
                  type: array
                  items:
                    type: string
                  description: Strengths customers mention, as Target lists them.
                cons:
                  type: array
                  items:
                    type: string
                  description: Weaknesses customers mention, as Target lists them.
                sentiment:
                  type: string
                  description: Overall tone of the reviews, such as positive, mixed
                    or negative.
              required:
              - summary
              description: Target’s generated review summary.
          description: Review snippets and available review summary.
        error:
          type: string
          description: Explanation of an empty result or an unsuccessful request.
