openapi: 3.0.3
info:
  title: Wine-Searcher market-price wine-check API
  description: The Wine-Searcher API allows developers to plug Wine-Searcher wine data directly into websites and applications. Typical consumers include wine apps, blogs, market research companies, wine investment platforms, valuations, and insurance services. The API provides wine pricing data (average, min, max), critic scores, merchant listings, grape variety, region, and available vintages for any wine in the Wine-Searcher database. Requests are submitted using HTTP GET with query parameters. Responses can be returned in XML (default) or JSON.
  version: 1.0.0
  contact:
    name: Wine-Searcher Developer Support
    url: https://www.wine-searcher.com/trade/ws-api
  termsOfService: https://www.wine-searcher.com/trade/terms
servers:
- url: https://www.wine-searcher.com/ws_api.php
  description: Wine-Searcher API
tags:
- name: wine-check
  description: Wine price check and data lookup
paths:
  /wine-check:
    get:
      operationId: getWineCheck
      summary: Get Wine Check Data
      description: Returns aggregated wine data for a given wine name and optional vintage. Provides the Wine-Searcher aggregated critic score, grape variety, producer, region, min/max/average price, and alcohol by volume. This is the primary endpoint for wine valuation and data enrichment use cases.
      tags:
      - wine-check
      parameters:
      - name: api_key
        in: query
        required: true
        description: Your Wine-Searcher API key
        schema:
          type: string
      - name: winename
        in: query
        required: true
        description: Name of the wine to look up (URL-encoded, e.g., haut+brion)
        schema:
          type: string
      - name: vintage
        in: query
        required: false
        description: Wine vintage year (4-digit year or 'NV' for non-vintage)
        schema:
          type: string
      - name: currencycode
        in: query
        required: false
        description: 'ISO 4217 currency code for price results (default: USD)'
        schema:
          type: string
          default: USD
      - name: location
        in: query
        required: false
        description: Filter results by country code (e.g., USA, GBR)
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: Filter results by US state code (e.g., CA, NY)
        schema:
          type: string
      - name: offer_type
        in: query
        required: false
        description: Filter by offer type (R=retail, A=auction, B=both)
        schema:
          type: string
          enum:
          - R
          - A
          - B
      - name: format
        in: query
        required: false
        description: Response format (json or xml, default is xml)
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
      responses:
        '200':
          description: Wine check results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WineCheckResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/WineCheckResponse'
components:
  schemas:
    WineCheckResponse:
      type: object
      description: Response from the Wine Check API endpoint
      properties:
        status:
          type: integer
          description: 'API status code: 0=Success, 1=No wines found, 2=Input error, 3=Server error, 4=Invalid access code, 5=Exceeded limit, 6=Access denied, 7=Subscription ended, 8=Multiple wines matched, 9=Nothing found, 10=Cannot access data, 99=Unknown error'
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 99
        message:
          type: string
          description: Status message describing the result
        wine:
          $ref: '#/components/schemas/Wine'
    Wine:
      type: object
      description: Wine data with aggregated pricing and details
      properties:
        name:
          type: string
          description: Full wine name as known by Wine-Searcher
        vintage:
          type: string
          description: Vintage year or NV (non-vintage)
        producer:
          type: string
          description: Wine producer/winery name
        region:
          type: string
          description: Wine production region
        country:
          type: string
          description: Production country
        grape:
          type: string
          description: Primary grape variety or blend
        alcohol_by_volume:
          type: number
          format: float
          description: Alcohol by volume percentage
        score:
          type: number
          format: float
          description: Wine-Searcher aggregated critic score (0-100)
        price_average:
          type: number
          format: float
          description: Average retail price across all listings
        price_min:
          type: number
          format: float
          description: Minimum retail price across all listings
        price_max:
          type: number
          format: float
          description: Maximum retail price across all listings
        currency:
          type: string
          description: Currency code for the price values
        listing_count:
          type: integer
          description: Total number of merchant listings