Frontera Signal Alcohol Sales API

openapi: 3.2.0
info:
  title: Frontera Signal Alcohol Sales API
  version: 1.8.0
  description: 'Market data for the Rio Grande Valley, Texas, paid per call. Construction: weekly permits, building-input prices, housing supply and labor for Hidalgo and Cameron counties; commercial projects, projects near an address, company track records with trade licenses, monthly housing permits and filed cost per square foot for Hidalgo, Cameron, Starr and Willacy; Hidalgo County parcel records; shelf prices for common building materials. Border and trade: bridge wait times now and by hour of week at the 11 Valley crossings, monthly crossings by port, the peso and Gulf Coast diesel. Local business: city sales tax by month, new business outlets by city and industry, bar and restaurant alcohol sales by location, home health agencies with star ratings, and a snapshot per industry. Ask the Valley answers one plain question in English or Spanish from all of it. Every value carries as_of, age_days, cadence and stale (weekly measures go stale after 14 days, monthly measures after 90). dark = the source published nothing that week; no_reading = we have no reading for it. Ranges are {low, high, unit}; approx marks a rounded reading. Not a quote, bid or appraisal. Terms: https://fronterasignal.com/terms/'
  termsOfService: https://fronterasignal.com/terms/
  contact:
    name: Frontera Signal
    email: hello@fronterasignal.com
    url: https://fronterasignal.com/contact/
  license:
    name: Frontera Signal terms of use
    url: https://fronterasignal.com/terms/
  x-guidance: 'Frontera Signal sells Rio Grande Valley (South Texas) market data per call over x402: construction, border crossings and bridge waits, peso and diesel, city sales tax, new businesses, alcohol sales and home health. USDC on Base, no account, no API key.

    1. Read the free catalog first: GET https://fronterasignal.com/api/v1 lists every paid endpoint, its price, what it returns, its parameters and a free sample.

    2. Free samples: https://fronterasignal.com/data/v1/samples/<endpoint>.json is one real answer per paid endpoint. https://fronterasignal.com/data/v1/index.json carries the latest 4 weeks of each weekly series.

    3. Call a paid endpoint without payment: it answers 402 with a JSON body (price, returns, sample, docs, how_to_pay) and a PAYMENT-REQUIRED header (base64 JSON, x402 v2). Sign and retry with a PAYMENT-SIGNATURE header; a 200 carries PAYMENT-RESPONSE with the settlement.

    4. Bad or unknown parameters get a free 400 and a valid query with nothing to return gets a free 404, before any payment, as {ok, error, message, docs, allowed}. allowed lists every parameter and its valid values. A payment is never settled on a 4xx or 5xx. nearby and parcel look the address up after the payment is verified, so an address they cannot place is a 404 that is not settled; GET /api/v1/parcel/match checks a parcel address for free first.

    Border and local business: bridge waits now -> /api/v1/bridge-wait; typical wait by hour of week -> /api/v1/bridge-hourly; monthly trucks, cars and pedestrians by port -> /api/v1/crossings; pesos per dollar -> /api/v1/peso; Gulf Coast diesel -> /api/v1/diesel; city sales tax -> /api/v1/sales-tax; new businesses by city and industry -> /api/v1/new-outlets; bar and restaurant alcohol sales -> /api/v1/alcohol-sales; home health agencies and ratings -> /api/v1/home-health; one industry in one call -> /api/v1/industry.

    Which endpoint: one city or the whole Valley this week -> /api/v1/snapshot. New commercial projects with owner, cost and dates -> /api/v1/projects. Projects within a radius of an address -> /api/v1/nearby. A company track record and its trade licenses -> /api/v1/companies. The Hidalgo County parcel record for an address -> /api/v1/parcel. Filed cost per square foot by county and type of work -> /api/v1/cost-per-sqft. Shelf prices for building materials -> /api/v1/materials. Monthly housing permits by structure type -> /api/v1/series/permits-monthly. Weekly history of permits, input prices, housing supply, labor or forecast grades -> /api/v1/series/<name>. The written weekly issue -> /api/v1/issue.

    A question in plain English or Spanish -> /api/v1/ask?q=...&lang=en|es ($0.25): one call reads the right endpoints and answers with the numbers used (data), the endpoints read (sources) and the newest date (as_of). A question outside the data is answered with in_scope false and the closest endpoint.

    Every value carries as_of, age_days, cadence and stale. dark and no_reading rows say a week has no reading; nothing is filled with guesses.

    MCP clients: https://fronterasignal.com/mcp (Streamable HTTP) serves the catalog, the free samples, the paid URL and price for your parameters and the free series as free, read-only tools.

    A2A clients: https://fronterasignal.com/a2a (JSON-RPC, A2A-Version 1.0) answers a message that names an endpoint or a Valley city with the paid URL and price. Free and read-only.'
  x-mcp:
    url: https://fronterasignal.com/mcp
    transport: streamable-http
    price: free
    tools:
    - list_endpoints
    - get_sample
    - how_to_pay
    - get_free_series
    about: 'Free and read-only: the paid endpoints and prices, a real sample per endpoint, the exact paid URL for your parameters and the free latest-4-weeks series. Payment stays on the HTTP API.'
  x-a2a:
    url: https://fronterasignal.com/a2a
    protocol_binding: JSONRPC
    protocol_version: '1.0'
    price: free
    agent_card: https://fronterasignal.com/.well-known/agent-card.json
    about: 'Free and read-only: send a message that names an endpoint or a Valley city and get the exact paid URL and price back. Send the header A2A-Version: 1.0.'
