Frontera Signal Ask API

openapi: 3.2.0
info:
  title: Frontera Signal Ask 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: Ask
paths:
  /api/v1/ask:
    get:
      operationId: ask
      summary: Ask the Valley
      description: 'Use when you have one question in plain English or Spanish about the Rio Grande Valley, Texas and want the answer without picking endpoints: new businesses, material prices, permits, projects, sales tax, bridge waits, crossings, peso, diesel, housing supply. One call reads the right Frontera Signal data and answers with numbers and dates. Example: "What does a 2x4 cost in McAllen this week?"


        Returns: A short plain answer to one question about the Rio Grande Valley, written from Frontera Signal data, with the numbers it used, the endpoints they came from and the newest date behind them, in English or Spanish.


        Free sample (a real answer to /api/v1/ask?q=What+does+a+2x4+cost+in+McAllen+this+week%3F&lang=en): https://fronterasignal.com/data/v1/samples/ask.json'
      externalDocs:
        description: 'Free sample: a real answer to /api/v1/ask?q=What+does+a+2x4+cost+in+McAllen+this+week%3F&lang=en'
        url: https://fronterasignal.com/data/v1/samples/ask.json
      x-payment-info:
        protocols:
        - x402: {}
        price:
          mode: fixed
          currency: USD
          amount: '0.25'
        network: eip155:8453
        asset: USDC
      security: []
      parameters:
      - name: q
        in: query
        required: true
        description: Your question in plain English or Spanish, 3 to 300 characters.
        schema:
          type: string
          minLength: 3
          maxLength: 300
          example: What does a 2x4 cost in McAllen this week?
      - name: lang
        in: query
        required: false
        description: 'Language of the answer: en or es. Default en.'
        schema:
          type: string
          enum:
          - en
          - es
          default: en
          example: en
      responses:
        '200':
          description: A short plain answer to one question about the Rio Grande Valley, written from Frontera Signal data, with the numbers it used, the endpoints they came from and the newest date behind them, in English or Spanish.
          content:
            application/json:
              schema:
                type: object
                properties:
                  publisher:
                    type: string
                  dataset:
                    type: string
                  query:
                    type: object
                    properties:
                      q:
                        type: string
                      lang:
                        type: string
                    required:
                    - q
                    - lang
                  answer:
                    type: string
                  in_scope:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: number
                        unit:
                          type: string
                        as_of:
                          type: string
                        endpoint:
                          type: string
                      required:
                      - label
                      - value
                      - unit
                      - as_of
                      - endpoint
                  sources:
                    type: array
                    items: {}
                  as_of:
                    type: 'null'
                  note:
                    type: string
                  disclaimer:
                    type: string
                required:
                - publisher
                - dataset
                - query
                - answer
                - in_scope
                - data
                - sources
                - as_of
                - note
                - disclaimer
              example:
                publisher: Frontera Signal
                dataset: ask
                query:
                  q: What does a 2x4 cost in McAllen this week?
                  lang: en
                answer: Frontera Signal data has no McAllen 2x4 price from this week. The newest reading is $3.98 each for an 8 ft 2x4 stud at two big box stores in McAllen, checked on September 7, 2026, which makes it 57 days old. The price held at $3.98 at every check from August 27 to September 7, 2026, so treat it as a guide and confirm the current shelf price before you rely on it.
                in_scope: true
                data:
                - label: 2x4 stud 8 ft, McAllen big box (two stores)
                  value: 3.98
                  unit: USD each
                  as_of: '2026-09-07'
                  endpoint: /api/v1/materials
                sources: []
                as_of: null
                note: answer is written from the Frontera Signal data listed in data, read from the endpoints in sources at the time of the call; call those endpoints for the full rows. as_of is the newest date behind the data used. A question the data cannot answer has in_scope false and closest names the nearest endpoint.
                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.25
                returns: A short plain answer to one question about the Rio Grande Valley, written from Frontera Signal data, with the numbers it used, the endpoints they came from and the newest date behind them, in English or Spanish.
                sample: https://fronterasignal.com/data/v1/samples/ask.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:
      - Ask
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