---
openapi: 3.0.0
info:
  title: Target Search API
  version: 1.0.0
  description: The Target Search API returns Target's search results as JSON. Each
    product comes with its title, brand, price and promotions, rating and reviews,
    badges, variants, and its availability for shipping, pickup, same-day delivery
    and in store. The response also carries Target's filters, popular filters, related
    searches and pagination, and on a category page the category path in `categories`.
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Target Search API
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use.
        schema:
          type: string
          enum:
          - "target_search"
      - name: q
        in: query
        required: false
        description: Search query of up to 128 characters. Supply q or category_id.
        schema:
          type: string
          maxLength: 128
      - name: category_id
        in: query
        required: false
        description: Category identifier from filters[].options[].category_id. Supply
          category_id or q. The response also carries the category's path in categories.
        schema:
          type: string
          pattern: "^[0-9a-z]{1,12}$"
      - 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: sort_by
        in: query
        required: false
        description: Result order. best_match requires q. Target uses its own ordering
          when this parameter is omitted.
        schema:
          type: string
          enum:
          - "best_match"
          - "featured"
          - "price_low_to_high"
          - "price_high_to_low"
          - "rating_high_to_low"
          - "best_seller"
          - "new_arrivals"
      - name: filters
        in: query
        required: false
        description: Up to 40 comma-separated refinement tokens from filters[].options[].filters
          or popular_filters[].filters. Each token contains 1 to 12 lowercase letters
          or digits.
        schema:
          type: string
          pattern: "^[0-9a-z]{1,12}(,[0-9a-z]{1,12})*$"
      - name: price_min
        in: query
        required: false
        description: Minimum price in US dollars from 0 to 1000000 with up to two
          decimal places, such as 20 or 19.99. An omitted upper bound becomes 1000000.
        schema:
          type: string
          pattern: "^([0-9]{1,6}(\\.[0-9]{1,2})?|1000000(\\.0{1,2})?)$"
      - name: price_max
        in: query
        required: false
        description: Maximum price in US dollars from 0 to 1000000 with up to two
          decimal places, greater than or equal to price_min. An omitted lower bound
          becomes zero.
        schema:
          type: string
          pattern: "^([0-9]{1,6}(\\.[0-9]{1,2})?|1000000(\\.0{1,2})?)$"
      - name: page
        in: query
        required: false
        description: Page number from 1 to 50. Target shows the first page when it
          is omitted.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - name: nfpr
        in: query
        required: false
        description: Set to 1 to disable Target spelling correction.
        schema:
          type: string
          enum:
          - "0"
          - "1"
      - 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:
        q:
          type: string
          maxLength: 128
          description: Search query of up to 128 characters. Supply q or category_id.
        category_id:
          type: string
          pattern: "^[0-9a-z]{1,12}$"
          description: Category identifier from filters[].options[].category_id. Supply
            category_id or q. The response also carries the category's path in categories.
        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.
        sort_by:
          type: string
          enum:
          - "best_match"
          - "featured"
          - "price_low_to_high"
          - "price_high_to_low"
          - "rating_high_to_low"
          - "best_seller"
          - "new_arrivals"
          description: Result order. best_match requires q. Target uses its own ordering
            when this parameter is omitted.
        filters:
          type: string
          description: Up to 40 comma-separated refinement tokens from filters[].options[].filters
            or popular_filters[].filters. Each token contains 1 to 12 lowercase letters
            or digits.
        price_min:
          type: string
          pattern: "^([0-9]{1,6}(\\.[0-9]{1,2})?|1000000(\\.0{1,2})?)$"
          description: Minimum price in US dollars from 0 to 1000000 with up to two
            decimal places, such as 20 or 19.99. An omitted upper bound becomes 1000000.
        price_max:
          type: string
          pattern: "^([0-9]{1,6}(\\.[0-9]{1,2})?|1000000(\\.0{1,2})?)$"
          description: Maximum price in US dollars from 0 to 1000000 with up to two
            decimal places, greater than or equal to price_min. An omitted lower bound
            becomes zero.
        page:
          type: string
          description: Page number from 1 to 50.
        nfpr:
          type: string
          enum:
          - "0"
          - "1"
          description: Set to 1 to disable Target spelling correction.
        engine:
          type: string
          enum:
          - "target_search"
        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:
            total_results:
              type: integer
              description: Total result count reported by Target.
            query_displayed:
              type: string
              description: Search query displayed by Target.
            store_id:
              type: string
              description: Store ID used for availability.
            store_name:
              type: string
              description: Name of the store used for availability.
            filters_applied:
              type: array
              items:
                type: string
              description: Labels of refinements applied by Target.
            did_you_mean:
              type: string
              description: Suggested correction to the search query.
            showing_results_for:
              type: string
              description: Query Target searched instead after correcting the spelling
                of the one sent.
            is_partial:
              type: boolean
              description: Whether Target's popular filters could not be retrieved
                for this response.
          description: Query and store information returned by Target.
        organic_results:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
                description: One-based position on the current results page.
              product_id:
                type: string
                description: Target TCIN identifying the returned product.
              parent_product_id:
                type: string
                description: Target TCIN identifying the variation family.
              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 identifier accepted by category_id.
              thumbnail:
                type: string
                description: URL of the primary image.
              images:
                type: array
                items:
                  type: string
                description: URLs of additional product images.
              price:
                type: string
                description: Formatted current price in US dollars.
              extracted_price:
                type: number
                description: Current price in US dollars.
              price_range:
                type: object
                required:
                - text
                - from
                - to
                - extracted_from_price
                - extracted_to_price
                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.
                description: Price range across the product family.
              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.
              rating:
                type: number
                description: Average customer rating on a five-star scale.
              reviews:
                type: integer
                description: Number of customer ratings.
              loved_for:
                type: string
                description: Review highlights reported by Target.
              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.
                description: Target’s generated review summary.
              is_sponsored:
                type: boolean
                description: Whether Target identifies the listing as sponsored.
              dpci:
                type: string
                description: Target department, class, and item identifier.
              item_type:
                type: string
                description: Kind of product as Target classifies it, such as Blenders.
              classification:
                type: object
                properties:
                  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.
              badges:
                type: array
                items:
                  type: object
                  required:
                  - key
                  - text
                  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.
                description: Badges Target shows on the product.
              variants:
                type: array
                items:
                  type: object
                  required:
                  - product_id
                  - link
                  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.
                description: Variation options with product IDs for detail requests.
              fulfillment:
                type: object
                properties:
                  shipping:
                    type: object
                    required:
                    - availability
                    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.
                    description: Availability of shipping to an address.
                  pickup:
                    type: object
                    required:
                    - availability
                    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.
                    description: Availability of order pickup at the store.
                  delivery:
                    type: object
                    required:
                    - availability
                    properties:
                      availability:
                        type: string
                        description: Same-day delivery status reported by Target,
                          such as IN_STOCK, OUT_OF_STOCK or UNAVAILABLE.
                      stock:
                        type: integer
                        description: Number of units Target reports as available
                          for this fulfillment method.
                    description: Availability of same-day delivery from the store.
                  in_store:
                    type: object
                    required:
                    - availability
                    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.
                    description: Availability on the shelves of the store.
                  digital_delivery:
                    type: object
                    required:
                    - availability
                    properties:
                      availability:
                        type: string
                        description: Digital delivery status reported by Target, such
                          as IN_STOCK.
                    description: Availability of digital delivery for items such as
                      gift cards and game codes.
                description: Availability by fulfillment method.
              seller:
                type: object
                required:
                - name
                properties:
                  id:
                    type: string
                    description: Target identifier for the seller.
                  name:
                    type: string
                    description: Name of the seller.
                description: Seller Target names for the product.
              is_marketplace:
                type: boolean
                description: Whether a Target Plus partner sells the product.
              is_free_shipping:
                type: boolean
                description: Whether Target advertises free shipping.
              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.
              is_add_on:
                type: boolean
                description: Whether Target marks the product as an add-on item.
              release_date:
                type: string
                description: Release date Target lists for the product, in YYYY-MM-DD
                  format.
              attributes:
                type: array
                items:
                  type: object
                  required:
                  - value
                  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.
                description: Product features and standards Target lists, such as dietary
                  or certification attributes.
              promotions:
                type: array
                items:
                  type: object
                  required:
                  - id
                  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.
                description: Offers eligible for the returned product.
              is_out_of_stock:
                type: boolean
                description: Whether every supplied 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.
              is_snap_eligible:
                type: boolean
                description: Whether the product is eligible for SNAP benefits.
              is_price_hidden:
                type: boolean
                description: Whether Target requires viewing the price in the cart.
            required:
            - position
            - product_id
          description: Product listings including any sponsored products identified
            by is_sponsored.
        filters:
          type: array
          items:
            type: object
            required:
            - options
            properties:
              type:
                type: string
                description: Name of the refinement group, such as Brand, Category
                  or Price.
              options:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: Label of the option as Target displays it.
                    filters:
                      type: string
                      description: Refinement token accepted by the filters parameter.
                    link:
                      type: string
                      description: Target website URL applying this unselected refinement.
                    thumbnail:
                      type: string
                      description: URL of the image Target shows for the option.
                    category_id:
                      type: string
                      description: Target category identifier accepted by category_id.
                    is_selected:
                      type: boolean
                      description: Whether Target applied this refinement.
                description: Options available within the group.
          description: Available refinement groups.
        pagination:
          type: object
          required:
          - current
          properties:
            current:
              type: integer
              description: Current page number.
            next:
              type: string
              description: Target website URL for the next page.
            other_pages:
              type: object
              additionalProperties:
                type: string
              description: Target website URLs indexed by page number.
            previous:
              type: string
              description: Target website URL for the previous page.
          description: Current page number and Target website URLs for other pages.
        popular_filters:
          type: array
          items:
            type: object
            required:
            - text
            properties:
              text:
                type: string
                description: Label of the suggested refinement as Target displays
                  it.
              filters:
                type: string
                description: Refinement token accepted by the filters parameter.
              thumbnail:
                type: string
                description: URL of the image Target shows for the suggestion.
              link:
                type: string
                description: Target website URL of the search this suggestion opens.
          description: Suggested refinements from Target’s search page.
        related_searches:
          type: array
          items:
            type: object
            required:
            - query
            - link
            properties:
              query:
                type: string
                description: Search query Target suggests as related.
              link:
                type: string
                description: Target website URL of the search for this query.
          description: Suggested search queries.
        categories:
          type: array
          items:
            type: object
            required:
            - category_id
            - link
            properties:
              title:
                type: string
                description: Name of the category.
              category_id:
                type: string
                description: Target category identifier accepted by category_id.
              link:
                type: string
                description: Target website URL of the category.
          description: Category path of the results, from the broadest category to
            the narrowest.
        error:
          type: string
          description: Explanation of an empty result or an unsuccessful request.
