{ "openapi": "3.1.0", "info": { "title": "San Antonio Mixed Beverage Receipts API", "version": "1.0.0", "summary": "Nineteen years of alcohol sales for Bexar County, Texas, by month and ZIP code.", "description": "Read-only, CORS-enabled, cached JSON over the Texas Comptroller's mixed beverage gross receipts filings.\n\nThree things about this data will make a consumer confidently wrong, and each is returned as structured data by \/quality. The source numbers counties alphabetically rather than by FIPS, so Bexar is 015 and querying 029 silently returns a different county. Returns keep arriving after a month closes, so the newest month is a stub that looks like a collapse. And the drink-type columns do not sum to the reported total, because some filers report no breakdown.\n\nZIP codes with fewer than a handful of permit holders are withheld, because at that size a ZIP total is one identifiable business's revenue; their dollars stay inside the citywide totals. This API aggregates only and will not return a named venue.\n\nEvery response carries a `caveats` object stating these conditions.", "contact": { "name": "BrandShyp", "url": "https:\/\/brandshyp.org\/contact-us\/" }, "license": { "name": "Texas open data", "url": "https:\/\/data.texas.gov\/" } }, "externalDocs": { "description": "Human documentation, with the charts and the caveats in context", "url": "https:\/\/brandshyp.org\/san-antonio-bar-revenue\/" }, "servers": [ { "url": "https:\/\/brandshyp.org\/api\/v1\/mixed-beverage" } ], "security": [], "tags": [ { "name": "receipts", "description": "Reported alcohol sales" }, { "name": "meta", "description": "Discovery and data quality" } ], "paths": { "\/": { "get": { "summary": "Discovery document", "operationId": "getRoot", "tags": [ "meta" ], "responses": { "200": { "description": "Service description and headline findings, derived live from the dataset.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/summary": { "get": { "summary": "Citywide totals", "operationId": "getSummary", "tags": [ "receipts" ], "responses": { "200": { "description": "Totals, the latest complete month, the drink mix with its coverage rate, and the pandemic trough.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/months": { "get": { "summary": "Monthly series", "operationId": "getMonths", "tags": [ "receipts" ], "responses": { "200": { "description": "Every complete month with its filings, distinct permit holders and receipts.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/zips": { "get": { "summary": "By ZIP code", "operationId": "getZips", "tags": [ "receipts" ], "responses": { "200": { "description": "Per-ZIP receipts over the trailing window for ZIPs above the disclosure floor, plus the withheld aggregate.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/quality": { "get": { "summary": "What will make you wrong", "operationId": "getQuality", "tags": [ "meta" ], "responses": { "200": { "description": "The county-code trap, the disclosure floor, the reporting lag, the mix coverage gap, and what this API deliberately does not publish.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/summary.csv": { "get": { "summary": "The whole cube as CSV", "operationId": "getSummaryCsv", "tags": [ "receipts" ], "responses": { "200": { "description": "Tidy CSV covering totals, months, ZIPs, the drink mix and the caveats.", "content": { "text\/csv": { "schema": { "type": "string" } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } }, "\/openapi.json": { "get": { "summary": "This document", "operationId": "getOpenapi", "tags": [ "meta" ], "responses": { "200": { "description": "OpenAPI 3.1 description.", "content": { "application\/json": { "schema": { "type": "object", "required": [ "caveats" ], "properties": { "caveats": { "$ref": "#\/components\/schemas\/Caveats" } } } } } }, "405": { "description": "Method not allowed. This API is read-only (GET).", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "503": { "description": "Dataset temporarily unavailable. It is rebuilt monthly.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error", "status" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation." }, "status": { "type": "integer", "description": "HTTP status code, repeated in the body." } } }, "Caveats": { "type": "object", "description": "The conditions under which these numbers mean anything. Present on every successful JSON response.", "properties": { "gross_receipts": { "type": "string" }, "permit_universe": { "type": "string" }, "not_a_denominator": { "type": "string" }, "disclosure_floor": { "type": "string" }, "partial_months": { "type": "string" }, "mix_coverage": { "type": "string" }, "county_code": { "type": "string" } } } } } }