servers:
- url: https://fronterasignal.com
tags:
- name: Alcohol Sales
paths:
  /api/v1/alcohol-sales:
    get:
      operationId: alcohol_sales
      summary: Bar and restaurant alcohol sales
      description: 'Use to size a bar or restaurant market or rank venues in the Rio Grande Valley: monthly liquor, wine and beer sales per location, its trailing 12 months, city totals and year over year change. Filter by city or part of a venue name. Example: "Which McAllen bars sold the most alcohol last month?"


        Returns: Monthly alcohol sales (liquor, wine, beer and cover charges) at every bar and restaurant with a mixed beverage permit in the four Valley counties, ranked, with each location''s trailing 12-month total, city totals and the change from a year earlier.


        Free sample (a real answer to /api/v1/alcohol-sales?city=McAllen&limit=10): https://fronterasignal.com/data/v1/samples/alcohol-sales.json'
      externalDocs:
        description: 'Free sample: a real answer to /api/v1/alcohol-sales?city=McAllen&limit=10'
        url: https://fronterasignal.com/data/v1/samples/alcohol-sales.json
      x-payment-info:
        protocols:
        - x402: {}
        price:
          mode: fixed
          currency: USD
          amount: '0.05'
        network: eip155:8453
        asset: USDC
      security: []
      parameters:
      - name: city
        in: query
        required: false
        description: A Valley city or town, e.g. McAllen, Brownsville, Rio Grande City (case does not matter).
        schema:
          type: string
          minLength: 3
          maxLength: 40
          example: McAllen
      - name: name
        in: query
        required: false
        description: Part of a venue name, case-insensitive.
        schema:
          type: string
          minLength: 3
          maxLength: 60
          example: grill
      - name: limit
        in: query
        required: false
        description: How many locations to list, 1-200.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 25
          example: 10
      responses:
        '200':
          description: Monthly alcohol sales (liquor, wine, beer and cover charges) at every bar and restaurant with a mixed beverage permit in the four Valley counties, ranked, with each location's trailing 12-month total, city totals and the change from a year earlier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  publisher:
                    type: string
                  source:
                    type: string
                  dataset:
                    type: string
                  query:
                    type: object
                    properties:
                      city:
                        type: string
                      limit:
                        type: integer
                    required:
                    - limit
                  as_of:
                    type: string
                  cadence:
                    type: string
                  stale:
                    type: boolean
                  stale_after_days:
                    type: integer
                  updated_at:
                    type: string
                  month:
                    type: string
                  complete:
                    type: boolean
                  valley:
                    type: object
                    properties:
                      total_usd:
                        type: integer
                      locations:
                        type: integer
                      liquor_usd:
                        type: integer
                      wine_usd:
                        type: integer
                      beer_usd:
                        type: integer
                      prior_year_usd:
                        type: integer
                      yoy_pct:
                        type: number
                    required:
                    - total_usd
                    - locations
                    - liquor_usd
                    - wine_usd
                    - beer_usd
                    - prior_year_usd
                    - yoy_pct
                  cities:
                    type: array
                    items:
                      type: object
                      properties:
                        city:
                          type: string
                        county:
                          type: string
                        total_usd:
                          type: integer
                        locations:
                          type: integer
                        prior_year_usd:
                          type:
                          - integer
                          - 'null'
                        yoy_pct:
                          type:
                          - number
                          - 'null'
                      required:
                      - city
                      - county
                      - total_usd
                      - locations
                      - prior_year_usd
                      - yoy_pct
                  monthly:
                    type: array
                    items:
                      type: object
                      properties:
                        month:
                          type: string
                        total_usd:
                          type: integer
                        locations:
                          type: integer
                      required:
                      - month
                      - total_usd
                      - locations
                  matched:
                    type: integer
                  locations:
                    type: array
                    items:
                      type: object
                      properties:
                        rank:
                          type: integer
                        name:
                          type: string
                        city:
                          type: string
                        county:
                          type: string
                        address:
                          type: string
                        zip:
                          type: string
                        total_usd:
                          type: integer
                        liquor_usd:
                          type: integer
                        wine_usd:
                          type: integer
                        beer_usd:
                          type: integer
                        cover_usd:
                          type: integer
                        trailing_12m_usd:
                          type: integer
                      required:
                      - rank
                      - name
                      - city
                      - county
                      - address
                      - zip
                      - total_usd
                      - liquor_usd
                      - wine_usd
                      - beer_usd
                      - cover_usd
                      - trailing_12m_usd
                  note:
                    type: string
                  disclaimer:
                    type: string
                required:
                - publisher
                - source
                - dataset
                - query
                - as_of
                - cadence
                - stale
                - stale_after_days
                - updated_at
                - month
                - complete
                - valley
                - cities
                - monthly
                - matched
                - locations
                - note
                - disclaimer
              example:
                publisher: Frontera Signal
                source: Frontera Signal
                dataset: alcohol-sales
                query:
                  city: McAllen
                  limit: 10
                as_of: 2026-09
                cadence: monthly
                stale: false
                stale_after_days: 90
                updated_at: '2026-10-26T14:54:18.826Z'
                month: 2026-09
                complete: true
                valley:
                  total_usd: 17442435
                  locations: 654
                  liquor_usd: 9213263
                  wine_usd: 834707
                  beer_usd: 7059636
                  prior_year_usd: 17602015
                  yoy_pct: -0.9
                cities:
                - city: McAllen
                  county: Hidalgo
                  total_usd: 6598824
                  locations: 218
                  prior_year_usd: 6556149
                  yoy_pct: 0.7
                monthly:
                - month: 2025-09
                  total_usd: 17602015
                  locations: 703
                - month: 2025-10
                  total_usd: 18683858
                  locations: 701
                - month: 2025-11
                  total_usd: 18936095
                  locations: 710
                matched: 210
                locations:
                - rank: 1
                  name: 'Yard House #8382'
                  city: McAllen
                  county: Hidalgo
                  address: 2200 S 10TH ST Ste S17
                  zip: '78503'
                  total_usd: 292101
                  liquor_usd: 124694
                  wine_usd: 7732
                  beer_usd: 159675
                  cover_usd: 0
                  trailing_12m_usd: 2894447
                - rank: 2
                  name: Twin Peaks
                  city: McAllen
                  county: Hidalgo
                  address: 901 W Expressway 83
                  zip: '78503'
                  total_usd: 291947
                  liquor_usd: 99782
                  wine_usd: 908
                  beer_usd: 191257
                  cover_usd: 0
                  trailing_12m_usd: 3511105
                - rank: 5
                  name: Howling Rabbits Beer Works
                  city: McAllen
                  county: Hidalgo
                  address: 1200 Auburn Ave Ste 350
                  zip: '78504'
                  total_usd: 218086
                  liquor_usd: 123453
                  wine_usd: 1459
                  beer_usd: 93174
                  cover_usd: 0
                  trailing_12m_usd: 2699275
                note: 'Gross receipts each location reported for the month: liquor, wine, beer and cover charges, in US dollars. rank is within the Valley. trailing_12m_usd sums the 12 months through month. Late reports keep arriving for weeks; complete is false while the month still looks short. Locations whose name may be a person are counted but not listed.'
                disclaimer: 'Every value carries as_of, age_days, cadence and stale (weekly measures go stale after 14 days, monthly measures after 90). dark = the source published nothing that week; no_reading = we have no reading for it. Ranges are {low, high, unit}; approx marks a rounded reading. Not a quote, bid or appraisal. Terms: https://fronterasignal.com/terms/'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: Payment required. Free of charge to receive. The PAYMENT-REQUIRED header (base64 JSON, x402 v2) lists price, network, asset and payTo; retry with a PAYMENT-SIGNATURE header.
          headers:
            PAYMENT-REQUIRED:
              description: Base64 JSON payment requirements (x402 v2).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
              example:
                error: payment_required
                price: $0.05
                returns: Monthly alcohol sales (liquor, wine, beer and cover charges) at every bar and restaurant with a mixed beverage permit in the four Valley counties, ranked, with each location's trailing 12-month total, city totals and the change from a year earlier.
                sample: https://fronterasignal.com/data/v1/samples/alcohol-sales.json
                docs: https://fronterasignal.com/openapi.json
                how_to_pay: x402 v2, USDC on Base; retry with PAYMENT-SIGNATURE
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      tags:
      - Alcohol Sales
