Introduction
Welcome to the Untappd For Business (UTFB) API! You can use our API to access Untappd For Business API endpoints.
Version - /api/v1
For example: /api/v1/sessions
You must prepend /api/v1 to all the endpoints.
TLS Versions
The Untappd API currently supports only TLS v1.2.
Authentication
To base64 encode your email and API token:
printf [email protected]:MySuperAPIToken123 | base64
Outputs:
bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM=
All requests to the API require either a read only token or a read & write token.
An API token is essentially your password to the API. The API expects the API Token to be included in all requests in a header that looks like the following:
Authorization: Basic bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM=
You must replace Authorization: Basic bmlja0B1bnRhcHBkLmNvbTpNeVN1cGVyQVBJVG9rZW4xMjM= with your encoded email and API key.
See: https://en.wikipedia.org/wiki/Basic_access_authentication
You can verify the token by sending a request to the current user endpoint
You can find your tokens under the section titled **"API Access Tokens" at: https://business.untappd.com/account.**
Alternatively, you may use the /sessions routes below to programmatically fetch your API tokens. Please do not hit the /sessions route for every request! We rate limit it so your requests will fail! The POST /sessions route should ideally only ever be used once to initially fetch the token. You can then hard code your API tokens.
API Token Types
There are two types of API tokens.
- Read Only
- Read & Write
The Read Only token only allows read access to your data. You cannot modify any of your data using a read only token. Read only tokens should be used in frontend (user facing) applications. For example if you build a custom menu that is embedded on your website. This way you can hard code the token in the web page and not have to worry about a malicious user using your token to change your data.
The Read & Write token allows read and write access to your data. You can modify your data using the read and write token. Read and write tokens should be used only on the backend (non-user facing) integrations. For example if you build an application that works behind the scenes to sync your menus with your point of sale system.
You can find your tokens here: https://business.untappd.com/account.
POST /sessions
To get your API key, use this code:
curl "https://business.untappd.com/api/v1/sessions" \
-X POST \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "DrinkMoreBeer"}'
Returns JSON structured like this:
{
"user": {
"email": "[email protected]",
"auth_token": "Rt4688PzSJUSdXZeZLTB",
"auth_token_read_only": "Kr3514GdHWBYjQBuLHJP"
}
}
You can get your API key by sending a POST request with a JSON body containing the user's email and password.
The response to the POST request will return the email, auth_token, and auth_token_read_only which must be supplied with every request via the Basic Authorization header.
Reset session
Reset the API key for the currently authorized user.
Request:
curl "https://business.untappd.com/api/v1/sessions" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{ "status": "OK" }
HTTP Request
DELETE https://business.untappd.com/api/v1/sessions
Analytics
Track an event
Track an event for location analytics. These events are aggregated and displayed as part of the analytics dashboard.
If you are building a custom embedded menu on your website using this api then you should hit this endpoint every time your menu is loaded by a visitor of your website to track the menu view.
curl "http://localhost:3000/api/v1/locations/3/analytics?source_name=iPhoneApp" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{ "status" : "OK" }
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/analytics
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to record the event for. |
| source_name | Integer | true | The source of the event. This is used to group and label events on the analytics dashboard. Defaults to: API. e.g. API, HomePage, MobileApp |
Container Sizes
In order to set a container on an item, you must know the container_size.id.
The index route here will give you all the possible container sizes to present to a user. We use a select field on business.untappd.com.
- Container Sizes have many items.
- Container belongs to a Container Size
Container Size Object
| Property | Type | Description |
|---|---|---|
| created_at | timestamp | Time at which the ContainerSize was created. ISO8601 format. |
| id | integer | Unique identifier for the ContainerSize |
| name | string | Name of the ContainerSize |
| ounces | float | Number of ounces the ContainerSize holds |
| position | integer | The position of the ContainerSize in the list of ContainerSizes. Positions start at zero and should be contiguous. |
| updated_at | timestamp | Time at which the ContainzerSize was last updated. ISO8601 format. |
List all container sizes
Request:
curl "http://localhost:3000/api/v1/container_sizes" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"container_sizes": [
{
"id": 94,
"name": "1oz Draft",
"ounces": "1.0",
"position": 0,
"created_at": "2016-06-01T16:26:07.206217Z",
"updated_at": "2017-01-30T16:11:56.740164Z"
},
{
"id": 116,
"name": "1.5oz Draft",
"ounces": "1.5",
"position": 1,
"created_at": "2016-07-01T19:05:30.941985Z",
"updated_at": "2017-01-30T16:11:56.538908Z"
},
{
"id": 93,
"name": "2oz Draft",
"ounces": "2.0",
"position": 2,
"created_at": "2016-06-01T16:26:07.206217Z",
"updated_at": "2016-07-01T19:36:38.267600Z"
},
{
"id": 127,
"name": "2.5oz Draft",
"ounces": "2.5",
"position": 3,
"created_at": "2016-07-26T19:30:18.883625Z",
"updated_at": "2016-08-01T19:43:50.743959Z"
},
{
"id": 34,
"name": "3oz Draft",
"ounces": "3.0",
"position": 4,
"created_at": "2016-03-01T15:36:26.000000Z",
"updated_at": "2016-08-01T19:43:50.763425Z"
}
]
}
Returns a list of all container sizes. This list is likely to be added to in the future. A given container size will most likely never be removed.
HTTP Request
GET https://business.untappd.com/api/v1/container_sizes
Containers
Container Object
| Property | Type | Description |
|---|---|---|
| _track_by | integer | |
| calories | integer | Number of calories for the Container |
| container_size_id | integer | ContainerSize identifier. See: ContainerSize. |
| container_size | ContainerSize | The ContainerSize for the Container |
| created_at | timestamp | Time at which the Container was created. ISO8601 format. |
| currency | string | Currency used for the price of the Container. ISO 4217 3-letter code. |
| id | integer | Unique identifier for the Container |
| item_id | integer | Item id that the Container belongs to. See Item. |
| name | string | Name of the Container |
| position | integer | The position of the Container in the list of Containers for the Item. Positions start at zero and should be contiguous. |
| price | float | Price for the Container. Currency is determined by the currency property. |
| updated_at | timestamp | Time at which the Container was last updated. ISO8601 format. |
List all containers
Returns a list of containers belonging to an item.
Request:
curl "http://localhost:3000/api/v1/items/64/containers" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"containers": [
{
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "7.00",
"position": 0,
"container_size": {
"id": 18,
"name": "20oz Draft",
"position": 21,
"created_at": "2016-03-01T15:36:26.000Z",
"updated_at": "2016-08-24T20:52:06.390Z",
"container_size_group_id": 2,
"ounces": "20.0"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/items/:item_id/containers
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| item_id | Integer | true | The id of the item. |
| build | true or not set | false | Add a blank container (not yet persisted) to the response. This is useful when you have a reactive frontend that fetches all the containers and provides fields for a new one to be added. |
Create a container
Add a new container to an item.
Request:
curl "http://localhost:3000/api/v1/items/64/containers" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
-H "Content-Type: application/json" \
-d '{ "container": { "container_size_id": 18, "price": 7.00 } }'
Returns JSON structured like this:
{
"container": {
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "7.00",
"position": 0,
"container_size": {
"id": 18,
"name": "20oz Draft",
"position": 21,
"created_at": "2016-03-01T15:36:26.000Z",
"updated_at": "2016-08-24T20:52:06.390Z",
"container_size_group_id": 2,
"ounces": "20.0"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/items/:item_id/containers
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| item_id | Integer | true | The id of the item. |
| container_size_id | Integer | true | id of the container size. See: Container Sizes. |
| price | Float | true | Price of the container size for an item. |
Retrieve a container
Retrieve the details of an existing container. You need only supply the unique container identifier that was returned upon container creation.
Request:
curl "http://localhost:3000/api/v1/containers/118" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"container": {
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "7.00",
"position": 0,
"container_size": {
"id": 18,
"name": "20oz Draft",
"position": 21,
"created_at": "2016-03-01T15:36:26.000Z",
"updated_at": "2016-08-24T20:52:06.390Z",
"container_size_group_id": 2,
"ounces": "20.0"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/containers/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the container. |
Update a container
Updates the specified container by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/containers/118" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
-H "Content-Type: application/json" \
-d '{ "container": { "price": 2.99, "position": 1 } }'
Returns JSON structured like this:
{
"container": {
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "2.99",
"position": 1,
"container_size": {
"id": 18,
"name": "20oz Draft",
"position": 21,
"created_at": "2016-03-01T15:36:26.000Z",
"updated_at": "2016-08-24T20:52:06.390Z",
"container_size_group_id": 2,
"ounces": "20.0"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/containers/:id
PATCH https://business.untappd.com/api/v1/containers/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the container. |
| container_size_id | Integer | true | id of the container size. See: Container Sizes. |
| price | Integer | true | Price of the container size for an item. |
| position | Integer | false | The position of the container in the list of containers for the item. Positions start at zero and should be contiguous. |
Delete a container
Permanently deletes a container. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/containers/118" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns the deleted container as JSON structured like this:
{
"container": {
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "7.00",
"position": 0,
"container_size": {
"id": 18,
"name": "20oz Draft",
"position": 21,
"created_at": "2016-03-01T15:36:26.000Z",
"updated_at": "2016-08-24T20:52:06.390Z",
"container_size_group_id": 2,
"ounces": "20.0"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/containers/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The container to be deleted. |
Current User
The current user belonging to the auth token.
Returns JSON structured like this:
{
"current_user": {
"id": 1,
"email": "[email protected]",
"created_at": "2016-01-06T19:12:06Z",
"updated_at": "2016-06-15T14:16:36Z",
"role": "owner",
"admin": false,
"business_id": 1,
"untappd_username": "starbuck",
"name": "Kara"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/current_user
Events
- A location has many events.
- An event belongs to a location.
List all events
Returns a list of events belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/3/events" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"events": [
{
"id": 1,
"name": "Super fun happy hour",
"description": "Liquid drinks half off only during happy hour.",
"place_json": {
"id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
"url": "https://maps.google.com/?cid=13931099202030384142",
"icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
"name": "Next Glass",
"scope": "GOOGLE",
"types": ["point_of_interest", "establishment"],
"geometry": {
"location": {
"lat": 34.234665,
"lng": -77.94829399999998
}
},
"place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
"vicinity": "21 South Front Street, Wilmington",
"reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
"utc_offset": -240,
"adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"html_attributions": [],
"address_components": [
{
"types": ["street_number"],
"long_name": "21",
"short_name": "21"
},
{
"types": ["route"],
"long_name": "South Front Street",
"short_name": "S Front St"
},
{
"types": ["neighborhood", "political"],
"long_name": "Historic District",
"short_name": "Historic District"
},
{
"types": ["locality", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_3", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_2", "political"],
"long_name": "New Hanover County",
"short_name": "New Hanover County"
},
{
"types": ["administrative_area_level_1", "political"],
"long_name": "North Carolina",
"short_name": "NC"
},
{
"types": ["country", "political"],
"long_name": "United States",
"short_name": "US"
},
{
"types": ["postal_code"],
"long_name": "28401",
"short_name": "28401"
}
]
},
"start_time": "2017-06-30T04:15:00.000Z",
"start_time_in_zone": "2017-06-30T00:15:00-04:00",
"end_time": "2017-06-30T19:15:00.000Z",
"end_time_in_zone": "2017-06-30T15:15:00-04:00",
"location_id": 3,
"created_at": "2016-06-20T14:47:33.551Z",
"updated_at": "2016-06-20T14:59:11.153Z",
"location_name": "Next Glass",
"city": "Wilmington",
"state": "NC",
"street": "21 S Front St",
"country": "US",
"zip": "28401",
"latitude": "34.234665",
"longitude": "-77.94829399999998",
"from_facebook": false,
"link": "https://nextglass.co"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/events
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
Create an event
Creates a new event.
Request:
curl "http://localhost:3000/api/v1/locations/3/events" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "event": { "name": "Super fun happy hour", "description": "Liquid drinks half off only during happy hour.", "start_time_date": "2017-06-30", "start_time_time": "12:15", "end_time_date": "2017-06-30", "end_time_time": "15:15" } }'
Returns JSON structured like this:
{
"event": {
"id": 3,
"name": "Super fun happy hour",
"description": "Liquid drinks half off only during happy hour.",
"place_json": null,
"start_time": "2017-06-30T16:15:00.000Z",
"start_time_in_zone": "2017-06-30T12:15:00-04:00",
"end_time": "2017-06-30T19:15:00.000Z",
"end_time_in_zone": "2017-06-30T15:15:00-04:00",
"location_id": 3,
"created_at": "2016-06-20T14:55:21.667Z",
"updated_at": "2016-06-20T14:55:21.667Z",
"location_name": null,
"city": null,
"state": null,
"street": null,
"country": null,
"zip": null,
"latitude": null,
"longitude": null,
"from_facebook": false,
"link": null
}
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/events
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
| name | String | true | The event name. |
| description | String | true | The event description. |
| start_time_date | String | true | The event start date. e.g. 2017-06-30 |
| start_time_time | String | true | The event start time. 24-hour format e.g. 12:15 |
| end_time_date | String | false | The event end date. e.g. 2017-06-30 |
| end_time_time | String | false | The event end time. 24-hour format e.g. 15:15 |
| link | String | false | A url to a web page for the event. |
| location_name | String | false | The event location. e.g. Next Glass |
| street | String | false | The event location city. e.g. 21 S Front St. |
| city | String | false | The event location city. e.g. Wilmington |
| state | String | false | The event location city. e.g. NC |
| zip | String | false | The event location city. e.g. 28401 |
| country | String | false | The event location city. e.g. US |
Retrieve an event
Retrieve the details of an existing event. You need only supply the unique event identifier that was returned upon event creation.
Request:
curl "http://localhost:3000/api/v1/events/1" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"event": {
"id": 1,
"name": "Super fun happy hour",
"description": "Liquid drinks half off only during happy hour.",
"place_json": {
"id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
"url": "https://maps.google.com/?cid=13931099202030384142",
"icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
"name": "Next Glass",
"scope": "GOOGLE",
"types": ["point_of_interest", "establishment"],
"geometry": {
"location": {
"lat": 34.234665,
"lng": -77.94829399999998
}
},
"place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
"vicinity": "21 South Front Street, Wilmington",
"reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
"utc_offset": -240,
"adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"html_attributions": [],
"address_components": [
{
"types": ["street_number"],
"long_name": "21",
"short_name": "21"
},
{
"types": ["route"],
"long_name": "South Front Street",
"short_name": "S Front St"
},
{
"types": ["neighborhood", "political"],
"long_name": "Historic District",
"short_name": "Historic District"
},
{
"types": ["locality", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_3", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_2", "political"],
"long_name": "New Hanover County",
"short_name": "New Hanover County"
},
{
"types": ["administrative_area_level_1", "political"],
"long_name": "North Carolina",
"short_name": "NC"
},
{
"types": ["country", "political"],
"long_name": "United States",
"short_name": "US"
},
{
"types": ["postal_code"],
"long_name": "28401",
"short_name": "28401"
}
]
},
"start_time": "2017-06-30T04:15:00.000Z",
"start_time_in_zone": "2017-06-30T00:15:00-04:00",
"end_time": "2017-06-30T19:15:00.000Z",
"end_time_in_zone": "2017-06-30T15:15:00-04:00",
"location_id": 3,
"created_at": "2016-06-20T14:47:33.551Z",
"updated_at": "2016-06-20T14:59:11.153Z",
"location_name": "Next Glass",
"city": "Wilmington",
"state": "NC",
"street": "21 S Front St",
"country": "US",
"zip": "28401",
"latitude": "34.234665",
"longitude": "-77.94829399999998",
"from_facebook": false,
"link": "https://nextglass.co"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/events/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the event. |
Update an event
Updates the specified menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Note: start_time_date and start_time_time must be set together. Same thing goes for end_time_date and end_time_time.
Request:
curl "http://localhost:3000/api/v1/events/1" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "event": { "name": "Super fun happy hour. Changed start time", "start_time_date": "2017-06-30", "start_time_time": "14:15" } }'
Returns JSON structured like this:
{
"event": {
"id": 1,
"name": "Super fun happy hour. Changed start time",
"description": "Liquid drinks half off only during happy hour.",
"place_json": {
"id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
"url": "https://maps.google.com/?cid=13931099202030384142",
"icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
"name": "Next Glass",
"scope": "GOOGLE",
"types": ["point_of_interest", "establishment"],
"geometry": {
"location": {
"lat": 34.234665,
"lng": -77.94829399999998
}
},
"place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
"vicinity": "21 South Front Street, Wilmington",
"reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
"utc_offset": -240,
"adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"html_attributions": [],
"address_components": [
{
"types": ["street_number"],
"long_name": "21",
"short_name": "21"
},
{
"types": ["route"],
"long_name": "South Front Street",
"short_name": "S Front St"
},
{
"types": ["neighborhood", "political"],
"long_name": "Historic District",
"short_name": "Historic District"
},
{
"types": ["locality", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_3", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_2", "political"],
"long_name": "New Hanover County",
"short_name": "New Hanover County"
},
{
"types": ["administrative_area_level_1", "political"],
"long_name": "North Carolina",
"short_name": "NC"
},
{
"types": ["country", "political"],
"long_name": "United States",
"short_name": "US"
},
{
"types": ["postal_code"],
"long_name": "28401",
"short_name": "28401"
}
]
},
"start_time": "2017-06-30T18:15:00.000Z",
"start_time_in_zone": "2017-06-30T14:15:00-04:00",
"end_time": null,
"end_time_in_zone": null,
"location_id": 3,
"created_at": "2016-06-20T14:47:33.551Z",
"updated_at": "2016-06-20T15:06:33.046Z",
"location_name": "Next Glass",
"city": "Wilmington",
"state": "NC",
"street": "21 S Front St",
"country": "US",
"zip": "28401",
"latitude": "34.234665",
"longitude": "-77.94829399999998",
"from_facebook": false,
"link": "https://nextglass.co"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/events/:id
PATCH https://business.untappd.com/api/v1/events/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the event. |
| name | String | true | The event name. |
| description | String | true | The event description. |
| start_time_date | String | true | The event start date. e.g. 2017-06-30 |
| start_time_time | String | true | The event start time. 24-hour format e.g. 12:15 |
| end_time_date | String | false | The event end date. e.g. 2017-06-30 |
| end_time_time | String | false | The event end time. 24-hour format e.g. 15:15 |
| link | String | false | A url to a web page for the event. |
| location_name | String | false | The event location. e.g. Next Glass |
| street | String | false | The event location city. e.g. 21 S Front St. |
| city | String | false | The event location city. e.g. Wilmington |
| state | String | false | The event location city. e.g. NC |
| zip | String | false | The event location city. e.g. 28401 |
| country | String | false | The event location city. e.g. US |
Delete an event
Permanently deletes an event. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/events/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns the deleted event as JSON structured like this:
{
"event": {
"id": 1,
"name": "Super fun happy hour. Changed start time",
"description": "Liquid drinks half off only during happy hour.",
"place_json": {
"id": "5cfafd431239a7242f807c60f67c95d7670cb33f",
"url": "https://maps.google.com/?cid=13931099202030384142",
"icon": "https://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
"name": "Next Glass",
"scope": "GOOGLE",
"types": ["point_of_interest", "establishment"],
"geometry": {
"location": {
"lat": 34.234665,
"lng": -77.94829399999998
}
},
"place_id": "ChIJ9xKQtMcfqokRDrS_A-o0VcE",
"vicinity": "21 South Front Street, Wilmington",
"reference": "CmReAAAAk8lnuukeWe9pdvxdr1GwFtwWZCfR78NpnbUGNarlNoJaVcDSTiWdh57OTpgal6f4i8OktGTjDVHbXxBq9dfgfG3E7esCfV_BR-URXRehDvAxB0F76qLx6e6XfiAJShaREhDvFuIPRvlhQuvn3x0xtakZGhRgRASCIW2rLgn4eUxfN7IIjMLLOw",
"utc_offset": -240,
"adr_address": "<span class=\"street-address\">21 S Front St</span>, <span class=\"locality\">Wilmington</span>, <span class=\"region\">NC</span> <span class=\"postal-code\">28401</span>, <span class=\"country-name\">USA</span>",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"html_attributions": [],
"address_components": [
{
"types": ["street_number"],
"long_name": "21",
"short_name": "21"
},
{
"types": ["route"],
"long_name": "South Front Street",
"short_name": "S Front St"
},
{
"types": ["neighborhood", "political"],
"long_name": "Historic District",
"short_name": "Historic District"
},
{
"types": ["locality", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_3", "political"],
"long_name": "Wilmington",
"short_name": "Wilmington"
},
{
"types": ["administrative_area_level_2", "political"],
"long_name": "New Hanover County",
"short_name": "New Hanover County"
},
{
"types": ["administrative_area_level_1", "political"],
"long_name": "North Carolina",
"short_name": "NC"
},
{
"types": ["country", "political"],
"long_name": "United States",
"short_name": "US"
},
{
"types": ["postal_code"],
"long_name": "28401",
"short_name": "28401"
}
]
},
"start_time": "2017-06-30T18:15:00.000Z",
"start_time_in_zone": "2017-06-30T14:15:00-04:00",
"end_time": null,
"end_time_in_zone": null,
"location_id": 3,
"created_at": "2016-06-20T14:47:33.551Z",
"updated_at": "2016-06-20T15:06:33.046Z",
"location_name": "Next Glass",
"city": "Wilmington",
"state": "NC",
"street": "21 S Front St",
"country": "US",
"zip": "28401",
"latitude": "34.234665",
"longitude": "-77.94829399999998",
"from_facebook": false,
"link": "https://nextglass.co"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/events/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The event to be deleted. |
Hours
List hours
List the hours associated with a given location.
curl "http://localhost:3000/api/v1/locations/2/hours" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"hours": [
{
"id": 8,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "monday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.225Z",
"updated_at": "2020-08-13T17:50:20.225Z"
},
{
"id": 9,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "tuesday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.228Z",
"updated_at": "2020-08-13T17:50:20.228Z"
},
{
"id": 10,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "wednesday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.230Z",
"updated_at": "2020-08-13T17:50:20.230Z"
},
{
"id": 11,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "thursday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.233Z",
"updated_at": "2020-08-13T17:50:20.233Z"
},
{
"id": 12,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "friday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.235Z",
"updated_at": "2020-08-13T17:50:20.235Z"
},
{
"id": 13,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "saturday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.237Z",
"updated_at": "2020-08-13T17:50:20.237Z"
},
{
"id": 14,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "sunday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.240Z",
"updated_at": "2020-08-13T17:50:20.240Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:id/hours
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the location. |
Update hours
Updates the specified location's hours by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/locations/2/hours" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "hours": [ { "id": 8, "closed: 0, open_at: "2020-08-13T20:07:48.112Z" } ] }'
Returns JSON structured like this:
{
"hours": [
{
"id": 8,
"always_open": false,
"closed": false,
"open_at": "2020-08-13T20:07:48.112Z",
"close_at": null,
"day": "monday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.225Z",
"updated_at": "2020-08-13T20:08:16.248Z"
},
{
"id": 9,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "tuesday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.228Z",
"updated_at": "2020-08-13T17:50:20.228Z"
},
{
"id": 10,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "wednesday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.230Z",
"updated_at": "2020-08-13T17:50:20.230Z"
},
{
"id": 11,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "thursday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.233Z",
"updated_at": "2020-08-13T17:50:20.233Z"
},
{
"id": 12,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "friday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.235Z",
"updated_at": "2020-08-13T17:50:20.235Z"
},
{
"id": 13,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "saturday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.237Z",
"updated_at": "2020-08-13T17:50:20.237Z"
},
{
"id": 14,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "sunday",
"location_id": 2,
"created_at": "2020-08-13T17:50:20.240Z",
"updated_at": "2020-08-13T17:50:20.240Z"
}
]
}
HTTP Request
PUT https://business.untappd.com/api/v1/locations/:location_id/hours
PATCH https://business.untappd.com/api/v1/locations/:location_id/hours
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
| id | Integer | true | The id of the hour. |
| always_open | Boolean | false | Whether the location is always open. |
| closed | Boolean | false | Whether the location is closed. |
| open_at | DateTime | false | The location's opening hour |
| close_at | DateTime | false | The location's closing hour |
Insights
Retrieve checkins over time
Retrieve the number of checkins over time for a location.
Request defaults to
group_by=checkins
curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"insights": {
"checkins": {
"count": 7,
"items": [
{
"date": "2016-06-14",
"checkins": 0,
"distinct_users": 0
},
{
"date": "2016-06-15",
"checkins": 2,
"distinct_users": 1
},
{
"date": "2016-06-16",
"checkins": 2,
"distinct_users": 2
},
{
"date": "2016-06-17",
"checkins": 7,
"distinct_users": 5
},
{
"date": "2016-06-18",
"checkins": 0,
"distinct_users": 0
},
{
"date": "2016-06-19",
"checkins": 0,
"distinct_users": 0
},
{
"date": "2016-06-20",
"checkins": 0,
"distinct_users": 0
}
]
},
"time_taken": 0.017
}
}
The
group_byparam will return differently structured JSON depending on the value passed.Request with
group_by=gender
curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=gender" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Response
{
"insights": {
"user_gender": [
{
"gender": "Male",
"count": 7
},
{
"gender": "Female",
"count": 4
},
{
"gender": "N/A",
"count": 0
}
],
"time_taken": 0.011
}
}
Request with
group_by=ages
curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=ages" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Response
{
"insights": {
"user_ages": {
"data": {
"19-21": 0,
"22-25": 0,
"26-30": 9,
"31-40": 1,
"41-50": 0,
"51-60": 1,
"61+": 0
},
"total": 11
},
"time_taken": 0.014
}
}
Request with
group_by=daily
curl "http://localhost:3000/api/v1/locations/3/insights/checkins_over_time?group_by=daily" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Response
{
"insights": {
"daily_data": [
{
"day": "Monday",
"distinct_users": 0
},
{
"day": "Tuesday",
"distinct_users": 0
},
{
"day": "Wednesday",
"distinct_users": 1
},
{
"day": "Thursday",
"distinct_users": 2
},
{
"day": "Friday",
"distinct_users": 5
},
{
"day": "Saturday",
"distinct_users": 0
},
{
"day": "Sunday",
"distinct_users": 0
}
],
"time_taken": 0.007
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/insights/checkins_over_time
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to query checkins for. |
| group_by | Must be one of: · checkins · gender · ages · daily |
false | Groups the checkins over time by the given value. Defaults to: checkins. |
| num_days | Must be one of: · 1 · 7 · 30 · 90 · 180 |
false | The number of days to query the data for. Defaults to: 7. |
| tz_offset | Integer | false | The timezone to query the data for (in hours). Defaults to location timezone. e.g. -5 |
Retrieve menu views over time
Retrieve the number of menu views over time for a location.
curl "http://localhost:3000/api/v1/locations/3/insights/menu_views_over_time?num_days=90" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"total_menu_views": 149,
"menu_views": [
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-22T04:00:00.000Z",
"end": "2016-03-23T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-23T04:00:00.000Z",
"end": "2016-03-24T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-24T04:00:00.000Z",
"end": "2016-03-25T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-25T04:00:00.000Z",
"end": "2016-03-26T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-26T04:00:00.000Z",
"end": "2016-03-27T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-27T04:00:00.000Z",
"end": "2016-03-28T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-28T04:00:00.000Z",
"end": "2016-03-29T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-29T04:00:00.000Z",
"end": "2016-03-30T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-30T04:00:00.000Z",
"end": "2016-03-31T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-03-31T04:00:00.000Z",
"end": "2016-04-01T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 1
}
],
"timeframe": {
"start": "2016-04-01T04:00:00.000Z",
"end": "2016-04-02T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-02T04:00:00.000Z",
"end": "2016-04-03T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-03T04:00:00.000Z",
"end": "2016-04-04T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-04T04:00:00.000Z",
"end": "2016-04-05T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-05T04:00:00.000Z",
"end": "2016-04-06T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-06T04:00:00.000Z",
"end": "2016-04-07T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 1
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-07T04:00:00.000Z",
"end": "2016-04-08T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-08T04:00:00.000Z",
"end": "2016-04-09T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-09T04:00:00.000Z",
"end": "2016-04-10T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-10T04:00:00.000Z",
"end": "2016-04-11T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-11T04:00:00.000Z",
"end": "2016-04-12T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-12T04:00:00.000Z",
"end": "2016-04-13T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-13T04:00:00.000Z",
"end": "2016-04-14T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-14T04:00:00.000Z",
"end": "2016-04-15T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-15T04:00:00.000Z",
"end": "2016-04-16T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-16T04:00:00.000Z",
"end": "2016-04-17T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-17T04:00:00.000Z",
"end": "2016-04-18T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-18T04:00:00.000Z",
"end": "2016-04-19T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-19T04:00:00.000Z",
"end": "2016-04-20T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-20T04:00:00.000Z",
"end": "2016-04-21T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-21T04:00:00.000Z",
"end": "2016-04-22T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-22T04:00:00.000Z",
"end": "2016-04-23T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-23T04:00:00.000Z",
"end": "2016-04-24T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-24T04:00:00.000Z",
"end": "2016-04-25T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-25T04:00:00.000Z",
"end": "2016-04-26T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-26T04:00:00.000Z",
"end": "2016-04-27T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-27T04:00:00.000Z",
"end": "2016-04-28T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-28T04:00:00.000Z",
"end": "2016-04-29T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-29T04:00:00.000Z",
"end": "2016-04-30T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-04-30T04:00:00.000Z",
"end": "2016-05-01T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-01T04:00:00.000Z",
"end": "2016-05-02T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-02T04:00:00.000Z",
"end": "2016-05-03T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-03T04:00:00.000Z",
"end": "2016-05-04T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 24
}
],
"timeframe": {
"start": "2016-05-04T04:00:00.000Z",
"end": "2016-05-05T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-05T04:00:00.000Z",
"end": "2016-05-06T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-06T04:00:00.000Z",
"end": "2016-05-07T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-07T04:00:00.000Z",
"end": "2016-05-08T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-08T04:00:00.000Z",
"end": "2016-05-09T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-09T04:00:00.000Z",
"end": "2016-05-10T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-10T04:00:00.000Z",
"end": "2016-05-11T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-11T04:00:00.000Z",
"end": "2016-05-12T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-12T04:00:00.000Z",
"end": "2016-05-13T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-13T04:00:00.000Z",
"end": "2016-05-14T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-14T04:00:00.000Z",
"end": "2016-05-15T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-15T04:00:00.000Z",
"end": "2016-05-16T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 32
}
],
"timeframe": {
"start": "2016-05-16T04:00:00.000Z",
"end": "2016-05-17T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 27
}
],
"timeframe": {
"start": "2016-05-17T04:00:00.000Z",
"end": "2016-05-18T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 64
}
],
"timeframe": {
"start": "2016-05-18T04:00:00.000Z",
"end": "2016-05-19T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-19T04:00:00.000Z",
"end": "2016-05-20T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-20T04:00:00.000Z",
"end": "2016-05-21T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-21T04:00:00.000Z",
"end": "2016-05-22T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-22T04:00:00.000Z",
"end": "2016-05-23T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-23T04:00:00.000Z",
"end": "2016-05-24T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-24T04:00:00.000Z",
"end": "2016-05-25T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-25T04:00:00.000Z",
"end": "2016-05-26T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-26T04:00:00.000Z",
"end": "2016-05-27T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-27T04:00:00.000Z",
"end": "2016-05-28T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-28T04:00:00.000Z",
"end": "2016-05-29T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-29T04:00:00.000Z",
"end": "2016-05-30T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-30T04:00:00.000Z",
"end": "2016-05-31T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-05-31T04:00:00.000Z",
"end": "2016-06-01T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-01T04:00:00.000Z",
"end": "2016-06-02T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-02T04:00:00.000Z",
"end": "2016-06-03T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-03T04:00:00.000Z",
"end": "2016-06-04T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-04T04:00:00.000Z",
"end": "2016-06-05T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-05T04:00:00.000Z",
"end": "2016-06-06T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-06T04:00:00.000Z",
"end": "2016-06-07T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-07T04:00:00.000Z",
"end": "2016-06-08T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-08T04:00:00.000Z",
"end": "2016-06-09T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-09T04:00:00.000Z",
"end": "2016-06-10T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-10T04:00:00.000Z",
"end": "2016-06-11T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-11T04:00:00.000Z",
"end": "2016-06-12T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-12T04:00:00.000Z",
"end": "2016-06-13T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-13T04:00:00.000Z",
"end": "2016-06-14T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-14T04:00:00.000Z",
"end": "2016-06-15T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-15T04:00:00.000Z",
"end": "2016-06-16T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-16T04:00:00.000Z",
"end": "2016-06-17T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-17T04:00:00.000Z",
"end": "2016-06-18T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-18T04:00:00.000Z",
"end": "2016-06-19T04:00:00.000Z"
}
},
{
"value": [
{
"source": "API",
"result": 0
},
{
"source": "website",
"result": 0
}
],
"timeframe": {
"start": "2016-06-19T04:00:00.000Z",
"end": "2016-06-20T04:00:00.000Z"
}
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/insights/menu_views_over_time
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to query checkins for. |
| num_days | Must be one of: · 1 · 7 · 30 · 90 · 180 |
false | The number of days to query the data for. Defaults to: 7. |
| tz_offset | Integer | false | The timezone to query the data for (in seconds). Defaults to location timezone. e.g. -18000 |
Retrieve stats for a location
Retrieve the stats for a location. The response includes properties that don't have a time range, i.e. total checkins for the location.
curl "http://localhost:3000/api/v1/locations/3/insights/stats" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"insights": {
"subscribes": {
"all": 10,
"beers": 0,
"events": 0
},
"stats": {
"total_checkins": 291,
"total_users": 31
},
"time_taken": 0.009
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/insights/stats
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to query the stats for. |
Retrieve subscribes over time
Retrieve the subscribes over time for a location.
curl "http://localhost:3000/api/v1/locations/3/insights/subscribes_over_time?num_days=30" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"insights": {
"date_range": "2016-05-21 11:47:44",
"subscribes": {
"all": 2,
"beers": 0,
"events": 0
},
"time_taken": 0.007
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/insights/subscribes_over_time
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to query the subscribes for. |
| num_days | Must be one of: · 1 · 7 · 30 · 90 · 180 |
false | The number of days to query the data for. Defaults to: 7. |
| tz_offset | Integer | false | The timezone to query the data for (in hours). Defaults to location timezone. e.g. -5 |
Retrieve top beers
Retrieve the top beers and top nearby beers over time for a location.
curl "http://localhost:3000/api/v1/locations/3/insights/top_beers" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"insights": {
"top_beers": [
{
"recent_created_at": "Sat, 18 Jun 2016 00:30:15 +0000",
"total_count": 4,
"total_users": 3,
"beer": {
"bid": 3963,
"beer_name": "Festina Peche",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-3963_54433_sm.jpeg",
"beer_abv": 4.5,
"beer_ibu": 8,
"beer_slug": "dogfish-head-craft-brewery-festina-peche",
"beer_description": "A refreshing neo-BerlinerWeisse fermented with honest-to-goodness peaches to (get this!) 4.5% abv! Because extreme beers don't have to be extremely boozy! Available in 4-pack and draft during the sweaty months.",
"is_in_production": 1,
"beer_style_id": 171,
"beer_style": "Berliner Weisse",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.481,
"rating_count": 66387
},
"brewery": {
"brewery_id": 459,
"brewery_name": "Dogfish Head Craft Brewery",
"brewery_slug": "dogfish-head-craft-brewery",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-459_b3e4d.jpeg",
"country_name": "United States",
"contact": {
"twitter": "dogfishbeer",
"facebook": "http://www.facebook.com/dogfishheadbeer",
"url": "http://www.dogfish.com/"
},
"location": {
"brewery_city": "Milton",
"brewery_state": "DE",
"lat": 38.7776,
"lng": -75.3099
},
"brewery_active": 1
}
},
{
"recent_created_at": "Fri, 17 Jun 2016 21:29:41 +0000",
"total_count": 2,
"total_users": 2,
"beer": {
"bid": 846311,
"beer_name": "The Guilty Party",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-846311_5904a_sm.jpeg",
"beer_abv": 5.1,
"beer_ibu": 37,
"beer_slug": "gibb-s-hundred-brewing-company-the-guilty-party",
"beer_description": "This charmingly drinkable brew is a pleasure to share with friends old and new. Pleasingly full-bodied, it achieves a nice balance of caramelly, nutty, biscuity maltiness, and smooth but assertive bitterness. The premium English and Belgian malt comes through nicely in the nose, along with floral Indie Golding hops, and a wonderful fruitiness from the traditional English yeast.",
"is_in_production": 1,
"beer_style_id": 92,
"beer_style": "Extra Special / Strong Bitter",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.643,
"rating_count": 1603
},
"brewery": {
"brewery_id": 128514,
"brewery_name": "Gibb's Hundred Brewing Company",
"brewery_slug": "gibb-s-hundred-brewing-company",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-128514_37810.jpeg",
"country_name": "United States",
"contact": {
"twitter": "GibbsHundred",
"facebook": "https://www.facebook.com/gibbshundred",
"url": "www.gibbshundred.com"
},
"location": {
"brewery_city": "Greensboro",
"brewery_state": "NC",
"lat": 36.0658,
"lng": -79.7918
},
"brewery_active": 1
}
},
{
"recent_created_at": "Thu, 16 Jun 2016 16:47:14 +0000",
"total_count": 2,
"total_users": 2,
"beer": {
"bid": 752597,
"beer_name": "Pleasure Island Pilsner",
"beer_label": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png",
"beer_abv": 5,
"beer_ibu": 30,
"beer_slug": "good-hops-brewing-pleasure-island-pilsner",
"beer_description": "",
"is_in_production": 1,
"beer_style_id": 39,
"beer_style": "Pilsner - Other",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.223,
"rating_count": 299
},
"brewery": {
"brewery_id": 138065,
"brewery_name": "Good Hops Brewing",
"brewery_slug": "good-hops-brewing",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-138065_c5ded.jpeg",
"country_name": "United States",
"contact": {
"twitter": "goodhopsbrewing",
"facebook": "https://www.facebook.com/pages/Good-Hops-Brewing-LLC/218556831654670",
"url": "http://www.goodhopsbrewing.com/"
},
"location": {
"brewery_city": "Carolina Beach",
"brewery_state": "NC",
"lat": 34.0413,
"lng": -77.9046
},
"brewery_active": 1
}
},
{
"recent_created_at": "Fri, 17 Jun 2016 20:30:51 +0000",
"total_count": 1,
"total_users": 1,
"beer": {
"bid": 1543818,
"beer_name": "Stone Citrusy Wit",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-1543818_c35ad_sm.jpeg",
"beer_abv": 5.3,
"beer_ibu": 35,
"beer_slug": "stone-brewing-stone-citrusy-wit",
"beer_description": "When it comes to our beers and the ingredients we use, we give a wit. So rather than spinning just the same fruit wheel of the classic orange peel, we punched up our wit with the dynamic duo of tangerine and kaffir lime leaf. The fruit-forward aromatics and flavors are perfectly balanced, so you don’t have to bother adding a slice (or leaf) to the rim of your glass. Even with this lack of unnecessary garnish, you won’t find an absence of intense fruit. In fact, each dryly refreshing, citrusy sip of this coriander-spiced, tangerine-infused, Mandarina Bavaria-hopped creation will satisfy even the most hardcore fan.",
"is_in_production": 1,
"beer_style_id": 83,
"beer_style": "Witbier",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.53,
"rating_count": 6547
},
"brewery": {
"brewery_id": 1204,
"brewery_name": "Stone Brewing",
"brewery_slug": "stone-brewing",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-1204_23541.jpeg",
"country_name": "United States",
"contact": {
"twitter": "StoneBrewingCo",
"facebook": "http://www.facebook.com/StoneBrewingCo",
"url": "http://www.stonebrewing.com/"
},
"location": {
"brewery_city": "Escondido",
"brewery_state": "CA",
"lat": 33.1157,
"lng": -117.12
},
"brewery_active": 1
}
},
{
"recent_created_at": "Fri, 17 Jun 2016 23:14:11 +0000",
"total_count": 1,
"total_users": 1,
"beer": {
"bid": 561943,
"beer_name": "Viking Fraoch Scottish Sour",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-561943_d13a0_sm.jpeg",
"beer_abv": 5,
"beer_ibu": 0,
"beer_slug": "d9-brewing-company-viking-fraoch-scottish-sour",
"beer_description": "Viking Fraoch Scottish Sour is the first Fanatical Ale in our Ancient Sour Series. Viking Fraoch (Fraoch is Scandinavian for Heather, a flower native to that area) is a 4,000 year old Viking Heather Flower Ale combined with an 18th Century Scottish Ale that is spontaneously soured with a rich brown hue, balanced tartness and hint of heather flowers. Flavors of caramel, bold tartness and ripe stone fruit give way to lingering flowers and clean, crisp mouthfeel.",
"is_in_production": 1,
"beer_style_id": 70,
"beer_style": "Sour Ale",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.86,
"rating_count": 5097
},
"brewery": {
"brewery_id": 67113,
"brewery_name": "D9 Brewing Company",
"brewery_slug": "d9-brewing-company",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-district9brewingcompany_67113.jpeg",
"country_name": "United States",
"contact": {
"twitter": "D9Brewing",
"facebook": "http://facebook.com/d9brewing",
"url": "http://www.d9brewing.com"
},
"location": {
"brewery_city": "Cornelius",
"brewery_state": "NC",
"lat": 35.4584,
"lng": -80.8539
},
"brewery_active": 1
}
},
{
"recent_created_at": "Fri, 17 Jun 2016 21:28:02 +0000",
"total_count": 1,
"total_users": 1,
"beer": {
"bid": 210218,
"beer_name": "Apple Ale",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-210218_d71b7_sm.jpeg",
"beer_abv": 5,
"beer_ibu": 0,
"beer_slug": "redd-s-brewing-company-apple-ale",
"beer_description": "Redd’s Apple Ale is an apple flavored golden ale with low malty and bitterness cues. With a crisp clean finish that allows the natural apple flavor to come through, this ale is for those times when you are looking to try something different.",
"is_in_production": 1,
"beer_style_id": 21,
"beer_style": "Fruit Beer",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1,
"rating_score": 3.113,
"rating_count": 60658
},
"brewery": {
"brewery_id": 36153,
"brewery_name": "Redd's Brewing Company",
"brewery_slug": "redds-brewing-company",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-ReddsBrewingCompany_36153_7d340.jpeg",
"country_name": "United States",
"contact": {
"twitter": "ReddsAppleAle",
"facebook": "https://www.facebook.com/reddsappleale",
"url": "http://www.reddsapple.com"
},
"location": {
"brewery_city": "Milwaukee",
"brewery_state": "WI",
"lat": 43.0389,
"lng": -87.9065
},
"brewery_active": 1
}
}
],
"top_nearby_beers": [
{
"beer": {
"bid": 49166,
"beer_name": "Port City IPA",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_49166_883830a37f4eaf609a5c87a54b5d.jpeg",
"beer_abv": 6.1,
"beer_ibu": 0,
"beer_slug": "front-street-brewery-nc-port-city-ipa",
"beer_description": "",
"is_in_production": 1,
"beer_style_id": 128,
"beer_style": "IPA - American",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1
},
"brewery": {
"brewery_id": 559,
"brewery_name": "Front Street Brewery (NC)",
"brewery_slug": "front-street-brewery-nc",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
"country_name": "United States",
"contact": {
"twitter": "FrontStreetBrew",
"facebook": "http://www.facebook.com/FrontStreetBrewery",
"url": "http://frontstreetbrewery.com"
},
"location": {
"brewery_city": "Wilmington",
"brewery_state": "NC",
"lat": 34.2358,
"lng": -77.9491
},
"brewery_active": 1
},
"total_users": 31
},
{
"beer": {
"bid": 8905,
"beer_name": "Sexual Chocolate (Bourbon Barrel Aged)",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-800268_54a99_sm.jpeg",
"beer_abv": 9.75,
"beer_ibu": 85,
"beer_slug": "foothills-brewing-sexual-chocolate-bourbon-barrel-aged",
"beer_description": "A barrel-aged cocoa infused Imperial Stout. Opaque black in color with a dark brown head. Big chocolate aroma with notes of espresso, blackstrap molasses, dark sweet toffee and dark fruit. Smooth dark chocolate backbone with complex notes of coffee, dark toffee and dark fruit.",
"is_in_production": 1,
"beer_style_id": 86,
"beer_style": "Stout - American Imperial / Double",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1
},
"brewery": {
"brewery_id": 543,
"brewery_name": "Foothills Brewing",
"brewery_slug": "foothills-brewing",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FoothillsBrewing_543.jpeg",
"country_name": "United States",
"contact": {
"twitter": "FoothillsBeer",
"facebook": "http://www.facebook.com/foothills.brewing",
"url": "http://www.foothillsbrewing.com/"
},
"location": {
"brewery_city": "Winston-Salem",
"brewery_state": "NC",
"lat": 36.0973,
"lng": -80.2509
},
"brewery_active": 1
},
"total_users": 27
},
{
"beer": {
"bid": 125297,
"beer_name": "Amberjack ESB",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_125297_e0fe653089ba588e5d3617d7e5ca.jpeg",
"beer_abv": 4.5,
"beer_ibu": 0,
"beer_slug": "front-street-brewery-nc-amberjack-esb",
"beer_description": "A traditional English Ale. ESB stands for Extra Special Bitter. The English’s idea of bitter is very different than ours. This beer does not have much upfront bitterness. It focuses more on hop flavor and aroma. East Kent Goldings hops give this beer a nice earthy aroma and flavor. English Crystal malt give this ale a nice amber color and a touch of caramel flavor. ",
"is_in_production": 1,
"beer_style_id": 92,
"beer_style": "Extra Special / Strong Bitter",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1
},
"brewery": {
"brewery_id": 559,
"brewery_name": "Front Street Brewery (NC)",
"brewery_slug": "front-street-brewery-nc",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
"country_name": "United States",
"contact": {
"twitter": "FrontStreetBrew",
"facebook": "http://www.facebook.com/FrontStreetBrewery",
"url": "http://frontstreetbrewery.com"
},
"location": {
"brewery_city": "Wilmington",
"brewery_state": "NC",
"lat": 34.2358,
"lng": -77.9491
},
"brewery_active": 1
},
"total_users": 26
},
{
"beer": {
"bid": 49653,
"beer_name": "Coastal Kolsch",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_49653_fa9f65c91c163fa7a4a8dcca22f5.jpeg",
"beer_abv": 4.8,
"beer_ibu": 0,
"beer_slug": "front-street-brewery-nc-coastal-kolsch",
"beer_description": "Unfiltered ",
"is_in_production": 1,
"beer_style_id": 30,
"beer_style": "Kölsch",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1
},
"brewery": {
"brewery_id": 559,
"brewery_name": "Front Street Brewery (NC)",
"brewery_slug": "front-street-brewery-nc",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
"country_name": "United States",
"contact": {
"twitter": "FrontStreetBrew",
"facebook": "http://www.facebook.com/FrontStreetBrewery",
"url": "http://frontstreetbrewery.com"
},
"location": {
"brewery_city": "Wilmington",
"brewery_state": "NC",
"lat": 34.2358,
"lng": -77.9491
},
"brewery_active": 1
},
"total_users": 24
},
{
"beer": {
"bid": 27490,
"beer_name": "Riptide Raspberry Ale",
"beer_label": "https://untappd.akamaized.net/site/beer_logos/beer-_27490_de5d725d6ddcfbb2cc6d56f8c0ce.jpeg",
"beer_abv": 4.7,
"beer_ibu": 0,
"beer_slug": "front-street-brewery-nc-riptide-raspberry-ale",
"beer_description": "American Wheat Ale made with all natural raspberry puree for a delicious, subtly sweet flavor. A Front Street favorite! Light bodied and delicately hopped. ",
"is_in_production": 1,
"beer_style_id": 60,
"beer_style": "Red Ale - American Amber / Red",
"auth_rating": 0,
"wish_list": false,
"beer_active": 1
},
"brewery": {
"brewery_id": 559,
"brewery_name": "Front Street Brewery (NC)",
"brewery_slug": "front-street-brewery-nc",
"brewery_label": "https://untappd.akamaized.net/site/brewery_logos/brewery-FrontStreetBreweryNC_559.jpeg",
"country_name": "United States",
"contact": {
"twitter": "FrontStreetBrew",
"facebook": "http://www.facebook.com/FrontStreetBrewery",
"url": "http://frontstreetbrewery.com"
},
"location": {
"brewery_city": "Wilmington",
"brewery_state": "NC",
"lat": 34.2358,
"lng": -77.9491
},
"brewery_active": 1
},
"total_users": 19
}
]
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/insights/top_beers
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to query the top beers for. |
| num_days | Must be one of: · 1 · 7 · 30 |
false | The number of days to query the data for. Defaults to: 7. |
| tz_offset | Integer | false | The timezone to query the data for (in hours). Defaults to location timezone. e.g. -5 |
Items
- An item belongs to a section.
- An item has many containers.
Item Object
| Property | Type | Description |
|---|---|---|
| calories | integer | Number of calories for the Item. To specify the calories for a specific Container size see Container. |
| created_at | timestamp | Time at which the Item was created. ISO8601 format. |
| custom_label_image | url | URL for the user uploaded label image for the Item. |
| custom_label_image_filename | string | Filename for the user uploaded label image. |
| custom_label_image_thumb | url | URL for the thumbnail version of the user uploaded label image. |
| default_image | url | URL for the default image for the Item. |
| description | string | Description of the Item. |
| id | integer | Unique identifier for the Item. |
| label_image | url | URL of the label image for the Item. |
| label_image_hd | url | URL of the HD version of the label image for the item. Only beer types have HD versions of the label. For all other types, this will be the same as label_image. |
| label_image_thumb | url | URL of the thumbnail version of the label image for the item. Thumbnail images are 100x100. |
| name | string | Name of the Item. |
| position | integer | The position of the Item in the list of Items for the Section. Positions start at zero and should be contiguous. |
| section_id | integer | Section id that the Item belongs to. See Section. |
| tap_number | string | Tap number set for the Item. |
| type | string | One of beer, cocktail, flight, food, merchandise, miscellaneous, non_alcoholic, spirit, or wine. |
| updated_at | timestamp | Time at which the Item was last updated. ISO8601 format. |
Beer Item Object
| Property | Type | Description |
|---|---|---|
| abv | float | Alcohol By Volume for the Beer. |
| brewery | string | Name of the brewery. |
| brewery_country | string | Country of the brewery. |
| brewery_location | string | Location of the brewery. |
| cask | boolean | Indicates if the Beer is poured from a cask. |
| custom_abv | float | Customized abv |
| custom_brewery | string | Customized brewery |
| custom_calories | integer | Customized calories |
| custom_description | string | Customized description |
| custom_ibu | float | Customized ibu |
| custom_name | string | Customized name |
| custom_style | string | Customized style |
| ibu | float | International Bitterness Units for the Beer. |
| in_production | boolean | Indicates if this Beer is still in production or not. |
| local | boolean | Indicates if this Beer is local. |
| nitro | boolean | Indicates if this Beer is a nitro pour. |
| original_abv | float | Original abv as defined by Untappd. |
| original_brewery | string | Original brewery as defined by Untappd. |
| original_calories | integer | Original calories as defined by Untappd. |
| original_description | string | Original description as defined by Untappd. |
| original_ibu | float | Original ibu as defined by Untappd. |
| original_label_image | url | Original label_image as defined by Untappd. |
| original_label_image_hd | url | Original label_image_hd as defined by Untappd. |
| original_name | string | Original name as defined by Untappd. |
| original_style | string | Original style as defined by Untappd. |
| rating | float | Untappd rating for the Item. rating is on a scale from 0.0 to 5.0 inclusive. |
| rating_count | integer | Number of rating the Item has received on Untappd. |
| style | string | Style for the Beer. |
| untappd_beer_slug | string | Untappd unique URL slug for the beer. |
| untappd_brewery_id | integer | Untappd identifier for the brewery. |
| untappd_id | integer | Untappd identifier for the beer. |
Spirit Item Object
| Property | Type | Description |
|---|---|---|
| abv | float | Alcohol By Volume for the Spirit. |
| category | string | The type of Spirit e.g. Gin |
| location | string | Location that the Spirit is from. |
| producer | string | The producer of the Spirit. |
| vintage | string | Year or age of the Spirit. |
Wine Item Object
| Property | Type | Description |
|---|---|---|
| abv | float | Alcohol By Volume for the Wine. |
| category | string | Category refers the grapes used in this wine e.g. Cabernet Sauvignon |
| characteristics | string | Characteristics used to describe this wine e.g. Red - Savory and Classic |
| location | string | Location that the Wine is from. |
| producer | string | The producer of the Wine. |
| vintage | string | Year that the Wine was produced. |
Item Full Object
The full Item object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items, and Containers. The following properties will be available in addition to the properties in the regular Item object
| Property | Type | Description |
|---|---|---|
| containers | array | An array of Containers for the Item |
List all items
Returns a list of items belonging to a section.
Request:
curl "http://localhost:3000/api/v1/sections/10/items" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"items": [
{
"id": 64,
"section_id": 10,
"position": 0,
"untappd_id": 4473,
"label_image": "https://beer.untappd.com/labels/4473",
"label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4473",
"original_label_image": "https://beer.untappd.com/labels/4473",
"original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Dublin, County Dublin",
"cask": false,
"nitro": true,
"local": false,
"tap_number": "1",
"rating": "3.76886",
"rating_count": 801407,
"in_production": true,
"untappd_beer_slug": "guinness-guinness-draught",
"untappd_brewery_id": 49,
"name": "Guinness Draught",
"original_name": "Guinness Draught",
"custom_name": null,
"description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"custom_description": null,
"original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"brewery_country": "Ireland",
"custom_brewery": null,
"original_brewery": "Guinness",
"calories": "125",
"custom_calories": null,
"original_calories": "125",
"abv": "4.2",
"custom_abv": null,
"original_abv": "4.2",
"ibu": "45.0",
"custom_ibu": null,
"original_ibu": "45.0",
"created_at": "2023-03-21T13:01:26.220225Z",
"updated_at": "2023-03-21T13:04:40.327469Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
},
{
"id": 65,
"section_id": 10,
"position": 1,
"untappd_id": null,
"label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"original_label_image": "https://beer.untappd.com/labels/",
"original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": null,
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": null,
"rating_count": null,
"in_production": null,
"untappd_beer_slug": null,
"untappd_brewery_id": null,
"name": "Bodegas Campo Viejo Tempranillo",
"original_name": null,
"custom_name": null,
"description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"original_description": null,
"style": null,
"custom_style": null,
"original_style": null,
"brewery": null,
"brewery_country": null,
"custom_brewery": null,
"original_brewery": null,
"calories": null,
"custom_calories": null,
"original_calories": null,
"abv": "13.5",
"custom_abv": null,
"original_abv": null,
"ibu": null,
"custom_ibu": null,
"original_ibu": null,
"created_at": "2023-03-21T13:02:01.593381Z",
"updated_at": "2023-03-21T13:05:28.545371Z",
"type": "wine",
"default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"producer": "Bodegas Campo Viejo",
"vintage": null,
"characteristics": "Red - Savory and Classic",
"category": "Tempranillo",
"location": "Rioja, Spain"
},
{
"id": 66,
"section_id": 10,
"position": 2,
"untappd_id": null,
"label_image": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
"label_image_thumb": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"original_label_image": "https://beer.untappd.com/labels/",
"original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": null,
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": null,
"rating_count": null,
"in_production": null,
"untappd_beer_slug": null,
"untappd_brewery_id": null,
"name": "The Kraken Black Spiced Rum",
"original_name": null,
"custom_name": null,
"description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
"custom_description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
"original_description": null,
"style": null,
"custom_style": null,
"original_style": null,
"brewery": null,
"brewery_country": null,
"custom_brewery": null,
"original_brewery": null,
"calories": null,
"custom_calories": null,
"original_calories": null,
"abv": "35.0",
"custom_abv": null,
"original_abv": null,
"ibu": null,
"custom_ibu": null,
"original_ibu": null,
"created_at": "2023-03-21T13:02:51.158417Z",
"updated_at": "2023-03-21T13:06:38.052956Z",
"type": "spirit",
"default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
"producer": "The Kraken",
"vintage": null,
"characteristics": null,
"category": "Rum - Liqueur - Flavored",
"location": "Caribbean, Rest of World"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/sections/:section_id/items
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| section_id | Integer | true | The section to list the items for. |
Create an item
Creates a new item
Request:
curl "http://localhost:3000/api/v1/sections/10/items" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "untappd_id": 4499 }'
Returns all the items for the section (including the new one) as JSON structured like this:
{
"item": {
"id": 68,
"section_id": 10,
"position": 0,
"untappd_id": 4499,
"label_image": "https://beer.untappd.com/labels/4499",
"label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4499",
"original_label_image": "https://beer.untappd.com/labels/4499",
"original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Windsor, CA",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "4.5019",
"rating_count": 275355,
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"custom_description": null,
"original_description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Company",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Russian River Brewing Company",
"calories": "240",
"custom_calories": null,
"original_calories": "240",
"abv": "8.0",
"custom_abv": null,
"original_abv": "8.0",
"ibu": "100.0",
"custom_ibu": null,
"original_ibu": "100.0",
"created_at": "2023-03-21T14:07:14.266113Z",
"updated_at": "2023-03-21T14:07:14.266113Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
}
HTTP Request
POST https://business.untappd.com/api/v1/sections/:section_id/items
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| section_id | Integer | true | The section to add the item to. |
| type | String | true | One of beer, cocktail, flight, food, merchandise, miscellaneous, non_alcoholic, spirit, wine |
Beer Parameters
The data for the item is automatically populated from the beer database.
Note: This type will accept an array of integers for untappd_id to batch add multiple items at once.
| Parameter | Type | Required | Description |
|---|---|---|---|
| untappd_id | Integer or Array[Integer] | true | A single ID or an array of IDs. untappd_id is the Untappd ID for a given item in the beer database. This is different from an Item ID. e.g. item.untappd_id != item.id |
Spirit Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| abv | float | false | Alcohol By Volume for the Spirit. |
| calories | integer | false | Number of calories for the Spirit. |
| category | string | false | The type of Spirit e.g. Gin |
| description | string | false | Description of the Spirit. |
| location | string | false | Location that the Spirit is from. |
| name | string | false | Name of the Spirit. |
| producer | string | false | The producer of the Spirit. |
| tap_number | string | false | Tap number for the Spirit. |
| vintage | string | false | Year or age of the Spirit. |
Wine Parameters
| Property | Type | Required | Description |
|---|---|---|---|
| abv | float | false | Alcohol By Volume for the Wine. |
| calories | integer | false | Number of calories for the Wine. |
| category | string | false | Category refers the grapes used in this wine e.g. Cabernet Sauvignon |
| characteristics | string | false | Characteristics used to describe this wine e.g. Red - Savory and Classic |
| description | string | false | Description of the Wine. |
| location | string | false | Location that the Wine is from. |
| name | string | false | Name of the Wine. |
| producer | string | false | The producer of the Wine. |
| tap_number | string | false | Tap number for the Wine. |
| vintage | string | false | Year that the Wine was produced. |
Cocktail/Flight/Food/NonAlcoholic Parameters
| Property | Type | Required | Description |
|---|---|---|---|
| calories | integer | false | Number of calories for the Item. |
| description | string | false | Description of the Item. |
| name | string | false | Name of the Item. |
| tap_number | string | false | Tap number for the Item. |
Miscellaneous Parameters
| Property | Type | Required | Description |
|---|---|---|---|
| description | string | false | Description of the Item. |
| name | string | false | Name of the Item. |
| tap_number | string | false | Tap number for the Item. |
Merchandise Parameters
| Property | Type | Required | Description |
|---|---|---|---|
| description | string | false | Description of the Item. |
| name | string | false | Name of the Item. |
Retrieve an item
Retrieve the details of an existing item. You need only supply the unique item identifier that was returned upon item creation.
Request:
curl "http://localhost:3000/api/v1/items/64" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"item": {
"id": 64,
"section_id": 10,
"position": 1,
"untappd_id": 4473,
"label_image": "https://beer.untappd.com/labels/4473",
"label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4473",
"original_label_image": "https://beer.untappd.com/labels/4473",
"original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Dublin, County Dublin",
"cask": false,
"nitro": true,
"local": false,
"tap_number": "1",
"rating": "3.76886",
"rating_count": 801407,
"in_production": true,
"untappd_beer_slug": "guinness-guinness-draught",
"untappd_brewery_id": 49,
"name": "Guinness Draught",
"original_name": "Guinness Draught",
"custom_name": null,
"description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"custom_description": null,
"original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"brewery_country": "Ireland",
"custom_brewery": null,
"original_brewery": "Guinness",
"calories": "125",
"custom_calories": null,
"original_calories": "125",
"abv": "4.2",
"custom_abv": null,
"original_abv": "4.2",
"ibu": "45.0",
"custom_ibu": null,
"original_ibu": "45.0",
"created_at": "2023-03-21T13:01:26.220225Z",
"updated_at": "2023-03-21T14:07:14.275910Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
}
HTTP Request
GET https://business.untappd.com/api/v1/items/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the item. |
Update an item
Updates the specified item by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/items/68" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "item": { "cask": true, "tap_number": 1, "brewery": "Russian River Brewing Co." } }'
Returns JSON structured like this:
{
"item": {
"id": 68,
"section_id": 10,
"position": 0,
"untappd_id": 4499,
"label_image": "https://beer.untappd.com/labels/4499",
"label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4499",
"original_label_image": "https://beer.untappd.com/labels/4499",
"original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Windsor, CA",
"cask": true,
"nitro": false,
"local": false,
"tap_number": "1",
"rating": "4.5019",
"rating_count": 275355,
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"custom_description": null,
"original_description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Co.",
"brewery_country": "United States",
"custom_brewery": "Russian River Brewing Co.",
"original_brewery": "Russian River Brewing Company",
"calories": "240",
"custom_calories": null,
"original_calories": "240",
"abv": "8.0",
"custom_abv": null,
"original_abv": "8.0",
"ibu": "100.0",
"custom_ibu": null,
"original_ibu": "100.0",
"created_at": "2023-03-21T14:07:14.266113Z",
"updated_at": "2023-03-21T14:10:11.540401Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/items/:id
PATCH https://business.untappd.com/api/v1/items/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the item. |
| cask | true/false | false | Is the item designated cask? |
| nitro | true/false | false | Is the item designated nitro? |
| tap_number | String | false | A tap description for the item. e.g. Could be 2 or B. |
| description | String | false | A custom description for the item. If custom_description is null, menus will display the original_description. |
| name | String | false | A custom name for the item. If custom_name is null, menus will display the original_name. |
| style | String | false | A custom style for the item. If custom_style is null, menus will display the original_style. |
| brewery | String | false | A custom brewery for the item. If custom_brewery is null, menus will display the original_brewery. |
Delete an item
Permanently deletes an item. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/items/68" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns the deleted item as JSON structured like this:
{
"item": {
"id": 68,
"section_id": 10,
"position": 0,
"untappd_id": 4499,
"label_image": "https://beer.untappd.com/labels/4499",
"label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4499",
"original_label_image": "https://beer.untappd.com/labels/4499",
"original_label_image_hd": "https://beer.untappd.com/labels/4499?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Windsor, CA",
"cask": true,
"nitro": false,
"local": false,
"tap_number": "1",
"rating": "4.5019",
"rating_count": 275355,
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"custom_description": null,
"original_description": "PLINY THE ELDER - (Double IPA) Brewed with Amarillo, Centennial, CTZ, Cascade, Warrior, and Simcoe hops. Well-balanced with malt, hops, and alcohol. Slightly bitter with aromas of citrus, pine, and floral. ",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Co.",
"brewery_country": "United States",
"custom_brewery": "Russian River Brewing Co.",
"original_brewery": "Russian River Brewing Company",
"calories": "240",
"custom_calories": null,
"original_calories": "240",
"abv": "8.0",
"custom_abv": null,
"original_abv": "8.0",
"ibu": "100.0",
"custom_ibu": null,
"original_ibu": "100.0",
"created_at": "2023-03-21T14:07:14.266113Z",
"updated_at": "2023-03-21T14:10:11.540401Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/items/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The item to be deleted. |
Update item positions
Set the positions of items in a section. Item positions are used to order the items within a section of a published menu on a page.
Important!: When updating item positions, all items for the section must be passed and the positions must start at zero. Use List all items first to get all the items for the section.
Request:
curl "http://localhost:3000/api/v1/sections/10/items/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "items": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'
Returns JSON structured like this:
{
"items": [
{
"id": 2,
"position": 0
},
{
"id": 1,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/sections/:section_id/items/positions
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| section_id | Integer | true | The section to update item positions for. |
| items | Array | true | An Array of Objects. All the items for a section should be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
| id | Integer | true | The item id to update the position for. |
| position | Integer | true | The position to set the item at. Item positions must start at zero. |
Move an item to another section
Move the specified item to another section.
Request:
curl "http://localhost:3000/api/v1/items/64/move" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "item": { "section_id": 3 } }'
Returns JSON structured like this:
{
"item": {
"id": 67,
"section_id": 10,
"position": 0,
"untappd_id": 9681,
"label_image": "https://beer.untappd.com/labels/9681",
"label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/9681",
"original_label_image": "https://beer.untappd.com/labels/9681",
"original_label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Grand Rapids, MI",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "4.38633",
"rating_count": 224308,
"in_production": true,
"untappd_beer_slug": "founders-brewing-co-kentucky-breakfast-stout-kbs",
"untappd_brewery_id": 549,
"name": "Kentucky Breakfast Stout (KBS)",
"original_name": "Kentucky Breakfast Stout (KBS)",
"custom_name": null,
"description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
"custom_description": null,
"original_description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
"style": "Stout - Imperial / Double Coffee",
"custom_style": null,
"original_style": "Stout - Imperial / Double Coffee",
"brewery": "Founders Brewing Co.",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Founders Brewing Co.",
"calories": "340",
"custom_calories": null,
"original_calories": "340",
"abv": "12.0",
"custom_abv": null,
"original_abv": "12.0",
"ibu": "70.0",
"custom_ibu": null,
"original_ibu": "70.0",
"created_at": "2023-03-21T14:14:17.526349Z",
"updated_at": "2023-03-21T14:14:17.526936Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
}
HTTP Request
PATCH https://business.untappd.com/api/v1/items/:id/move
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the item. |
| section_id | Integer | true | The section_id of the section to move the item to. |
Search for item
Search the Untappd beer database for an item.
This is the route that might be used to first find an item to add before calling Create an item with the untappd_id.
Request:
curl "http://localhost:3000/api/v1/items/search?q=pbr" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"items": [
{
"id": null,
"section_id": null,
"position": null,
"untappd_id": 3883,
"label_image": "https://beer.untappd.com/labels/3883",
"label_image_hd": "https://beer.untappd.com/labels/3883?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/3883",
"original_label_image": "https://beer.untappd.com/labels/3883",
"original_label_image_hd": "https://beer.untappd.com/labels/3883?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "San Antonio, TX",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "2.83077",
"rating_count": 379754,
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon",
"original_name": "Pabst Blue Ribbon",
"custom_name": null,
"description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"custom_description": null,
"original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"style": "Lager - American",
"custom_style": null,
"original_style": "Lager - American",
"brewery": "Pabst Brewing Company",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"calories": "140",
"custom_calories": null,
"original_calories": "140",
"abv": "4.8",
"custom_abv": null,
"original_abv": "4.8",
"ibu": "10.0",
"custom_ibu": null,
"original_ibu": "10.0",
"created_at": null,
"updated_at": null,
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
},
{
"id": null,
"section_id": null,
"position": null,
"untappd_id": 3396518,
"label_image": "https://beer.untappd.com/labels/3396518",
"label_image_hd": "https://beer.untappd.com/labels/3396518?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/3396518",
"original_label_image": "https://beer.untappd.com/labels/3396518",
"original_label_image_hd": "https://beer.untappd.com/labels/3396518?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "San Antonio, TX",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "3.90427",
"rating_count": 45210,
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-hard-coffee",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon Hard Coffee",
"original_name": "Pabst Blue Ribbon Hard Coffee",
"custom_name": null,
"description": "Coffee flavored malt beverage. ",
"custom_description": null,
"original_description": "Coffee flavored malt beverage. ",
"style": "Flavored Malt Beverage",
"custom_style": null,
"original_style": "Flavored Malt Beverage",
"brewery": "Pabst Brewing Company",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"calories": "150",
"custom_calories": null,
"original_calories": "150",
"abv": "5.0",
"custom_abv": null,
"original_abv": "5.0",
"ibu": "0.0",
"custom_ibu": null,
"original_ibu": "0.0",
"created_at": null,
"updated_at": null,
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
},
{
"id": null,
"section_id": null,
"position": null,
"untappd_id": 3099757,
"label_image": "https://beer.untappd.com/labels/3099757",
"label_image_hd": "https://beer.untappd.com/labels/3099757?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/3099757",
"original_label_image": "https://beer.untappd.com/labels/3099757",
"original_label_image_hd": "https://beer.untappd.com/labels/3099757?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "San Antonio, TX",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "3.11095",
"rating_count": 6662,
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-extra",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon Extra",
"original_name": "Pabst Blue Ribbon Extra",
"custom_name": null,
"description": "",
"custom_description": null,
"original_description": "",
"style": "Lager - American",
"custom_style": null,
"original_style": "Lager - American",
"brewery": "Pabst Brewing Company",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"calories": "195",
"custom_calories": null,
"original_calories": "195",
"abv": "6.5",
"custom_abv": null,
"original_abv": "6.5",
"ibu": "0.0",
"custom_ibu": null,
"original_ibu": "0.0",
"created_at": null,
"updated_at": null,
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/items/search
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| q | String | true | The query string used to search for an item. |
Share an item
Share an item to Twitter or Facebook.
Request:
curl "http://localhost:3000/api/v1/items/2/share?social_channel=twitter" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Response is a 200 OK http status code with an empty object json if there are no errors:
{}
If the social channel is not linked on the user's profile you will get a response like this:
{
"error": {
"status": 400,
"title": "social channel not linked",
"detail": "The social channel is not linked. The user must link their twitter account before utilizing it.",
"code": "Errors::SocialChannelNotLinkedError",
"social_channel": "twitter",
"item_id": 2,
"redirect_to": "/locations/3/social"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/items/:item_id/share
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| item_id | String | true | The item to share. |
| social_channel | facebook/twitter | true | The social channel to share to. |
Sort items
Sort the items in a section by the sorter method. This sort is persistent; --it will set the position property on each item.
Request:
curl "http://localhost:3000/api/v1/sections/1/items/sort?sort_by=alphabetically" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Response is all the items for the section with updated and sorted position:
{
"items": [
{
"id": 65,
"section_id": 10,
"position": 0,
"untappd_id": null,
"label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"original_label_image": "https://beer.untappd.com/labels/",
"original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": null,
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": null,
"rating_count": null,
"in_production": null,
"untappd_beer_slug": null,
"untappd_brewery_id": null,
"name": "Bodegas Campo Viejo Tempranillo",
"original_name": null,
"custom_name": null,
"description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"original_description": null,
"style": null,
"custom_style": null,
"original_style": null,
"brewery": null,
"brewery_country": null,
"custom_brewery": null,
"original_brewery": null,
"calories": null,
"custom_calories": null,
"original_calories": null,
"abv": "13.5",
"custom_abv": null,
"original_abv": null,
"ibu": null,
"custom_ibu": null,
"original_ibu": null,
"created_at": "2023-03-21T13:02:01.593381Z",
"updated_at": "2023-03-21T14:14:17.533411Z",
"type": "wine",
"default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"producer": "Bodegas Campo Viejo",
"vintage": null,
"characteristics": "Red - Savory and Classic",
"category": "Tempranillo",
"location": "Rioja, Spain"
},
{
"id": 64,
"section_id": 10,
"position": 1,
"untappd_id": 4473,
"label_image": "https://beer.untappd.com/labels/4473",
"label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4473",
"original_label_image": "https://beer.untappd.com/labels/4473",
"original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Dublin, County Dublin",
"cask": false,
"nitro": true,
"local": false,
"tap_number": "1",
"rating": "3.76886",
"rating_count": 801407,
"in_production": true,
"untappd_beer_slug": "guinness-guinness-draught",
"untappd_brewery_id": 49,
"name": "Guinness Draught",
"original_name": "Guinness Draught",
"custom_name": null,
"description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"custom_description": null,
"original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"brewery_country": "Ireland",
"custom_brewery": null,
"original_brewery": "Guinness",
"calories": "125",
"custom_calories": null,
"original_calories": "125",
"abv": "4.2",
"custom_abv": null,
"original_abv": "4.2",
"ibu": "45.0",
"custom_ibu": null,
"original_ibu": "45.0",
"created_at": "2023-03-21T13:01:26.220225Z",
"updated_at": "2023-03-21T14:14:17.533411Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/sections/:section_id/items/sort
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| section_id | String | true | The section to sort items for. |
| sort_by | String | true | The method by which to sort the items. |
Note: When ordering items with the same brewery, sort_by: brewery will first sort alphabetically by brewery then will fall back to sorting alphabetically by item name.
Sorter Methods
| sort_by | Description |
|---|---|
| tap_number | Sort by Tap Number |
| alphabetically | A-Z |
| reverse_alphabetically | Z-A |
| brewery | A-Z |
| style | A-Z |
| abv | 0-100 |
| reverse_abv | 100-0 |
Locations
List all locations
List the locations belonging to the currently authorized user.
curl "http://localhost:3000/api/v1/locations" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"locations": [
{
"id": 3,
"name": "Pied Piper",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"full_address": "21 S Front St, , Wilmington, North Carolina, 28401, United States",
"address1": "21 S Front St",
"address2": "",
"city": "Wilmington",
"postcode": "28401",
"region": "North Carolina",
"country": "United States",
"latitude": "34.2346553",
"longitude": "-77.9482581",
"website": "http://business.untappd.com",
"contact_email": "[email protected]",
"phone": "910-333-1245",
"untappd_venue_id": 4174364,
"created_at": "2016-06-16T19:29:59Z",
"updated_at": "2016-06-16T19:50:32Z",
"business_id": 3,
"cross_streets": "",
"neighborhood": "Downtown Wilmington",
"timezone": "Eastern Time (US & Canada)",
"tz_offset": -4,
"directions": "Turn right at the fork.",
"description": "Erlich Bachman's Incubator (A.K.A his House)",
"in_business_since": 2021,
"number_of_taps": null,
"food_served": "food_served_yes",
"growler_filling_station": "growler_filling_station_no",
"crowler_filling_station": "crowler_filling_station_no",
"kegs": "kegs_yes",
"hours": [
{
"id": 1,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "monday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.508Z",
"updated_at": "2020-02-17T20:16:23.508Z"
},
{
"id": 2,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "tuesday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.511Z",
"updated_at": "2020-02-17T20:16:23.511Z"
},
{
"id": 3,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "wednesday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.615Z",
"updated_at": "2020-02-17T20:16:23.615Z"
},
{
"id": 4,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "thursday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.617Z",
"updated_at": "2020-02-17T20:16:23.617Z"
},
{
"id": 5,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "friday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.619Z",
"updated_at": "2020-02-17T20:16:23.619Z"
},
{
"id": 6,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "saturday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.621Z",
"updated_at": "2020-02-17T20:16:23.621Z"
},
{
"id": 7,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "sunday",
"location_id": 3,
"created_at": "2020-02-17T20:16:23.623Z",
"updated_at": "2020-02-17T20:16:23.623Z"
}
],
"nitro_on_tap": "nitro_on_tap_no",
"cask_on_tap": "cask_on_tap_no",
"serve_wine": "serve_wine_yes",
"serve_cocktails": "serve_cocktails_yes",
"serve_liquor": "serve_liquor_yes",
"outdoor_seating": "outdoor_seating_yes",
"pet_friendly": "pet_friendly_yes",
"contact_name": "Starbuck",
"contact_phone": "(910) 333 - 1245",
"published_at_untappd": null,
"published_at_embed": null,
"published_at_facebook": null,
"published_count": 0,
"currency": "USD",
"currency_symbol": "$",
"suspended": false,
"accepted_payment_types": [
"visa",
"master_card",
"american_express",
"discover",
"check"
],
"twitter_linked": false,
"facebook_post_page": false,
"facebook_menu_page": false,
"country_name": "United States",
"website_url": "http://business.untappd.com"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations
Retrieve a location
Retrieve the information of an existing location. You need only supply the unique location identifier.
curl "http://localhost:3000/api/v1/locations/1234" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"location": {
"id": 1234,
"name": "Deadpool's Pizza & Pint ",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"full_address": "21 S Front St, , Wilmington, North Carolina, 28401, US",
"address1": "21 S Front St",
"address2": "",
"city": "Wilmington",
"postcode": "28401",
"region": "North Carolina",
"country": "US",
"latitude": "34.2346598",
"longitude": "-77.9482096",
"website": "business.untappd.com",
"contact_email": "[email protected]",
"phone": "910 292 4336",
"untappd_venue_id": 8943870,
"created_at": "2019-05-13T18:10:26.419925Z",
"updated_at": "2020-08-12T01:50:15.296375Z",
"cross_streets": null,
"neighborhood": null,
"timezone": "Eastern Time (US & Canada)",
"tz_offset": -4,
"directions": null,
"description": null,
"in_business_since": null,
"number_of_taps": null,
"food_served": "unknown",
"growler_filling_station": "unknown",
"hours": [
{
"id": 181211,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "monday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.443Z",
"updated_at": "2019-05-13T18:10:26.443Z"
},
{
"id": 181212,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "tuesday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.446Z",
"updated_at": "2019-05-13T18:10:26.446Z"
},
{
"id": 181213,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "wednesday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.448Z",
"updated_at": "2019-05-13T18:10:26.448Z"
},
{
"id": 181214,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "thursday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.451Z",
"updated_at": "2019-05-13T18:10:26.451Z"
},
{
"id": 181215,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "friday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.453Z",
"updated_at": "2019-05-13T18:10:26.453Z"
},
{
"id": 181216,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "saturday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.456Z",
"updated_at": "2019-05-13T18:10:26.456Z"
},
{
"id": 181217,
"always_open": false,
"closed": false,
"open_at": "2000-01-01T08:00:00.000Z",
"close_at": "2000-01-01T18:00:00.000Z",
"day": "sunday",
"location_id": 25592,
"created_at": "2019-05-13T18:10:26.458Z",
"updated_at": "2019-05-13T18:10:26.458Z"
}
],
"crowler_filling_station": "unknown",
"kegs": "unknown",
"nitro_on_tap": "unknown",
"cask_on_tap": "unknown",
"serve_wine": "unknown",
"serve_cocktails": "unknown",
"serve_liquor": "unknown",
"outdoor_seating": "unknown",
"pet_friendly": "unknown",
"child_friendly": "unknown",
"smoke_friendly": "unknown",
"contact_name": "Edward",
"contact_phone": "910 292 4336",
"published_at_untappd": "2020-08-04T23:03:01.721599Z",
"published_at_embed": "2020-08-12T01:51:00.431259Z",
"published_at_facebook": "2020-08-12T01:51:00.431259Z",
"published_count": 3,
"currency": "USD",
"currency_symbol": "$",
"accepted_payment_types": [],
"twitter_linked": false,
"facebook_post_page": false,
"facebook_menu_page": false,
"country_name": "United States of America",
"website_url": "http://business.untappd.com",
"mailing_address1": null,
"mailing_address2": null,
"mailing_city": null,
"mailing_postcode": null,
"mailing_region": null,
"mailing_country": null
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the location. |
Update a location
Updates the specified location by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/locations/1" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "location": { "mailing_address1": "123 Bourbon St" } }'
Returns JSON structured like this:
{
"location": {
"id": 1,
"name": "Pizzas & Pints",
"country": "US",
"address1": "21 S Front St",
"city": "Wilmington",
"region": "North Carolina",
"timezone": "Eastern Time (US & Canada)",
"untappd_venue_id": 8943870,
"in_business_since": null,
"number_of_taps": null,
"address2": "",
"postcode": "28401",
"latitude": "34.2346598",
"longitude": "-77.9482096",
"website": "business.untappd.com",
"contact_email": "[email protected]",
"phone": "910 292 4336",
"created_at": "2019-05-13T18:10:26.419Z",
"updated_at": "2020-08-12T14:11:23.037Z",
"cross_streets": null,
"neighborhood": null,
"directions": null,
"description": null,
"food_served": "unknown",
"growler_filling_station": "unknown",
"crowler_filling_station": "unknown",
"kegs": "unknown",
"nitro_on_tap": "unknown",
"cask_on_tap": "unknown",
"serve_wine": "unknown",
"serve_cocktails": "unknown",
"outdoor_seating": "unknown",
"pet_friendly": "unknown",
"facebook_menu_page_id": null,
"facebook_menu_page_name": null,
"facebook_menu_page_access_token": null,
"facebook_post_page_id": null,
"facebook_post_page_name": null,
"facebook_post_page_access_token": null,
"twitter_id": null,
"twitter_access_token": null,
"twitter_access_token_secret": null,
"twitter_username": null,
"logo_file_name": null,
"logo_content_type": null,
"logo_file_size": null,
"logo_updated_at": null,
"display_logo_on_menu": true,
"contact_name": "Thor",
"contact_phone": "910 292 4336",
"published_at_untappd": "2020-08-04T23:03:01.721Z",
"serve_liquor": "unknown",
"currency": "USD",
"child_friendly": "unknown",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"published_at_embed": "2020-08-12T01:51:00.431Z",
"published_at_facebook": "2020-08-12T01:51:00.431Z",
"pushed_untappd_at": "2020-08-12T01:51:00.431Z",
"pushed_embed_at": "2020-08-12T01:51:00.431Z",
"pushed_facebook_at": "2020-08-12T01:51:00.431Z",
"untappd_venue_access_token": "EE1A0A290BCA3AFE0DD8279BCE680214D52F8AF8",
"automatic_facebook_event_sync": false,
"digital_board_last_loaded_at": "2020-08-11T20:16:09.935Z",
"website_embed_last_seen_at": null,
"menu_last_updated_at": "2020-08-04T23:02:43.464Z",
"digital_board_version": 2,
"needs_touch": null,
"print_version": 2,
"business_type": "bar",
"first_publish_at": "2019-06-24T17:43:06.390Z",
"festival_start_on": null,
"festival_end_on": null,
"organization_id": null,
"mailing_address1": "123 Bourbon St",
"mailing_address2": null,
"mailing_city": null,
"mailing_postcode": null,
"mailing_region": null,
"mailing_country": null,
"smoke_friendly": "unknown"
},
"errors": null
}
HTTP Request
PUT https://business.untappd.com/api/v1/locations/:id
PATCH https://business.untappd.com/api/v1/locations/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the location. |
| mailing_address1 | String | false | The location mailing street address. |
| mailing_address2 | String | false | The location mailing address (PO Box, Apt, Ste, etc.) |
| mailing_city | String | false | The location mailing city |
| mailing_postcode | String | false | The location mailing postcode |
| mailing_region | String | false | The location mailing state/region |
| mailing_country | String | false | The location mailing country |
Update a location's details
Updates the specified location's details by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/locations/1/details" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "currency": "USD", "description": "We really like beer here!", "nitro_on_tap": 1, "categories": ["55a59bace4b013909087cb36"] }'
Returns JSON structured like this:
{
"location": {
"id": 1,
"name": "Pizzas & Pints",
"country": "US",
"address1": "21 S Front St",
"city": "Wilmington",
"region": "North Carolina",
"timezone": "Eastern Time (US & Canada)",
"untappd_venue_id": 8943870,
"in_business_since": null,
"number_of_taps": null,
"address2": "",
"postcode": "28401",
"latitude": "34.2346598",
"longitude": "-77.9482096",
"website": "business.untappd.com",
"contact_email": "[email protected]",
"phone": "910 292 4336",
"created_at": "2019-05-13T18:10:26.419Z",
"updated_at": "2020-08-12T14:11:23.037Z",
"cross_streets": null,
"neighborhood": null,
"directions": null,
"description": "We really like beer here!",
"food_served": "unknown",
"growler_filling_station": "unknown",
"crowler_filling_station": "unknown",
"kegs": "unknown",
"nitro_on_tap": "yes",
"cask_on_tap": "unknown",
"serve_wine": "unknown",
"serve_cocktails": "unknown",
"outdoor_seating": "unknown",
"pet_friendly": "unknown",
"facebook_menu_page_id": null,
"facebook_menu_page_name": null,
"facebook_menu_page_access_token": null,
"facebook_post_page_id": null,
"facebook_post_page_name": null,
"facebook_post_page_access_token": null,
"twitter_id": null,
"twitter_access_token": null,
"twitter_access_token_secret": null,
"twitter_username": null,
"logo_file_name": null,
"logo_content_type": null,
"logo_file_size": null,
"logo_updated_at": null,
"display_logo_on_menu": true,
"contact_name": "Thor",
"contact_phone": "910 292 4336",
"published_at_untappd": "2020-08-04T23:03:01.721Z",
"serve_liquor": "unknown",
"currency": "USD",
"child_friendly": "unknown",
"formatted_address": "21 S Front St, Wilmington, NC 28401, USA",
"published_at_embed": "2020-08-12T01:51:00.431Z",
"published_at_facebook": "2020-08-12T01:51:00.431Z",
"pushed_untappd_at": "2020-08-12T01:51:00.431Z",
"pushed_embed_at": "2020-08-12T01:51:00.431Z",
"pushed_facebook_at": "2020-08-12T01:51:00.431Z",
"untappd_venue_access_token": "EE1A0A290BCA3AFE0DD8279BCE680214D52F8AF8",
"automatic_facebook_event_sync": false,
"digital_board_last_loaded_at": "2020-08-11T20:16:09.935Z",
"website_embed_last_seen_at": null,
"menu_last_updated_at": "2020-08-04T23:02:43.464Z",
"digital_board_version": 2,
"needs_touch": null,
"print_version": 2,
"business_type": "bar",
"first_publish_at": "2019-06-24T17:43:06.390Z",
"festival_start_on": null,
"festival_end_on": null,
"organization_id": null,
"mailing_address1": "123 Bourbon St",
"mailing_address2": null,
"mailing_city": null,
"mailing_postcode": null,
"mailing_region": null,
"mailing_country": null,
"smoke_friendly": "unknown"
},
"errors": null
}
HTTP Request
PUT https://business.untappd.com/api/v1/locations/:id/details
PATCH https://business.untappd.com/api/v1/locations/:id/details
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the location. |
| timezone | String | false | The location timezone. |
| currency | String | false | The location accepted currency |
| description | String | false | The location description |
| food_served | String | false | The food served at the location |
| growler_filling_station | String | false | Whether the location fills growlers |
| crowler_filling_station | String | false | Whether the location fills crowlers |
| kegs | String | false | Whether the location carries kegs |
| nitro_on_tap | String | false | Whether the location has nitro on tap |
| cask_on_tap | String | false | Whether the location has casks on tap |
| serve_wine | String | false | Whether the location serves wine |
| serve_liquor | String | false | Whether the location serves liquor |
| serve_cocktails | String | false | Whether the location serves cocktails |
| categories | String[] | false | The location categories; minimum 1 required, maximum 4 allowed. Passing an empty array will not add or remove any existing categories. |
| accepted_payment_types | String[] | false | The location accepted payment types |
Menu Announcements
- A location has many menu announcements
List all menu announcements
Returns a list of menu announcements belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/3/menu_announcements" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="
Returns JSON structured like this:
{
"menu_announcements": {
"current": [
{
"id": 1,
"location_id": 3,
"created_at": "2016-10-12T13:08:57Z",
"updated_at": "2016-10-12T13:08:57Z",
"content": "This is an announcement that goes out immediately.",
"period": "now",
"canceled": false,
"next_publish_at": null,
"last_published_at": "2016-10-12T13:08:57Z",
"type": "MenuAnnouncement",
"post_to_facebook": false,
"post_to_twitter": false,
"display_on_embed_menu": true,
"display_on_print_menu": false,
"display_on_digital_board": false
}
],
"upcoming": [
{
"id": 2,
"location_id": 3,
"created_at": "2016-10-12T13:27:27Z",
"updated_at": "2016-10-12T13:27:27Z",
"content": "This is an announcement that goes out immediately.",
"period": "once",
"canceled": false,
"next_publish_at": "2016-10-15T17:21:51Z",
"last_published_at": null,
"type": "MenuAnnouncement",
"post_to_facebook": false,
"post_to_twitter": false,
"display_on_embed_menu": true,
"display_on_print_menu": false,
"display_on_digital_board": false
}
],
"weekly": [
{
"id": 3,
"location_id": 3,
"created_at": "2016-10-12T13:28:07Z",
"updated_at": "2016-10-12T13:28:07Z",
"content": "This is an announcement that goes out immediately.",
"period": "weekly",
"canceled": false,
"next_publish_at": "2016-11-15T18:21:51Z",
"last_published_at": null,
"type": "MenuAnnouncement",
"post_to_facebook": false,
"post_to_twitter": false,
"display_on_embed_menu": true,
"display_on_print_menu": false,
"display_on_digital_board": false
}
]
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/menu_announcements
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
Create a menu announcement
Creates a new menu announcement.
Request:
curl "http://localhost:3000/api/v1/locations/3/menu_announcements" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko=" \
-H "Content-Type: application/json" \
-d '{ "menu_announcement": { "content": "This is an announcement that goes out once per week.", "period": "weekly", "next_publish_at": "2016-11-15T13:21:51Z", "display_on_embed_menu": true } }'
Returns JSON structured like this:
{
"menu_announcement": {
"id": 3,
"location_id": 3,
"created_at": "2016-10-12T13:28:07Z",
"updated_at": "2016-10-12T13:28:07Z",
"content": "This is an announcement that goes out once per week.",
"period": "weekly",
"canceled": false,
"next_publish_at": "2016-11-15T18:21:51Z",
"last_published_at": null,
"type": "MenuAnnouncement",
"post_to_facebook": false,
"post_to_twitter": false,
"display_on_embed_menu": true,
"display_on_print_menu": false,
"display_on_digital_board": false
}
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/menu_announcements
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
| content | String | true | The main content for the announcement. ex. "Join us for happy hour at 3pm!" |
| next_publish_at | String | true | The date and time the announcement should be published at. Date time format must be iso8601. Not necessary when supplying period=now. |
| period | String now / once / weekly |
true | When the announcement should be posted. "now" posts the announcement immediately once. "once" posts the announcement at a future time. "weekly" is a reoccurring announcement that will post every week at the given next_publish_at date and time. |
| display_on_embed_menu | Boolean | false | Indicates that the announcement should be displayed on the embedded menus. |
| display_on_print_menu | Boolean | false | Indicates that the announcement should be displayed on the print menus. |
| display_on_digital_board | Boolean | false | Indicates that the announcement should be displayed on the digital boards. |
Cancel a menu announcement
Permanently deletes a menu announcement. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/menu_announcements/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="
Returns the canceled menu announcement as JSON structured like this. Notice
canceledis nowtrue.):
{
"menu_announcement": {
"id": 1,
"location_id": 3,
"created_at": "2016-10-12T13:08:57Z",
"updated_at": "2016-10-12T13:57:13Z",
"content": "This is an announcement that goes out immediately.",
"period": "now",
"canceled": true,
"next_publish_at": null,
"last_published_at": "2016-10-12T13:08:57Z",
"type": "MenuAnnouncement",
"post_to_facebook": false,
"post_to_twitter": false,
"display_on_embed_menu": true,
"display_on_print_menu": false,
"display_on_digital_board": false
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/menu_announcements/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The menu announcement to be canceled. |
Menu History
Menu history, or more accurately Item history, is useful for restoring items that were previously on a menu but have since been removed.
List historical items
Returns a list of historical items.
Request:
curl --include "http://localhost:3000/api/v1/locations/3/historical_items" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
'curl --include' switch will display the response http headers:
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Link: <http://localhost:3000/api/v1/locations/3/historical_items?page=2>; rel="last", <http://localhost:3000/api/v1/locations/3/historical_items?page=2>; rel="next"
Per-Page: 14
Total: 15
Content-Type: application/json; charset=utf-8
ETag: W/"d4882f3a872691d58dce3658c3250d40"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: d5c4f589-7ef4-4cb1-a050-44e34f851625
X-Runtime: 0.051484
Vary: Origin
Transfer-Encoding: chunked
Returns JSON structured like this:
{
"historical_items": [
{
"id": 4,
"location_id": 3,
"item": {
"id": 2,
"abv": "27.0",
"ibu": "0.0",
"cask": false,
"name": "Samuel Adams Utopias",
"nitro": false,
"style": "Strong Ale - American",
"rating": "4.47778",
"brewery": "Boston Beer Company",
"position": 0,
"containers": [
{
"table": {
"id": 1,
"price": "15.99",
"position": 0,
"item_id": 2,
"_track_by": 1,
"created_at": "2016-11-08T16:31:11Z",
"updated_at": "2016-11-08T16:31:26Z",
"container_size": {
"table": {
"id": 12,
"name": "8oz Draft",
"position": 10,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:52:06Z"
},
"modifiable": true
},
"container_size_id": 12
},
"modifiable": true
},
{
"table": {
"id": 2,
"price": "18.99",
"position": 1,
"item_id": 2,
"_track_by": 2,
"created_at": "2016-11-08T16:31:34Z",
"updated_at": "2016-11-08T16:31:38Z",
"container_size": {
"table": {
"id": 16,
"name": "16oz Draft",
"position": 18,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:52:06Z"
},
"modifiable": true
},
"container_size_id": 16
},
"modifiable": true
}
],
"created_at": "2016-11-08T15:01:54Z",
"section_id": 1,
"tap_number": null,
"untappd_id": 19004,
"updated_at": "2016-11-08T16:31:38Z",
"custom_name": null,
"description": "Truly the epitome of brewing's two thousand year evolution, Samuel Adams Utopias® offers a flavor not just unlike any other beer but unlike any other beverage in the world. Each release is a blend of batches, some having been aged up to 16 years in the barrel room of our Boston Brewery, in a variety of woods. We aged a portion of the beer in hand-selected, single-use bourbon casks from the award-winning Buffalo Trace Distillery. Some of the latest batches also spent time in Portuguese muscatel finishing casks, as well as sherry, brandy and Cognac casks. This flavorful, slightly fruity brew has a sweet, malty flavor that is reminiscent of a deep, rich vintage port, fine cognac or aged sherry.",
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
"custom_style": null,
"in_production": true,
"original_name": "Samuel Adams Utopias",
"custom_brewery": null,
"original_style": "Strong Ale - American",
"brewery_location": "Boston, MA",
"original_brewery": "Boston Beer Company",
"untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
"custom_description": null,
"untappd_brewery_id": 157,
"original_description": "Truly the epitome of brewing's two thousand year evolution, Samuel Adams Utopias® offers a flavor not just unlike any other beer but unlike any other beverage in the world. Each release is a blend of batches, some having been aged up to 16 years in the barrel room of our Boston Brewery, in a variety of woods. We aged a portion of the beer in hand-selected, single-use bourbon casks from the award-winning Buffalo Trace Distillery. Some of the latest batches also spent time in Portuguese muscatel finishing casks, as well as sherry, brandy and Cognac casks. This flavorful, slightly fruity brew has a sweet, malty flavor that is reminiscent of a deep, rich vintage port, fine cognac or aged sherry."
},
"added_at": "2016-11-08T15:01:54Z",
"changed_at": "2016-11-08T16:31:41Z",
"change_type": "change_type_removed",
"created_at": "2016-11-08T16:31:41Z",
"updated_at": "2016-11-08T16:31:41Z"
},
{
"id": 3,
"location_id": 3,
"item": {
"id": 3,
"abv": "4.3",
"ibu": "45.0",
"cask": false,
"name": "Guinness Draught",
"nitro": false,
"style": "Stout - Irish Dry",
"rating": "3.81587",
"brewery": "Guinness",
"position": 0,
"containers": [],
"created_at": "2016-11-08T15:02:12Z",
"section_id": 1,
"tap_number": null,
"untappd_id": 4473,
"updated_at": "2016-11-08T15:02:12Z",
"custom_name": null,
"description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\n\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\n\nPure beauty. Pure GUINNESS.\n\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\n\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
"custom_style": null,
"in_production": true,
"original_name": "Guinness Draught",
"custom_brewery": null,
"original_style": "Stout - Irish Dry",
"brewery_location": "Dublin 8",
"original_brewery": "Guinness",
"untappd_beer_slug": "guinness-guinness-draught",
"custom_description": null,
"untappd_brewery_id": 49,
"original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\n\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\n\nPure beauty. Pure GUINNESS.\n\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\n\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C"
},
"added_at": "2016-11-08T15:02:12Z",
"changed_at": "2016-11-08T16:31:07Z",
"change_type": "change_type_removed",
"created_at": "2016-11-08T16:31:07Z",
"updated_at": "2016-11-08T16:31:07Z"
},
{
"id": 2,
"location_id": 3,
"item": {
"id": 4,
"abv": "8.0",
"ibu": "100.0",
"cask": true,
"name": "Pliny the Elder",
"nitro": false,
"style": "IPA - Imperial / Double",
"rating": "4.5657",
"brewery": "Russian River Brewing Co.",
"position": 0,
"containers": [],
"created_at": "2016-11-08T15:08:49Z",
"section_id": 1,
"tap_number": "1",
"untappd_id": 4499,
"updated_at": "2016-11-08T16:18:51Z",
"custom_name": null,
"description": "All the rest...",
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
"custom_style": null,
"in_production": true,
"original_name": "Pliny the Elder",
"custom_brewery": "Russian River Brewing Co.",
"original_style": "IPA - Imperial / Double",
"brewery_location": "Santa Rosa, CA",
"original_brewery": "Russian River Brewing Company",
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"custom_description": "All the rest...",
"untappd_brewery_id": 5143,
"original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew."
},
"added_at": "2016-11-08T15:08:49Z",
"changed_at": "2016-11-08T16:22:53Z",
"change_type": "change_type_removed",
"created_at": "2016-11-08T16:22:53Z",
"updated_at": "2016-11-08T16:22:53Z"
},
{
"id": 1,
"location_id": 3,
"item": {
"id": 1,
"abv": "4.6",
"ibu": "0.0",
"cask": false,
"name": "Pabst Blue Ribbon",
"nitro": false,
"style": "Lager - North American Adjunct",
"rating": "2.7616",
"brewery": "Pabst Brewing Company",
"position": 0,
"containers": [],
"created_at": "2016-11-07T19:09:47Z",
"section_id": 1,
"tap_number": null,
"untappd_id": 3883,
"updated_at": "2016-11-07T19:18:59Z",
"custom_name": null,
"description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
"custom_style": null,
"in_production": true,
"original_name": "Pabst Blue Ribbon",
"custom_brewery": null,
"original_style": "Lager - North American Adjunct",
"brewery_location": "Woodridge, IL",
"original_brewery": "Pabst Brewing Company",
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
"custom_description": null,
"untappd_brewery_id": 963,
"original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893."
},
"added_at": "2016-11-07T19:09:47Z",
"changed_at": "2016-11-08T15:01:50Z",
"change_type": "change_type_removed",
"created_at": "2016-11-08T15:01:50Z",
"updated_at": "2016-11-08T15:01:50Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/historical_items?page=:page_number
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location to retrieve historical items for. |
| page | Integer | false | The page number to to view. Only 14 results are returned per page. Pagination information will be the Link header as specified by RFC-5988. See the header output to the right. |
| q | String | false | A query param to search for historical items by name. ie. ?q=blue would return a list including the beer "Labatt Blue". |
Restore a historical item
When an item is removed from a menu it becomes a historical item. You can use the restore route to put a historical item back onto a menu.
The response is a newly created item (based on the historical item) to the specified section.
Request:
curl "http://localhost:3000/api/v1/historical_items/2/restore" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{"section_id": 1}'
Returns JSON structured like this:
{
"item": {
"id": 5,
"section_id": 1,
"position": 0,
"untappd_id": 4499,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
"brewery_location": "Santa Rosa, CA",
"abv": "8.0",
"ibu": "100.0",
"cask": true,
"nitro": false,
"tap_number": "1",
"rating": "4.5657",
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "All the rest...",
"custom_description": "All the rest...",
"original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Co.",
"custom_brewery": "Russian River Brewing Co.",
"original_brewery": "Russian River Brewing Company",
"created_at": "2016-11-08T16:34:04Z",
"updated_at": "2016-11-08T16:34:04Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/historical_items/:id/restore
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the historical item to be restored. |
| section_id | Integer | true | The id of an existing section to which the item will be restored. |
Delete a historical item
Permanently deletes a historical item from the Menu History. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/historical_items/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns the deleted item as JSON structured like this:
{
"historical_item": {
"id": 1,
"location_id": 3,
"item": {
"id": 1,
"abv": "4.6",
"ibu": "0.0",
"cask": false,
"name": "Pabst Blue Ribbon",
"nitro": false,
"style": "Lager - North American Adjunct",
"rating": "2.7616",
"brewery": "Pabst Brewing Company",
"position": 0,
"containers": [],
"created_at": "2016-11-07T19:09:47Z",
"section_id": 1,
"tap_number": null,
"untappd_id": 3883,
"updated_at": "2016-11-07T19:18:59Z",
"custom_name": null,
"description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
"custom_style": null,
"in_production": true,
"original_name": "Pabst Blue Ribbon",
"custom_brewery": null,
"original_style": "Lager - North American Adjunct",
"brewery_location": "Woodridge, IL",
"original_brewery": "Pabst Brewing Company",
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
"custom_description": null,
"untappd_brewery_id": 963,
"original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893."
},
"added_at": "2016-11-07T19:09:47Z",
"changed_at": "2016-11-08T15:01:50Z",
"change_type": "change_type_removed",
"created_at": "2016-11-08T15:01:50Z",
"updated_at": "2016-11-08T15:01:50Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/historical_items/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the historical item to be deleted. |
Menus
- A location has many menus.
- A menu belongs to a location.
- A menu has many sections.
Menu Object
| Property | Type | Description |
|---|---|---|
| created_at | timestamp | Time at which the Menu was created. ISO8601 format. |
| description | string | Description of the Menu |
| draft | boolean | If the Menu is in a draft status. deprecated |
| footer | string | Footer text that is displayed in the footer of the Menu. deprecated |
| id | integer | Unique identifier for the Menu |
| location_id | integer | Location id that the Menu belongs to |
| name | string | Name of the Menu |
| position | integer | The position of the Menu in the list of Menus for the Location. Positions start at zero and should be contiguous. |
| push_notification_frequency | string | One of real_time, daily, or weekly read only |
| show_price_on_untappd | boolean | Whether price information should be shown on the Untappd App. |
| unpublished | boolean | Indicates if the Menu is in an unpublished state. Unpublished menus are hidden from the public. |
| updated_at | timestamp | Time at which the Menu was last updated. ISO8601 format. |
| uuid | string | A unique identifier for the Menu read only |
Menu Full Object
The full Menu object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items,and Containers. The following properties will be available in addition to the properties in the regular Menu object
| Property | Type | Description |
|---|---|---|
| sections | array | An array of Sections for the Menu |
| on_deck_section | Sections | The OnDeckSection for the Menu |
List all menus
Returns a list of menus belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/5/menus" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menus": [
{
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/menus
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
Create/Update multiple menus
Create/Update (upsert) multiple menus in a single request. A menu with an id will be updated. A menu without an id will be created as a new menu.
The same thing goes for the sections. A section with an id will be updated. A section without an id will be created as a new section.
Important! Any existing sections, items, and/or containers not provided will be deleted. This is essentially a hard reset from the current menu data to the data in the request.
Also, note that menus in our system default to unpublished: true ie. "not published". If you would like your menu to be published out to our publishers (including your website's embedded menus) you must set unpublished: false in the request; as it is in the example to the right.
Note: If your request takes longer than 30 seconds to process you will receive "Request Timeout" as a response. If this is the case, try using the background form parameter.
Request:
curl "http://localhost:3000/api/v1/locations/3/menus" \
-X PUT \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{"menus":[{"unpublished":false,"name":"Draft Beer List","description":"All the draft beers.","footer":"Heavy vs. Light or Good vs. Evil? You Decide.","sections":[{"name":"Other beers","description":"Our beers that are not dark or light.","items":[{"untappd_id":4499,"cask":true,"nitro":false,"description":"A custom item description","tap_number":4,"containers":[{"container_size_id":6,"price":3.99}]},{"untappd_id":3883,"cask":false,"nitro":true,"description":"A PBR beer","tap_number":5,"containers":[{"container_size_id":6,"price":3.99}]}]}]}]}'
Returns JSON structured like this:
{
"menus": [
{
"id": 3,
"location_id": 3,
"uuid": "c2402f2e-90e5-40cd-a455-68e45cf7f70c",
"name": "Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"sections": [
{
"id": 7,
"menu_id": 3,
"position": 0,
"name": "Other beers",
"description": "Our beers that are not dark or light.",
"type": "Section",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"items": [
{
"id": 10,
"section_id": 7,
"position": 0,
"untappd_id": 4499,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
"brewery_location": "Santa Rosa, CA",
"abv": "8.0",
"ibu": "100.0",
"cask": true,
"nitro": false,
"tap_number": "4",
"rating": "4.5657",
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "A custom item description",
"custom_description": "A custom item description",
"original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Company",
"custom_brewery": null,
"original_brewery": "Russian River Brewing Company",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"containers": [
{
"id": 9,
"item_id": 10,
"container_size_id": 6,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"container_size": {
"id": 6,
"name": "32oz Growler",
"position": 96,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 9
}
],
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": 11,
"section_id": 7,
"position": 1,
"untappd_id": 3883,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
"brewery_location": "Woodridge, IL",
"abv": "4.6",
"ibu": "0.0",
"cask": false,
"nitro": true,
"tap_number": "5",
"rating": "2.76162",
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon",
"original_name": "Pabst Blue Ribbon",
"custom_name": null,
"description": "A PBR beer",
"custom_description": "A PBR beer",
"original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"style": "Lager - North American Adjunct",
"custom_style": null,
"original_style": "Lager - North American Adjunct",
"brewery": "Pabst Brewing Company",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"containers": [
{
"id": 10,
"item_id": 11,
"container_size_id": 6,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"container_size": {
"id": 6,
"name": "32oz Growler",
"position": 96,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 10
}
],
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
]
}
],
"on_deck_section": {
"id": 8,
"menu_id": 3,
"position": 0,
"name": "On Deck",
"description": "",
"type": "OnDeckSection",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"public": false,
"items": []
}
}
]
}
An example of using this route to update the previously created data looks like the following:
Request:
curl "http://localhost:3000/api/v1/locations/3/menus" \
-X PUT \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{"menus":[{"id":3, "unpublished":false,"name":"A different menu name","description":"A menu description","footer":"a footer for the menu","sections":[{"id":7, "name":"A section name","description":"A section description.","items":[{"untappd_id":4499,"cask":true,"nitro":false,"description":"A custom item description","tap_number":4,"containers":[{"container_size_id":5,"price":3.99}]},{"untappd_id":3883,"cask":false,"nitro":true,"description":"A PBR beer","tap_number":5,"containers":[{"container_size_id":5,"price":3.99}]}]}]}]}'
Returns JSON structured like this:
{
"menus": [
{
"id": 3,
"location_id": 3,
"uuid": "c2402f2e-90e5-40cd-a455-68e45cf7f70c",
"name": "A different menu name",
"description": "A menu description",
"footer": "a footer for the menu",
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T17:01:20Z",
"sections": [
{
"id": 7,
"menu_id": 3,
"position": 0,
"name": "A section name",
"description": "A section description.",
"type": "Section",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T17:01:20Z",
"items": [
{
"id": 10,
"section_id": 7,
"position": 0,
"untappd_id": 4499,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-4499_dc04a_sm.jpeg",
"brewery_location": "Santa Rosa, CA",
"abv": "8.0",
"ibu": "100.0",
"cask": true,
"nitro": false,
"tap_number": "4",
"rating": "4.5657",
"in_production": true,
"untappd_beer_slug": "russian-river-brewing-company-pliny-the-elder",
"untappd_brewery_id": 5143,
"name": "Pliny the Elder",
"original_name": "Pliny the Elder",
"custom_name": null,
"description": "A custom item description",
"custom_description": "A custom item description",
"original_description": "A true leader in the hop-wars of the west coast, Pliny the Elder hits you over the head with hoppy bitterness and manages to smooth the rough edges out enough to become an enjoyable brew.",
"style": "IPA - Imperial / Double",
"custom_style": null,
"original_style": "IPA - Imperial / Double",
"brewery": "Russian River Brewing Company",
"custom_brewery": null,
"original_brewery": "Russian River Brewing Company",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T17:01:20Z",
"containers": [
{
"id": 11,
"item_id": 10,
"container_size_id": 5,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T17:01:20Z",
"updated_at": "2016-11-08T17:01:20Z",
"container_size": {
"id": 5,
"name": "Crowler",
"position": 101,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 11
}
],
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": 11,
"section_id": 7,
"position": 1,
"untappd_id": 3883,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
"brewery_location": "Woodridge, IL",
"abv": "4.6",
"ibu": "0.0",
"cask": false,
"nitro": true,
"tap_number": "5",
"rating": "2.76162",
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon",
"original_name": "Pabst Blue Ribbon",
"custom_name": null,
"description": "A PBR beer",
"custom_description": "A PBR beer",
"original_description": "This is the original Pabst Blue Ribbon Beer. Nature's choicest products provide its prized flavor. Only the finest of hops and grains are used. Selected as America's Best in 1893.",
"style": "Lager - North American Adjunct",
"custom_style": null,
"original_style": "Lager - North American Adjunct",
"brewery": "Pabst Brewing Company",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T17:01:20Z",
"containers": [
{
"id": 12,
"item_id": 11,
"container_size_id": 5,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T17:01:20Z",
"updated_at": "2016-11-08T17:01:20Z",
"container_size": {
"id": 5,
"name": "Crowler",
"position": 101,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 12
}
],
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
]
}
],
"on_deck_section": {
"id": 8,
"menu_id": 3,
"position": 0,
"name": "On Deck",
"description": "",
"type": "OnDeckSection",
"created_at": "2016-11-08T16:59:05Z",
"updated_at": "2016-11-08T16:59:05Z",
"public": false,
"items": []
}
}
]
}
HTTP Request
PUT https://business.untappd.com/api/v1/locations/:location_id/menus
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the Location. |
| menus | Array | true | An Array of Objects. Any menus without an id will be created. Any menus with an id will be updated. Any existing menus not provided will remain unchanged. |
| sections | Array | true | An Array of Objects. Any sections without an id will be created. Any sections with an id will be updated. Any existing sections not provided for the given menu will be removed. |
| items | Array | true | An Array of Objects. Items are updated by untappd_id. Any items with an untappd_id will be updated. Any existing items not provided for the given section will be removed. |
| containers | Array | true | An Array of Objects. Existing containers are removed and any provided containers will be created. |
| background | String | false | Only use this if your payload is extremely large (ie. 1000 menu items) and you are receiving "Request Timeout". If background is set, the bulk upsert will be performed in a background job with the value of background used as the JSON payload. ie: { "background": "{\"menus\": [{\"id\": 1}]}" }. Note: the value of background must be a stringified version of the JSON payload. We do this for performance reasons. |
| callback_url | String | false | A valid url starting with either https:// or http:// that will be POSTed to with the response when using background. ie. http://example.com/background_job_complete. The Content-Type of the callback request will be: application/json. Note: The response from your server at the callback_url must be an HTTP 200 status code. Any other status code or failure will cause the callback to be retried for about a month using exponential backoff. |
Create a menu
Creates a new menu.
Request:
curl "http://localhost:3000/api/v1/locations/5/menus" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "menu": { "name": "Draft Beer List" } }'
Returns JSON structured like this:
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Draft Beer List",
"description": null,
"footer": null,
"draft": true,
"unpublished": true,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/menus
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The id of the location. |
| name | String | true | The menu name. |
Retrieve a menu
Retrieve the details of an existing menu. You need only supply the unique menu identifier that was returned upon menu creation.
Request:
curl "http://localhost:3000/api/v1/menus/5" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
Or...
To get the full menu use the full param with the request:
curl "http://localhost:3000/api/v1/menus/5?full=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T18:02:42.836010Z",
"sections": [
{
"id": 10,
"menu_id": 5,
"position": 0,
"name": "Alcoholic Drinks",
"description": "Escape from a hard day with something alcoholic!",
"type": "Section",
"public": true,
"created_at": "2023-03-21T12:48:57.552844Z",
"updated_at": "2023-03-21T17:52:55.087976Z",
"items": [
{
"id": 65,
"section_id": 10,
"position": 0,
"untappd_id": null,
"label_image": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"label_image_thumb": "https://www.wine-searcher.com/images/labels/19/94/10531994.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"original_label_image": "https://beer.untappd.com/labels/",
"original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": null,
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": null,
"rating_count": null,
"in_production": null,
"untappd_beer_slug": null,
"untappd_brewery_id": null,
"name": "Bodegas Campo Viejo Tempranillo",
"original_name": null,
"custom_name": null,
"description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"custom_description": "A cherry red colour suggests a vibrant Tempranillo wine. On the nose, the rich aromas have a pronounced intensity with an initial scent of ripe fruits followed by gentle sweet notes of vanilla and spices. On the palate, it is perfumed, soft and fresh with a long finish.",
"original_description": null,
"style": null,
"custom_style": null,
"original_style": null,
"brewery": null,
"brewery_country": null,
"custom_brewery": null,
"original_brewery": null,
"calories": null,
"custom_calories": null,
"original_calories": null,
"abv": "13.5",
"custom_abv": null,
"original_abv": null,
"ibu": null,
"custom_ibu": null,
"original_ibu": null,
"created_at": "2023-03-21T13:02:01.593381Z",
"updated_at": "2023-03-21T14:14:17.533411Z",
"type": "wine",
"default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/wine.svg",
"producer": "Bodegas Campo Viejo",
"vintage": null,
"characteristics": "Red - Savory and Classic",
"category": "Tempranillo",
"location": "Rioja, Spain",
"containers": [
{
"id": 119,
"item_id": 65,
"container_size_id": "",
"price": "8.00",
"position": 0,
"container_size": null,
"created_at": "2023-03-21T13:05:28.537922Z",
"updated_at": "2023-03-21T13:05:28.537922Z",
"_track_by": 119,
"calories": null,
"name": "Glass",
"currency": "USD"
}
]
},
{
"id": 64,
"section_id": 10,
"position": 1,
"untappd_id": 4473,
"label_image": "https://beer.untappd.com/labels/4473",
"label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/4473",
"original_label_image": "https://beer.untappd.com/labels/4473",
"original_label_image_hd": "https://beer.untappd.com/labels/4473?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Dublin, County Dublin",
"cask": false,
"nitro": true,
"local": false,
"tap_number": "1",
"rating": "3.76886",
"rating_count": 801407,
"in_production": true,
"untappd_beer_slug": "guinness-guinness-draught",
"untappd_brewery_id": 49,
"name": "Guinness Draught",
"original_name": "Guinness Draught",
"custom_name": null,
"description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"custom_description": null,
"original_description": "Swirling clouds tumble as the storm begins to calm. Settle. Breathe in the moment, then break through the smooth, light head to the bittersweet reward.\r\n\r\nUnmistakeably GUINNESS, from the first velvet sip to the last, lingering drop. And every deep-dark satisfying mouthful in between.\r\n\r\nPure beauty. Pure GUINNESS.\r\n\r\nGuinness Draught is sold in kegs, widget cans, and bottles. The ABV varies from 4.1 to 4.3%.\r\n\r\nGuinness Extra Cold is the exact same beer only served through a super cooler at 3.5 °C",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"brewery_country": "Ireland",
"custom_brewery": null,
"original_brewery": "Guinness",
"calories": "125",
"custom_calories": null,
"original_calories": "125",
"abv": "4.2",
"custom_abv": null,
"original_abv": "4.2",
"ibu": "45.0",
"custom_ibu": null,
"original_ibu": "45.0",
"created_at": "2023-03-21T13:01:26.220225Z",
"updated_at": "2023-03-21T14:14:17.533411Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null,
"containers": [
{
"id": 118,
"item_id": 64,
"container_size_id": 18,
"price": "7.00",
"position": 0,
"container_size": {
"id": 18,
"name": "20oz Draft",
"ounces": "20.0",
"position": 21,
"created_at": "2016-03-01T15:36:26.000000Z",
"updated_at": "2016-08-24T20:52:06.390485Z"
},
"created_at": "2023-03-21T13:04:40.317030Z",
"updated_at": "2023-03-21T13:04:40.317030Z",
"_track_by": 118,
"calories": "180.0",
"name": "20oz Draft",
"currency": "USD"
}
]
},
{
"id": 67,
"section_id": 10,
"position": 2,
"untappd_id": 9681,
"label_image": "https://beer.untappd.com/labels/9681",
"label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
"label_image_thumb": "https://beer.untappd.com/labels/9681",
"original_label_image": "https://beer.untappd.com/labels/9681",
"original_label_image_hd": "https://beer.untappd.com/labels/9681?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": "Grand Rapids, MI",
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": "4.38633",
"rating_count": 224308,
"in_production": true,
"untappd_beer_slug": "founders-brewing-co-kentucky-breakfast-stout-kbs",
"untappd_brewery_id": 549,
"name": "Kentucky Breakfast Stout (KBS)",
"original_name": "Kentucky Breakfast Stout (KBS)",
"custom_name": null,
"description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
"custom_description": null,
"original_description": "This beer taught us that patience truly is a virtue. KBS is a big imperial stout brewed with a massive amount of coffee and chocolate and then bourbon barrel-aged to perfection. Incredibly silky and full-bodied with notes of vanilla, cocoa, roasted coffee and charred oak.",
"style": "Stout - Imperial / Double Coffee",
"custom_style": null,
"original_style": "Stout - Imperial / Double Coffee",
"brewery": "Founders Brewing Co.",
"brewery_country": "United States",
"custom_brewery": null,
"original_brewery": "Founders Brewing Co.",
"calories": "340",
"custom_calories": null,
"original_calories": "340",
"abv": "12.0",
"custom_abv": null,
"original_abv": "12.0",
"ibu": "70.0",
"custom_ibu": null,
"original_ibu": "70.0",
"created_at": "2023-03-21T14:14:17.526349Z",
"updated_at": "2023-03-21T14:14:17.526936Z",
"type": "beer",
"default_image": "https://assets.untappd.com/site/assets/images/temp/badge-beer-default.png",
"producer": null,
"vintage": null,
"characteristics": null,
"category": null,
"location": null,
"containers": []
},
{
"id": 66,
"section_id": 10,
"position": 3,
"untappd_id": null,
"label_image": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"label_image_hd": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
"label_image_thumb": "https://www.wine-searcher.com/images/labels/36/77/10143677.jpg?width=50&height=50&fit=bounds&canvas=50,50",
"original_label_image": "https://beer.untappd.com/labels/",
"original_label_image_hd": "https://beer.untappd.com/labels/?size=hd",
"custom_label_image": null,
"custom_label_image_thumb": null,
"custom_label_image_filename": null,
"brewery_location": null,
"cask": false,
"nitro": false,
"local": false,
"tap_number": null,
"rating": null,
"rating_count": null,
"in_production": null,
"untappd_beer_slug": null,
"untappd_brewery_id": null,
"name": "The Kraken Black Spiced Rum",
"original_name": null,
"custom_name": null,
"description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
"custom_description": "One of the fastest growing rum brands, The Kraken® is the world’s first black spiced rum, housed in an iconic bottle. Taste the flavors of cinnamon, vanilla, and nutmeg and experience its magic. The Kraken® Original is 94 proof. It has a distinct aroma of caramel, toffee and spice with flavors of cinnamon and vanilla and a lingering spicy finish. (47% ABV - 94 proof) The Kraken®, blended with secret spices, is perfect to spice up classics and new favorite cocktails or as a shot.",
"original_description": null,
"style": null,
"custom_style": null,
"original_style": null,
"brewery": null,
"brewery_country": null,
"custom_brewery": null,
"original_brewery": null,
"calories": null,
"custom_calories": null,
"original_calories": null,
"abv": "35.0",
"custom_abv": null,
"original_abv": null,
"ibu": null,
"custom_ibu": null,
"original_ibu": null,
"created_at": "2023-03-21T13:02:51.158417Z",
"updated_at": "2023-03-21T14:14:17.533411Z",
"type": "spirit",
"default_image": "https://s3.amazonaws.com/woof.nextglass.co/default/spirit.svg",
"producer": "The Kraken",
"vintage": null,
"characteristics": null,
"category": "Rum - Liqueur - Flavored",
"location": "Caribbean, Rest of World",
"containers": [
{
"id": 120,
"item_id": 66,
"container_size_id": "",
"price": "3.50",
"position": 0,
"container_size": null,
"created_at": "2023-03-21T13:06:38.039237Z",
"updated_at": "2023-03-21T13:06:38.039237Z",
"_track_by": 120,
"calories": null,
"name": "Shot",
"currency": "USD"
}
]
}
]
}
],
"on_deck_section": {
"id": 9,
"menu_id": 5,
"position": 0,
"name": "On Deck",
"description": "",
"type": "OnDeckSection",
"public": true,
"created_at": "2023-03-21T12:48:57.548359Z",
"updated_at": "2023-03-21T14:14:17.542020Z",
"items": []
}
}
}
HTTP Request
GET https://business.untappd.com/api/v1/menus/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the menu. |
| full | true or not set | false | Returns the entire menu tree with sections, items, containers and container sizes. Also, enables analytics tracking for the request. |
| source_name | Integer | false | When full is present in the request params, an optional source_name may be provided to change the recorded source of the request for the analytics dashboard. Defaults to: API. See: Analytics/Track. |
Update a menu
Updates the specified menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/menus/5" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "menu": { "name": "Super Awesome Draft Beer List" } }'
Returns JSON structured like this:
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Super Awesome Draft Beer List",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/menus/:id
PATCH https://business.untappd.com/api/v1/menus/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the menu. |
| name | String | false | The menu name. |
| description | String | false | The menu description. |
| footer | String | false | The menu footer. |
Delete a menu
Permanently deletes a menu. It cannot be undone. If the menu is already published then it will first be unpublished and then deleted.
Request:
curl "http://localhost:3000/api/v1/menus/5" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns the deleted menu as JSON structured like this:
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/menus/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The menu to be deleted. |
Delete Multiple Menus
Permanently deletes menus. It cannot be undone. If the menus are already published then they will first be unpublished and then deleted.
Request:
curl "http://localhost:3000/api/v1/locations/5/menus" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "ids": [1, 2, 3] }'
Returns JSON structured like this:
{
"success": true
}
HTTP Request
DELETE https://business.untappd.com/api/v1/locations/:location_id/menus
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to delete menus for. |
| ids | Array | true | An Array of ids. All the menu ids for the location to be deleted. |
Update menu positions
Set the positions of menus in a location. Menu positions are used to order the published menus on a page.
Important!: When updating menu positions, all menus for the location must be passed and the positions must start at zero. Use List all menus first to get all the menus for the location.
Request:
curl "http://localhost:3000/api/v1/locations/3/menus/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "menus": [{ "id": 1, "position": 1 }, { "id": 3, "position": 0 }] }'
Returns JSON structured like this:
{
"menus": [
{
"id": 3,
"position": 0
},
{
"id": 1,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/locations/:location_id/menus/positions
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location to update menu positions for. |
| menus | Array | true | An Array of Menu Position Objects. All the menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
Menu Position Object
| Property | Type | Required | Description |
|---|---|---|---|
| id | integer | true | Menu id to update the position for. |
| position | integer | true | The position to set the menu at. Menu positions must start at zero. |
Publish all menus
Publish all the unpublished menus of a location. Any changes to a published menu will automatically take effect.
Request:
curl "http://localhost:3000/api/v1/locations/5/menus/publish_all" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublishedis now set to:false):
{
"menus": [
{
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
},
{
"id": 6,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 1,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
]
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/menus/publish_all
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| location_id | Integer | true | The location. |
Publish a menu
Publish a menu. There is no need to republish a menu that has already been published. Any changes to a published menu will automatically take effect.
Request:
curl "http://localhost:3000/api/v1/menus/5/publish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublishedis now set to:false):
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": false,
"unpublished": false,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/menus/:id/publish
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The menu to publish. |
Unpublish a menu
Unpublish a menu.
Request:
curl "http://localhost:3000/api/v1/menus/5/unpublish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublishedis now set to:true):
{
"menu": {
"id": 5,
"location_id": 5,
"uuid": "f181f982-42bf-414b-be9a-d13406e5be0b",
"name": "Beverages",
"description": "Grab something to drink while you're here.",
"footer": null,
"draft": true,
"unpublished": true,
"position": 0,
"show_price_on_untappd": true,
"push_notification_frequency": "real_time",
"created_at": "2023-03-21T12:48:57.545101Z",
"updated_at": "2023-03-21T13:32:55.043263Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/menus/:id/unpublish
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The menu to unpublish. |
Untappd Item Exists
Returns true or false depending on if an untappd item exists in any section in a menu.
Request:
curl "http://localhost:3000/api/v1/menus/5/untappd_item_exists/4099?is_nitro=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"untappd_id": 4099,
"exists": true
}
HTTP Request
GET https://business.untappd.com/api/v1/menus/:menu_id/untappd_item_exists/:untappd_id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| menu_id | Integer | true | The id of the menu. |
| untappd_id | Integer | true | The id of the untappd item. |
| is_nitro | Boolean | false | "true", "1" - "false", "0" |
| is_cask | Boolean | false | "true", "1" - "false", "0" |
Sections
- A section belongs to a menu.
- A section has many items.
Section Object
| Property | Type | Description |
|---|---|---|
| created_at | timestamp | Time at which the Section was created. ISO8601 format. |
| description | string | Description of the Section |
| id | integer | Unique identifier for the Section |
| menu_id | integer | Menu id that the Section belongs to. See Menu. |
| name | string | Name of the Section |
| position | integer | The position of the Section in the list of Sections for the Menu. Positions start at zero and should be contiguous. |
| public | boolean | If the Section is visible to the public. Controls visibility within the Untappd App when displaying menus. |
| type | string | One of Section or OnDeckSection |
| updated_at | timestamp | Time at which this Section was last updated. ISO8601 format. |
Section Full Object
The full Section object can be returned by passing full=true when retieving a Menu. This will return the entire menu tree including all Sections, Items, and Containers. The following properties will be available in addition to the properties in the regular Section object
| Property | Type | Description |
|---|---|---|
| items | array | An array of Items for the Section |
List all sections
List all the sections of a menu.
Request:
curl "http://localhost:3000/api/v1/menus/5/sections?include_on_deck_section=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns JSON structured like this:
{
"sections": [
{
"id": 10,
"menu_id": 5,
"position": 0,
"name": "Alcoholic",
"description": "Escape from a hard day with something alcoholic!",
"type": "Section",
"public": true,
"created_at": "2023-03-21T12:48:57.552844Z",
"updated_at": "2023-03-21T14:17:37.727172Z"
},
{
"id": 9,
"menu_id": 5,
"position": 0,
"name": "On Deck",
"description": "",
"type": "OnDeckSection",
"public": true,
"created_at": "2023-03-21T12:48:57.548359Z",
"updated_at": "2023-03-21T14:14:17.542020Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/menus/:menu_id/sections
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| menu_id | Integer | true | The menu to lookup the sections for. |
| include_on_deck_section | true of false | false | When set to true will return the section with type OnDeckSection for the menu. |
Create a section
Creates a new section belonging to a menu.
Request:
curl "http://localhost:3000/api/v1/menus/5/sections" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
-H "Content-Type: application/json" \
-d '{ "section": { "name": "Other beers", "description": "Our beers that are not dark or light." } }'
Returns JSON structured like this:
{
"section": {
"id": 16,
"menu_id": 5,
"position": 2,
"name": "Other beers",
"description": "Our beers that are not dark or light.",
"created_at": "2023-03-21T17:50:55.954Z",
"updated_at": "2023-03-21T17:50:55.954Z",
"public": true,
"items_count": 0
}
}
HTTP Request
POST https://business.untappd.com/api/v1/menus/:menu_id/sections
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| menu_id | Integer | true | The id of the menu. |
| head | true or false | true | Adds the new section to the head of the list of sections for this menu when head is true. Otherwise the new section will be appended to the end. |
| name | String | false | A name for the new section. |
| description | String | false | A description for the new section. |
Retrieve a section
Retrieve the details of an existing section. You need only supply the unique section identifier that was returned upon section creation.
Request:
curl "http://localhost:3000/api/v1/sections/10" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns JSON structured like this:
{
"section": {
"id": 10,
"menu_id": 5,
"position": 0,
"name": "Alcoholic",
"description": "Escape from a hard day with something alcoholic!",
"type": "Section",
"public": true,
"created_at": "2023-03-21T12:48:57.552844Z",
"updated_at": "2023-03-21T14:17:37.727172Z"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/sections/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the section. |
Update a section
Updates the specified section by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Note: This endpoint does not currently support updating On Deck sections. Instead, you can perform actions on an On Deck section by doing the following:
- Find the section id using the List all sections endpoint
- Perform the desired action on the specified item using the Items endpoints.
Request:
curl "http://localhost:3000/api/v1/sections/10" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
-H "Content-Type: application/json" \
-d '{ "section": { "name": "Alcoholic Drinks" } }'
Returns JSON structured like this:
{
"section": {
"name": "Alcoholic Drinks",
"id": 10,
"menu_id": 5,
"position": 0,
"description": "Escape from a hard day with something alcoholic!",
"created_at": "2023-03-21T12:48:57.552Z",
"updated_at": "2023-03-21T17:52:55.087Z",
"public": true,
"items_count": 4
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/sections/:id
PATCH https://business.untappd.com/api/v1/sections/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the section. |
| name | String | false | The section name. |
| description | String | false | The section description. Note: This parameter is not available for OnDeckSection. |
Delete a section
Permanently deletes a section. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/sections/15" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns the deleted section as JSON structured like this:
{
"section": {
"id": 15,
"menu_id": 5,
"position": 1,
"name": "Other Beers",
"description": "",
"created_at": "2023-03-21T17:50:32.209Z",
"updated_at": "2023-03-21T17:50:32.209Z",
"public": true,
"items_count": 0
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/sections/:id
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| id | Integer | true | The id of the section. |
Update section positions
Set the positions of sections in a menu. Section positions are used to order the sections of a published menu on a page.
Important!: When updating section positions, all sections for the menu must be passed and the positions must start at zero. Use List all sections first to get all the sections for the menu.
Request:
curl "http://localhost:3000/api/v1/menus/10/sections/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
-H "Content-Type: application/json" \
-d '{ "sections": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'
Returns JSON structured like this:
{
"sections": [
{
"id": 2,
"position": 0
},
{
"id": 1,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/menus/:menu_id/sections/positions
Query Parameters
| Parameter | Validations | Required | Description |
|---|---|---|---|
| menu_id | Integer | true | The menu to update section positions for. |
| sections | Array | true | An Array of Objects. All the sections for a menu must be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
| id | Integer | true | The section id to update the position for. |
| position | Integer | true | The position to set the section at. Section positions must start at zero. |
Digital Boards
Digital Board Object
| Property | Type | Description |
|---|---|---|
| created_at | timestamp | Time at which the Digital Board was created. ISO8601 format. |
| id | integer | Unique identifier for the Digital Board |
| location_id | integer | Location id that the Digital Board belongs to |
| menus | array | An array of Digital Board Menus to be displayed on the digital board. |
| name | string | Name of the Digital Board |
| updated_at | timestamp | Time at which the Digital Board was last updated. ISO8601 format. |
| template | string | Template the Digital Board is using. |
| url | string | Website URL to view the Digital Board. |
Digital Board Menu Object
| Property | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the Menu |
| name | string | Name of the Menu |
List all digital boards
Returns a list of digital boards belonging to your location.
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/digital_boards
Request:
curl "https://business.untappd.com/api/v1/locations/5/digital_boards" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"digital_boards": [
{
"id": 20002,
"name": "Draft List",
"template": "two_column",
"created_at": "2023-12-07T15:44:08.162226Z",
"updated_at": "2023-12-07T15:44:16.867106Z",
"menus": [
{
"id": 1,
"name": "Draft"
}
],
"url": "https://business.untappd.com/boards/20002"
}
]
}
Status
A simple endpoint that returns 200 OK if the api is working.
Returns JSON structured like this:
{ "status": "OK" }
HTTP Request
GET https://business.untappd.com/api/v1/status
Changelog
All notable changes to this API will be documented in this file.
2024-07-17
Removed:
- Custom menus
- Custom sections
- Custom items
- Custom item types
- Custom containers
- Legacy Menus
2023-01-10
Added:
- Digital Boards section added to docs.
Removed
- Social announcements removed.
2021-01-25
Added:
- Improved documentation about location categories when updating Location Details.
2020-08-28
Added:
- TLS Versions section added to docs.
2020-08-12
Added:
- Retrieve a location section added to docs.
- Update a location section added to docs.
- Update a location's details section added to the docs.
- Hours section added to the docs.
Changed:
- Update a section improved documentation around updating an
On Decksection.
2017-10-12
Added:
- GraphQL section added to docs.
2016-11-22
Added:
- List Sections now has
include_on_deck_sectionparameter to include the section withtype=OnDeckSectionin the results. - Update Sections now accepts the
nameparameter for sections withtype=OnDeckSection.
2016-11-16
Added:
- API Token Types section to explain the different types of API tokens.
2016-11-15
Added:
- Container and Custom Container
positionproperties.positionon every container in the item will automatically be updated when one containerpositionis set.
Changed:
- Containers are now by default sorted by their
positionproperty instead ofcreated_at.
2016-11-08
Added:
- Item
custom_breweryandoriginal_breweryproperties.
Changed:
- Item
brewerybehavior. Will now equalcustom_brewerywhencustom_breweryis not null, otherwise defaults tooriginal_brewery.