> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kohl's Stores

> Search Kohl's anonymous store locator within 1–100 miles of latitude/longitude (default 25). Returns source location IDs, store numbers, addresses, coordinates, phone numbers and rounded distances. Results are bounded to 1,000 stores with an explicit truncation flag. Confirmed empty results use zero SocialQuery credits.

Search within `radius` miles of `location_coordinate=latitude,longitude`, or supply both `latitude` and `longitude`. The radius is 1–100 miles, default 25. If both input forms are supplied, their coordinates must agree.

The adapter requests the exact anonymous Kohl's locator service and validates its echoed center, radius and result limit. Every returned store is cross-checked against the source map marker. `place.id` is the source location ID; `place.ext.store_number` is the retailer's separate store number. Both are retained as strings.

Store records include the name, source store-page URL, full address, phone when available, latitude/longitude and individual address components. `ext.distance_miles` preserves the source's rounded distance; it is not driving distance. Opening hours, live inventory and current open/closed state are not inferred.

`returned_count` and `total` both count this response. Requests are bounded to 1,000 stores. `truncated: true` means that ceiling was reached, so the response must not be treated as the entire radius. Invalid or inconsistent source data fails without a net SocialQuery charge.

A confirmed empty source response returns an empty `items` array and uses **zero credits**. The normal maximum price is reserved before fetching and refunded when the verified result is empty. Each fresh request uses one basic Firecrawl fetch within the configured source allowance. Cache hits and successful idempotent replays are free.


## OpenAPI

````yaml GET /kohls/stores
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /kohls/stores:
    get:
      tags:
        - Kohls
      summary: Kohls Stores
      description: >-
        Search Kohl's anonymous store locator within 1–100 miles of
        latitude/longitude (default 25). Returns source location IDs, store
        numbers, addresses, coordinates, phone numbers and rounded distances.
        Results are bounded to 1,000 stores with an explicit truncation flag.
        Confirmed empty results use zero SocialQuery credits.
      operationId: get_kohls_stores
      parameters:
        - name: location_coordinate
          in: query
          required: false
          example: 40.758,-73.9855
          schema:
            type: string
          description: >-
            Latitude,longitude pair. If separate coordinates are also supplied,
            they must agree.
        - name: latitude
          in: query
          required: false
          schema:
            type: string
          description: >-
            Latitude between -90 and 90; supply longitude as well unless using
            location_coordinate.
        - name: longitude
          in: query
          required: false
          schema:
            type: string
          description: Longitude between -180 and 180.
        - name: radius
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Search radius in miles, 1–100; default 25.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Search Kohl's anonymous store locator within 1–100 miles of
            latitude/longitude (default 25). Returns source location IDs, store
            numbers, addresses, coordinates, phone numbers and rounded
            distances. Results are bounded to 1,000 stores with an explicit
            truncation flag. Confirmed empty results use zero SocialQuery
            credits.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                place:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    name:
                                      type: string
                                    url:
                                      type: string
                                    category:
                                      const: retail
                                    address:
                                      type: string
                                    phone:
                                      type:
                                        - string
                                        - 'null'
                                    latitude:
                                      type: number
                                    longitude:
                                      type: number
                                    ext:
                                      type: object
                                      properties:
                                        store_number:
                                          type: string
                                        street_address:
                                          type: string
                                        city:
                                          type: string
                                        state:
                                          type: string
                                        postcode:
                                          type: string
                                        country:
                                          const: US
                                        distance_miles:
                                          type: number
                                        website_url:
                                          type: string
                                      required:
                                        - store_number
                                        - street_address
                                        - city
                                        - state
                                        - postcode
                                        - country
                                        - distance_miles
                                        - website_url
                                  required:
                                    - id
                                    - name
                                    - url
                                    - category
                                    - address
                                    - phone
                                    - latitude
                                    - longitude
                                    - ext
                              required:
                                - place
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: integer
                            minimum: 0
                          center:
                            type: object
                            properties:
                              latitude:
                                type: number
                              longitude:
                                type: number
                            required:
                              - latitude
                              - longitude
                          radius_miles:
                            type: integer
                            minimum: 1
                            maximum: 100
                          truncated:
                            type: boolean
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - center
                          - radius_miles
                          - truncated
                          - source
                          - coverage_note
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.