components:
  responses:
    BadRequest:
      description: 'Bad or unknown parameters. Free, before any payment; allowed lists the valid ones.

        unknown_param (400): A query parameter this endpoint does not take. allowed lists the ones it does.

        repeated_param (400): The same parameter was sent twice.

        missing_param (400): A required parameter is missing.

        bad_param (400): A value in the wrong format (date, ISO week, number, length). The message names the parameter.

        unknown_value (400): A value outside the list we cover (city, county, item, store, type of work, language). allowed lists the valid ones.

        unknown_week (400): No issue was published for that week in that language. allowed.week lists the ones we have.

        bad_range (400): from is after to.

        no_house_number (400): nearby and parcel need a house number and street; an intersection or a street alone has no single place.

        not_covered (400): The place is outside what the endpoint covers. parcel covers Hidalgo County only for now.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error: unknown_value
            message: city must be one of McAllen, Edinburg, Mission, Pharr, San Juan, Weslaco, Donna, Mercedes, Brownsville, Harlingen (got "Laredo").
            param: city
            docs: https://fronterasignal.com/openapi.json
            allowed:
              city:
                type: enum
                description: A Valley city. Omit for the whole Valley.
    ServiceUnavailable:
      description: 'The payment service is starting (retry after the Retry-After header), payments are off, or a live public-records lookup did not answer in time. Never settled.

        upstream_unavailable (503): nearby and parcel read public records at request time, and that service did not answer in time. Retry in a minute. Not settled.

        payment_service_starting (503): The payment service is starting. Retry after the Retry-After header (2 s). Never charged.

        payments_not_configured (503): Payments are not switched on for this deployment.

        ask_not_configured (503): ask: the answering service is not switched on for this deployment. Never charged.

        ask_unavailable (503): ask: the answer could not be written in time. Retry in a minute. Never settled.

        data_warming_up (503): A self-updating dataset (bridge waits, crossings, peso, diesel, sales tax, new outlets, alcohol sales, home health) has not been stored yet. Retry after the next refresh. Never settled.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error: payment_service_starting
            message: The payment service is starting. Retry in 2 seconds.
            docs: https://fronterasignal.com/openapi.json
            retry_after_seconds: 2
    NotFound:
      description: 'A valid query with nothing to return, or no such endpoint. Free: before any payment, or for nearby and parcel after the payment is verified and never settled.

        no_results (404): The query is valid but nothing matches it. Free.

        no_readings (404): Rows exist for that range but every one is dark or no_reading. Free.

        no_match (404): No owner or design firm contains that name. Free.

        too_few_projects (404): Fewer than 5 usable filings in every group, so there is no statistic to sell. Free; counts are in the body.

        not_found (404): No such endpoint or series.

        address_not_found (404): nearby and parcel: the address could not be placed on the map or matched to a parcel. Found after the payment is verified; the payment is not settled.

        ambiguous (404): nearby and parcel: the address fits several different places or parcels. Add the direction (N, S, E, W). Not settled.

        outside_coverage (404): nearby: the address is outside Hidalgo, Cameron, Starr and Willacy counties. Not settled.

        not_available (404): parcel: this record is not available from this API. Not settled.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error: no_results
            message: No filed projects match city=McAllen, since=2026-10-03. Widen the filters; filings go back to 2024-10-01.
            docs: https://fronterasignal.com/openapi.json
            allowed: {}
  schemas:
    Error:
      type: object
      required:
      - ok
      - error
      - message
      - docs
      description: 'One error shape for every refusal. 400 and 404 come before any payment and are free.

        unknown_param (400): A query parameter this endpoint does not take. allowed lists the ones it does.

        repeated_param (400): The same parameter was sent twice.

        missing_param (400): A required parameter is missing.

        bad_param (400): A value in the wrong format (date, ISO week, number, length). The message names the parameter.

        unknown_value (400): A value outside the list we cover (city, county, item, store, type of work, language). allowed lists the valid ones.

        unknown_week (400): No issue was published for that week in that language. allowed.week lists the ones we have.

        bad_range (400): from is after to.

        no_house_number (400): nearby and parcel need a house number and street; an intersection or a street alone has no single place.

        not_covered (400): The place is outside what the endpoint covers. parcel covers Hidalgo County only for now.

        no_results (404): The query is valid but nothing matches it. Free.

        no_readings (404): Rows exist for that range but every one is dark or no_reading. Free.

        no_match (404): No owner or design firm contains that name. Free.

        too_few_projects (404): Fewer than 5 usable filings in every group, so there is no statistic to sell. Free; counts are in the body.

        not_found (404): No such endpoint or series.

        address_not_found (404): nearby and parcel: the address could not be placed on the map or matched to a parcel. Found after the payment is verified; the payment is not settled.

        ambiguous (404): nearby and parcel: the address fits several different places or parcels. Add the direction (N, S, E, W). Not settled.

        outside_coverage (404): nearby: the address is outside Hidalgo, Cameron, Starr and Willacy counties. Not settled.

        not_available (404): parcel: this record is not available from this API. Not settled.

        rate_limited (429): parcel/match: too many free lookups from one IP address. Retry after the Retry-After header.

        upstream_unavailable (503): nearby and parcel read public records at request time, and that service did not answer in time. Retry in a minute. Not settled.

        payment_service_starting (503): The payment service is starting. Retry after the Retry-After header (2 s). Never charged.

        payments_not_configured (503): Payments are not switched on for this deployment.

        ask_not_configured (503): ask: the answering service is not switched on for this deployment. Never charged.

        ask_unavailable (503): ask: the answer could not be written in time. Retry in a minute. Never settled.

        data_warming_up (503): A self-updating dataset (bridge waits, crossings, peso, diesel, sales tax, new outlets, alcohol sales, home health) has not been stored yet. Retry after the next refresh. Never settled.'
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
          enum:
          - unknown_param
          - repeated_param
          - missing_param
          - bad_param
          - unknown_value
          - unknown_week
          - bad_range
          - no_house_number
          - not_covered
          - no_results
          - no_readings
          - no_match
          - too_few_projects
          - not_found
          - address_not_found
          - ambiguous
          - outside_coverage
          - not_available
          - rate_limited
          - upstream_unavailable
          - payment_service_starting
          - payments_not_configured
          - ask_not_configured
          - ask_unavailable
          - data_warming_up
        message:
          type: string
          description: What was wrong, in a sentence.
        param:
          type: string
          description: The parameter at fault, when there is one.
        docs:
          type: string
          format: uri
          const: https://fronterasignal.com/openapi.json
        allowed:
          type: object
          description: Every parameter this endpoint takes, with its type and valid values.
          additionalProperties:
            type: object
        groups:
          type: array
          description: 'too_few_projects only: the count in each county and type of work.'
          items:
            type: object
        location:
          type: object
          description: 'nearby no_results only: where the address was placed.'
        coverage:
          type: object
          description: 'nearby no_results only: how many filings have a map point.'
        retry_after_seconds:
          type: integer
          description: payment_service_starting only.
    PaymentRequired:
      type: object
      required:
      - error
      - price
      - returns
      - sample
      - docs
      - how_to_pay
      properties:
        error:
          type: string
          const: payment_required
        price:
          type: string
          description: USD per call, paid in USDC.
          example: $0.02
        returns:
          type: string
          description: What the paid call answers with, in one line.
        sample:
          type: string
          format: uri
          description: A real answer to this endpoint, free.
        docs:
          type: string
          format: uri
        how_to_pay:
          type: string
          const: x402 v2, USDC on Base; retry with PAYMENT-SIGNATURE