{ "openapi": "3.1.0", "info": { "title": "yDrink Data API", "version": "1", "description": "Your yDrink data, whenever you want it: brand shipments, products, accounts, consumer spend and Marketslice. Docs: https://api.ydr.ink/docs/" }, "servers": [ { "url": "https://api.ydr.ink" } ], "security": [ { "key": [] } ], "paths": { "/v1/accounts": { "get": { "operationId": "accounts", "summary": "Accounts", "description": "Every on-premise account by yDrink id, with its chain and segmentation.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." }, { "name": "changed_since", "in": "query", "schema": { "type": "integer" }, "description": "Only rows changed since this version (from /v1/changes)." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "accounts" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "tdlinx_code": { "type": "string", "description": "Nielsen's account id. Only for clients with TDLinx access" }, "coverage_indicator": { "type": "integer", "description": "0 no coverage, 1 monthly coverage, 2 weekly coverage" }, "name": { "type": "string", "description": "Account name" }, "chain": { "type": "string", "description": "Chain name" }, "corporate": { "type": "string", "description": "Corporation or chain owner" }, "address": { "type": "string", "description": "Street address: 123 Main St" }, "city": { "type": "string", "description": "City: Austin" }, "zip": { "type": "string", "description": "5-digit zip code: 78756" }, "county": { "type": "string", "description": "County: Travis" }, "state": { "type": "string", "description": "State: TX" }, "segment": { "type": "string", "description": "Channel: Dining, Bar/Nightclub" }, "sub_segment": { "type": "string", "description": "Sub channel: Casual, Sports Bar" }, "cuisine": { "type": "string", "description": "Food type: American, Cajun" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/accounts/merges": { "get": { "operationId": "merges", "summary": "Account merges", "description": "Accounts found to be the same place: the old id and the id it was merged into. Move your history from merged_id to surviving_id.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "changed_since", "in": "query", "schema": { "type": "integer" }, "description": "Only rows changed since this version (from /v1/changes)." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "merges" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "merged_id": { "type": "integer", "description": "The establishment id that no longer exists" }, "surviving_id": { "type": "integer", "description": "The establishment id it was merged into" }, "merged_at": { "type": "string", "description": "When it was merged" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/brand/monthly": { "get": { "operationId": "brand_monthly", "summary": "Brand shipments, monthly", "description": "Your products sold into each on-premise account, by month.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First period, YYYY-MM, like 2026-09. Default: the first there is." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last period, YYYY-MM, like 2026-09. Default: the newest." }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "brand_monthly" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "product_id": { "type": "integer", "description": "yDrink's internal product id" }, "units": { "type": "integer", "description": "Bottles sold into the account" }, "cases": { "type": "number", "description": "9-liter cases sold into the account" }, "sales_date": { "type": "string", "format": "date", "description": "The month, as its last day: 2026-09-30" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/brand/weekly": { "get": { "operationId": "brand_weekly", "summary": "Brand shipments, weekly", "description": "Your products sold into each on-premise account, by week.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First period, YYYYWW, like 202642. Default: the first there is." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last period, YYYYWW, like 202642. Default: the newest." }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "brand_weekly" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "product_id": { "type": "integer", "description": "yDrink's internal product id" }, "units": { "type": "integer", "description": "Bottles sold into the account" }, "cases": { "type": "number", "description": "9-liter cases sold into the account" }, "yearweek": { "type": "string", "description": "The week, as YYYYWW: 202642. Weeks start on Sunday" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/changes": { "get": { "operationId": "changes", "summary": "What changed", "tags": [ "Staying in sync" ], "description": "Every period that changed since a version, per dataset. Delete those periods on your side and pull them again with from and to.", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The version you last synced to (from a response's version), or 0 for everything." } ], "responses": { "200": { "description": "The change manifest", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/consumer-spend": { "get": { "operationId": "consumer_spend", "summary": "Consumer spend", "description": "Taxable alcohol dollars consumers spent at each on-premise account, by month (mixed beverage tax receipts).", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First period, YYYY-MM, like 2026-09. Default: the first there is." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last period, YYYY-MM, like 2026-09. Default: the newest." }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "consumer_spend" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "liquor": { "type": "integer", "description": "Taxable liquor dollars" }, "wine": { "type": "integer", "description": "Taxable wine dollars" }, "beer": { "type": "integer", "description": "Taxable beer dollars" }, "total": { "type": "integer", "description": "Total taxable liquor, wine and beer dollars" }, "sales_date": { "type": "string", "format": "date", "description": "The month, as its last day: 2026-09-30" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/marketslice/monthly": { "get": { "operationId": "marketslice_monthly", "summary": "Marketslice, monthly", "description": "The whole on-premise spirits market by account and category, by month.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First period, YYYY-MM, like 2026-09. Default: the first there is." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last period, YYYY-MM, like 2026-09. Default: the newest." }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "marketslice_monthly" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "product_category": { "type": "string", "description": "yDrink main category: Tequila, Whiskey" }, "product_sub_category": { "type": "string", "description": "yDrink's lower category: Anejo, Scotch" }, "product_price_level": { "type": "string", "description": "Price point: Value, Mid, Premium, Super, Luxury" }, "units": { "type": "integer", "description": "Market (all) bottles sold into the account" }, "cases": { "type": "number", "description": "Market (all) 9-liter cases sold into the account" }, "sales_date": { "type": "string", "format": "date", "description": "The month, as its last day: 2026-09-30" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/marketslice/weekly": { "get": { "operationId": "marketslice_weekly", "summary": "Marketslice, weekly", "description": "The whole on-premise spirits market by account and category, by week.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First period, YYYYWW, like 202642. Default: the first there is." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last period, YYYYWW, like 202642. Default: the newest." }, { "name": "establishment_id", "in": "query", "schema": { "type": "string" }, "description": "Only these accounts: ids separated by commas, up to 1000." } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "marketslice_weekly" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "establishment_id": { "type": "integer", "description": "yDrink's internal establishment (account) id" }, "product_category": { "type": "string", "description": "yDrink main category: Tequila, Whiskey" }, "product_sub_category": { "type": "string", "description": "yDrink's lower category: Anejo, Scotch" }, "product_price_level": { "type": "string", "description": "Price point: Value, Mid, Premium, Super, Luxury" }, "units": { "type": "integer", "description": "Market (all) bottles sold into the account" }, "cases": { "type": "number", "description": "Market (all) 9-liter cases sold into the account" }, "yearweek": { "type": "string", "description": "The week, as YYYYWW: 202642. Weeks start on Sunday" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/products": { "get": { "operationId": "products", "summary": "Products", "description": "Your products: every product in your brand data, with its brand, label, size and categories.", "tags": [ "Data" ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "A page of rows. X-Next-Cursor has the next page's cursor, when there is one.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset", "version", "rows", "next_cursor", "data" ], "properties": { "dataset": { "type": "string", "const": "products" }, "version": { "type": "integer" }, "rows": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "yDrink's internal product id" }, "brand": { "type": "string", "description": "Major brand name: Crown Royal" }, "label": { "type": "string", "description": "Major label name: Crown Royal Regal Apple" }, "product": { "type": "string", "description": "yDrink's lowest product description; often the same as label" }, "product_size": { "type": "string", "description": "Bottle size: 750ML, 1L, 12OZ" }, "product_type": { "type": "string", "description": "Liquor, Wine, Beer or N/A" }, "product_category": { "type": "string", "description": "yDrink main category: Tequila, Whiskey, White, Red" }, "product_sub_category": { "type": "string", "description": "yDrink's lower category: Anejo, Scotch, Chardonnay, Pinot Noir" }, "product_price_level": { "type": "string", "description": "Price point: Value, Mid, Premium, Super, Luxury" }, "product_per_9l_case": { "type": "number", "description": "Bottles in a 9-liter case" } }, "additionalProperties": false } } } } }, "text/csv": { "schema": { "type": "string" }, "description": "A header row, then the rows, in the field order above." } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/status": { "get": { "operationId": "status", "summary": "Status", "tags": [ "About you" ], "description": "Your datasets (included or not, and why), the periods each holds and when it was last updated, your version and your limits.", "responses": { "200": { "description": "Your status", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/usage": { "get": { "operationId": "usage", "summary": "Your usage", "tags": [ "About you" ], "description": "Your requests, refusals and rows for the last 30 days, and your limits.", "responses": { "200": { "description": "Your usage", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "key": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ydk_live_..." } }, "parameters": { "cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "From the last page's next_cursor. Leave it out for the first page." }, "format": { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "csv for CSV (or send Accept: text/csv). Default JSON." } }, "responses": { "Error": { "description": "Refused or failed: error.code says why (see Errors in the docs).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_key", "ip_not_allowed", "paused", "no_service", "not_included", "not_found", "bad_period", "bad_parameter", "bad_cursor", "bad_version", "no_data_set", "rate_limited", "quota", "concurrent", "error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } } } }