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
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": 1,
"name": "Draft",
"position": 1,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 2,
"name": "Can",
"position": 2,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 3,
"name": "Bottle",
"position": 3,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 4,
"name": "Tallboy",
"position": 4,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 8,
"name": "4 Pack",
"position": 5,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 5,
"name": "Crowler",
"position": 6,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 6,
"name": "32oz Growler",
"position": 7,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
},
{
"id": 7,
"name": "64oz Growler",
"position": 8,
"created_at": "2016-04-07T14:26:31Z",
"updated_at": "2016-04-07T14:26:31Z"
}
]
}
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
List all containers
Returns a list of containers belonging to an item.
Request:
curl "http://localhost:3000/api/v1/items/1/containers" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"containers": [
{
"id": 1,
"item_id": 1,
"container_size_id": 6,
"price": "4.00",
"position": 0,
"created_at": "2016-06-16T19:54:49Z",
"updated_at": "2016-06-16T19:54:55Z",
"container_size": {
"id": 6,
"name": "8oz Draft",
"position": 6,
"created_at": "2016-06-16T19:30:00.948Z",
"updated_at": "2016-06-16T19:30:00.948Z",
"container_size_group_id": 1
},
"_track_by": 1
},
{
"id": 2,
"item_id": 1,
"container_size_id": 4,
"price": "3.75",
"position": 1,
"created_at": "2016-06-16T19:55:02Z",
"updated_at": "2016-06-16T19:55:05Z",
"container_size": {
"id": 4,
"name": "6oz Draft",
"position": 4,
"created_at": "2016-06-16T19:30:00.940Z",
"updated_at": "2016-06-16T19:30:00.940Z",
"container_size_group_id": 1
},
"_track_by": 2
}
]
}
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/1/containers" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
-H "Content-Type: application/json" \
-d '{ "container": { "container_size_id": 4, "price": 3.99 } }'
Returns JSON structured like this:
{
"container": {
"id": 6,
"item_id": 1,
"container_size_id": 4,
"price": "3.99",
"position": 0,
"created_at": "2016-06-20T14:04:05Z",
"updated_at": "2016-06-20T14:04:05Z",
"container_size": {
"id": 4,
"name": "6oz Draft",
"position": 4,
"created_at": "2016-06-16T19:30:00.940Z",
"updated_at": "2016-06-16T19:30:00.940Z",
"container_size_group_id": 1
},
"_track_by": 6
}
}
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/1" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"container": {
"id": 1,
"item_id": 1,
"container_size_id": 6,
"price": "4.00",
"position": 0,
"created_at": "2016-06-16T19:54:49Z",
"updated_at": "2016-06-16T19:54:55Z",
"container_size": {
"id": 6,
"name": "8oz Draft",
"position": 6,
"created_at": "2016-06-16T19:30:00.948Z",
"updated_at": "2016-06-16T19:30:00.948Z",
"container_size_group_id": 1
},
"_track_by": 1
}
}
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/1" \
-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": 1,
"item_id": 1,
"container_size_id": 6,
"price": "2.99",
"position": 1,
"created_at": "2016-06-16T19:54:49Z",
"updated_at": "2016-06-20T14:16:14Z",
"container_size": {
"id": 6,
"name": "8oz Draft",
"position": 6,
"created_at": "2016-06-16T19:30:00.948Z",
"updated_at": "2016-06-16T19:30:00.948Z",
"container_size_group_id": 1
},
"_track_by": 1
}
}
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/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns the deleted container as JSON structured like this:
{
"container": {
"id": 1,
"item_id": 1,
"container_size_id": 6,
"price": "2.99",
"position": 0,
"created_at": "2016-06-16T19:54:49Z",
"updated_at": "2016-06-20T14:16:14Z",
"container_size": {
"id": 6,
"name": "8oz Draft",
"position": 6,
"created_at": "2016-06-16T19:30:00.948Z",
"updated_at": "2016-06-16T19:30:00.948Z",
"container_size_group_id": 1
},
"_track_by": 1
}
}
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
Custom Containers [Deprecated]
List all custom containers
Returns a list of custom containers belonging to a custom item.
Request:
curl "http://localhost:3000/api/v1/custom_items/2/custom_containers" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"custom_containers": [
{
"id": 2,
"custom_item_id": 2,
"name": "1 glass",
"price": "8.95",
"position": 0,
"_track_by": 2,
"created_at": "2016-11-14T16:06:00Z",
"updated_at": "2016-11-14T16:06:12Z"
},
{
"id": 3,
"custom_item_id": 2,
"name": "1 bottle",
"price": "38.95",
"position": 1,
"_track_by": 3,
"created_at": "2016-11-14T16:06:09Z",
"updated_at": "2016-11-14T16:06:09Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_items/:custom_item_id/custom_containers
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
item_id | Integer | true | The id of the custom item. |
build | true or not set | false | Add a blank custom container (not yet persisted) to the response. This is useful when you have a reactive frontend that fetches all the custom containers and provides fields for a new one to be added. |
Create a custom container
Add a new custom container to a custom item.
Request:
curl "http://localhost:3000/api/v1/custom_items/2/custom_containers" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
-H "Content-Type: application/json" \
-d '{ "custom_container": { "name": "Tall glass", "price": 5.99 } }'
Returns JSON structured like this:
{
"custom_container": {
"id": 4,
"custom_item_id": 2,
"name": "Tall glass",
"price": "5.99",
"position": 0,
"_track_by": 4,
"created_at": "2016-11-14T16:07:01Z",
"updated_at": "2016-11-14T16:07:01Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/custom_items/:custom_item_id/custom_containers
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_item_id | Integer | true | The id of the custom_item. |
name | String | false | Name of the custom container. |
price | Float | true | Price of the custom container. |
Retrieve a custom container
Retrieve the details of an existing custom container. You need only supply the unique custom container identifier that was returned upon custom container creation.
Request:
curl "http://localhost:3000/api/v1/custom_containers/2" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns JSON structured like this:
{
"custom_container": {
"id": 2,
"custom_item_id": 2,
"name": "1 glass",
"price": "8.95",
"position": 1,
"_track_by": 2,
"created_at": "2016-11-14T16:06:00Z",
"updated_at": "2016-11-14T16:06:12Z"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_containers/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom container. |
Update a custom container
Updates the specified custom container by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/custom_containers/2" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ=" \
-H "Content-Type: application/json" \
-d '{ "custom_container": { "price": 7.99 } }'
Returns JSON structured like this:
{
"custom_container": {
"id": 2,
"custom_item_id": 2,
"name": "1 glass",
"price": "7.99",
"position": 1,
"_track_by": 2,
"created_at": "2016-11-14T16:06:00Z",
"updated_at": "2016-11-14T16:07:47Z"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/custom_containers/:id
PATCH https://business.untappd.com/api/v1/custom_containers/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the container. |
name | String | false | Name of the custom container. |
price | Float | true | Price of the custom container. |
position | Integer | false | The position of the custom container in the list of custom containers for the custom item. Positions start at zero and should be contiguous. |
Delete a custom container
Permanently deletes a custom container. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/custom_containers/2" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286a2dzU01WZTFkVVhYU2NKd3NxNTQ="
Returns the deleted custom container as JSON structured like this:
{
"custom_container": {
"id": 2,
"custom_item_id": 2,
"name": "1 glass",
"price": "7.99",
"position": 1,
"_track_by": 2,
"created_at": "2016-11-14T16:06:00Z",
"updated_at": "2016-11-14T16:07:47Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/custom_containers/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The custom container to be deleted. |
Custom Item Types [Deprecated]
In order to set a type on a custom item, you must know the custom_item_type_id
from: custom_item_type.id
.
The index route here will give you all the possible custom item types to present to a user. We use a select
field on business.untappd.com.
- Custom Item Types have many Custom Items.
- Custom Items belong to a Custom Item Type
List all custom item types
Request:
curl "http://localhost:3000/api/v1/custom_item_types" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"custom_item_types": [
{
"id": 1,
"name": "wine",
"position": 0,
"created_at": "2016-09-29T16:49:33Z",
"updated_at": "2016-09-29T16:49:33Z"
},
{
"id": 3,
"name": "food",
"position": 1,
"created_at": "2016-09-29T16:49:33Z",
"updated_at": "2016-09-29T18:52:01Z"
},
{
"id": 2,
"name": "cocktail",
"position": 2,
"created_at": "2016-09-29T16:49:33Z",
"updated_at": "2016-09-29T18:52:01Z"
}
]
}
Returns a list of all custom item types. This list is likely to be added to in the future. A given custom item type will most likely never be removed.
HTTP Request
GET https://business.untappd.com/api/v1/custom_item_types
Custom Items [Deprecated]
- An custom item belongs to a custom section.
- An custom item has many custom containers.
List all custom items
Returns a list of custom items belonging to a custom section.
Request:
curl "http://localhost:3000/api/v1/custom_sections/1/custom_items" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"custom_items": [
{
"id": 3,
"custom_section_id": 1,
"position": 0,
"name": "Old Fashioned",
"description": "Bitters and all.",
"type": "cocktail",
"custom_item_type_id": 2,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392a-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:59Z",
"updated_at": "2016-09-29T18:48:08Z"
},
{
"id": 2,
"custom_section_id": 1,
"position": 1,
"name": "A glass of house red",
"description": "Made from grapes.",
"type": "wine",
"custom_item_type_id": 1,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:58Z",
"updated_at": "2016-09-29T18:48:15Z"
},
{
"id": 1,
"custom_section_id": 1,
"position": 2,
"name": "Cheese Platter",
"description": "Delightful and delicious.",
"type": "food",
"custom_item_type_id": 3,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392c-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:56Z",
"updated_at": "2016-09-29T18:48:19Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_section_id | Integer | true | The section to list the items for. |
Create a custom item
Creates a new custom item.
Request:
curl "http://localhost:3000/api/v1/custom_sections/1/custom_items" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "custom_item": { "name": "A glass of house red", "description": "Made from grapes.", "custom_item_type_id": 1 } }'
Returns all the items for the section (including the new one) as JSON structured like this:
{
"custom_item": {
"id": 2,
"custom_section_id": 1,
"position": 1,
"name": "A glass of house red",
"description": "Made from grapes.",
"type": "wine",
"custom_item_type_id": 1,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:58Z",
"updated_at": "2016-09-29T18:48:15Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_section_id | Integer | true | The custom section to add the custom item to. |
name | String | false | The custom item name. |
description | String | false | The custom item description. |
type | wine/cocktail/food | true | The custom item type. |
Retrieve a custom item
Retrieve the details of an existing custom item. You need only supply the unique custom item identifier that was returned upon custom item creation.
Request:
curl "http://localhost:3000/api/v1/custom_items/2" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns JSON structured like this:
{
"custom_item": {
"id": 2,
"custom_section_id": 1,
"position": 1,
"name": "A glass of house red",
"description": "Made from grapes.",
"type": "wine",
"custom_item_type_id": 1,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:58Z",
"updated_at": "2016-09-29T18:48:15Z"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_items/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom item. |
name | String | false | The custom item name. |
description | String | false | The custom item description. |
type | wine/cocktail/food | true | The custom item type. |
Update a custom item
Updates the specified custom item by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/custom_items/2" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "custom_item": { "name": "Sangria", "description": "Fruit, Sweetened", "custom_item_type_id": 2 } }'
Returns JSON structured like this:
{
"custom_item": {
"id": 2,
"custom_section_id": 1,
"position": 1,
"name": "Sangria",
"description": "Fruit, Sweetened",
"type": "cocktail",
"custom_item_type_id": 2,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:58Z",
"updated_at": "2016-09-29T19:22:38Z"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/custom_items/:id
PATCH https://business.untappd.com/api/v1/custom_items/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the item. |
name | String | false | The custom item name. |
description | String | false | The custom item description. |
type | wine/cocktail/food | true | The custom item type. |
Delete a custom item
Permanently deletes a custom item. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/custom_items/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04="
Returns the deleted custom item as JSON structured like this:
{
"custom_item": {
"id": 1,
"custom_section_id": 1,
"position": 2,
"name": "ccccc",
"description": "c",
"type": "wine",
"custom_item_type_id": 1,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392c-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:56Z",
"updated_at": "2016-09-29T18:48:19Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/custom_items/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The custom item to be deleted. |
Update custom item positions
Set the positions of custom items in a custom section. Custom item positions are used to order the custom items within a custom section of a published custom menu on a page.
Important!: When updating custom item positions, all custom items for the custom section must be passed and the positions must start at zero. Use List all custom items first to get all the custom items for the custom section.
Request:
curl "http://localhost:3000/api/v1/custom_sections/1/custom_items/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "custom_items": [{ "id": 2, "position": 1 }, { "id": 3, "position": 0 }] }'
Returns JSON structured like this:
{
"custom_items": [
{
"id": 3,
"position": 0
},
{
"id": 2,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/custom_sections/:custom_section_id/custom_items/positions
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_section_id | Integer | true | The custom section to update custom item positions for. |
custom_items | Array | true | An Array of Objects. All the custom items for a custom section should be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
id | Integer | true | The custom item id to update the position for. |
position | Integer | true | The position to set the custom item at. Custom item positions must start at zero. |
Move a custom item to another custom section
Move the specified custom item to another custom section.
Request:
curl "http://localhost:3000/api/v1/custom_items/2/move" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286TDFleXpzTnhWU2ZZOE1kWkxjN04=" \
-H "Content-Type: application/json" \
-d '{ "custom_item": { "custom_section_id": 3 } }'
Returns JSON structured like this:
{
"custom_item": {
"id": 2,
"custom_section_id": 3,
"position": 0,
"name": "Sangria",
"description": "Fruit, Sweetened",
"type": "cocktail",
"custom_item_type_id": 2,
"image_url_for_type": "//s3.amazonaws.com/woof.nextglass.co/custom_item_type_images_production/36b7fa2ac48d10381ec79332cb5e5d6ef13e392b-custom-item-type-image.png",
"created_at": "2016-09-29T17:04:58Z",
"updated_at": "2016-09-29T19:25:51Z"
}
}
HTTP Request
PATCH https://business.untappd.com/api/v1/custom_items/:id/move
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom item. |
custom_section_id | Integer | true | The custom_section_id of the custom section to move the custom item to. |
Custom Menus [Deprecated]
- A location has many custom menus.
- A custom menu belongs to a location.
- A custom menu has many custom sections.
List all custom menus
Returns a list of custom menus belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/3/custom_menus" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this:
{
"custom_menus": [
{
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:10:37Z",
"position": 0
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/custom_menus
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The id of the location. |
Create a custom menu
Creates a new custom menu.
Request:
curl "http://localhost:3000/api/v1/locations/3/custom_menus" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_menu": { "name": "Wine selection" } }'
Returns JSON structured like this:
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:10:37Z",
"position": 0
}
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/custom_menus
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The id of the location. |
name | String | true | The custom menu name. |
Retrieve a custom menu
Retrieve the details of an existing custom menu. You need only supply the unique custom menu identifier that was returned upon custom menu creation.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this:
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:10:37Z",
"position": 0
}
}
Or...
To get the full custom menu use the full param with the request:
curl "http://localhost:3000/api/v1/custom_menus/1?full=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this:
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:30:08Z",
"updated_at": "2016-09-26T20:35:27Z",
"position": 0,
"custom_sections": [
{
"id": 1,
"custom_menu_id": 1,
"position": 0,
"name": "",
"description": "",
"created_at": "2016-09-26T20:30:08Z",
"updated_at": "2016-09-26T20:30:08Z",
"custom_items": []
}
]
}
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_menus/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom menu. |
full | true or not set | false | Returns the entire custom menu tree with custom sections, custom items, and custom containers. 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 custom menu
Updates the specified custom menu by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_menu": { "name": "Super Awesome Food Menu" } }'
Returns JSON structured like this:
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Super Awesome Food Menu",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:19:38Z",
"position": 0
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/custom_menus/:id
PATCH https://business.untappd.com/api/v1/custom_menus/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom menu. |
name | String | false | The custom menu name. |
description | String | false | The custom menu description. |
footer | String | false | The custom menu footer. |
Delete a custom menu
Permanently deletes a custom menu. It cannot be undone. If the custom menu is already published then it will first be unpublished and then deleted.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns the deleted custom menu as JSON structured like this:
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Super Awesome Food Menu",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:20:48Z",
"position": 0
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/custom_menus/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The custom menu to be deleted. |
Delete Multiple Custom Menus
Permanently deletes custom menus. It cannot be undone. If the custom menus are already published then they will first be unpublished and then deleted.
Request:
curl "http://localhost:3000/api/v1/locations/3/custom_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/custom_menus
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The location to delete custom menus for. |
ids | Array | true | An Array of ids. All the custom menu ids for the location to be deleted. |
Update custom menu positions
Set the positions of custom menus in a location. Custom menu positions are used to order the published custom menus on a page.
Important!: When updating custom menu positions, all custom menus for the location must be passed and the positions must start at zero. Use List all custom menus first to get all the custom menus for the location.
Request:
curl "http://localhost:3000/api/v1/locations/3/custom_menus/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_menus": [{ "id": 1, "position": 1 }, { "id": 3, "position": 0 }] }'
Returns JSON structured like this:
{
"custom_menus": [
{
"id": 3,
"position": 0
},
{
"id": 1,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/locations/:location_id/custom_menus/positions
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The location to update custom menu positions for. |
custom_menus | Array | true | An Array of Objects. All the custom menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
id | Integer | true | The custom menu id to update the position for. |
position | Integer | true | The position to set the custom menu at. Custom menu positions must start at zero. |
Publish all custom menus
Publish all the unpublished custom menus of a location. Any changes to a published custom menu will automatically take effect.
Request:
curl "http://localhost:3000/api/v1/locations/3/custom_menus/publish_all" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this (notice unpublished is now set to:
false
):
{
"custom_menus": [
{
"id": 1,
"location_id": 3,
"name": "Super Awesome Food Menu",
"description": "",
"unpublished": false,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:20:48Z",
"position": 0
},
{
"id": 2,
"location_id": 3,
"name": "Super Awesome Cocktail Menu",
"description": "",
"unpublished": false,
"created_at": "2016-09-26T20:10:37Z",
"updated_at": "2016-09-26T20:20:48Z",
"position": 0
}
]
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/custom_menus/publish_all
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The location. |
Publish a custom menu
Publish a custom menu. There is no need to republish a custom menu that has already been published. Any changes to a published custom menu will automatically take effect.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1/publish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this (notice unpublished is now set to:
false
):
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": false,
"created_at": "2016-09-26T20:30:08Z",
"updated_at": "2016-09-26T20:32:44Z",
"position": 0
}
}
HTTP Request
POST https://business.untappd.com/api/v1/custom_menus/:id/publish
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The custom menu to publish. |
Unpublish a custom menu
Unpublish a custom menu.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1/unpublish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this (notice unpublished is now set to:
true
):
{
"custom_menu": {
"id": 1,
"location_id": 3,
"name": "Wine selection",
"description": "",
"unpublished": true,
"created_at": "2016-09-26T20:30:08Z",
"updated_at": "2016-09-26T20:35:27Z",
"position": 0
}
}
HTTP Request
POST https://business.untappd.com/api/v1/custom_menus/:id/unpublish
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The custom menu to unpublish. |
Custom Sections [Deprecated]
- A custom section belongs to a custom menu.
- A custom section has many custom items.
List all custom sections
List all the custom sections of a custom menu.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this:
{
"custom_sections": [
{
"id": 1,
"custom_menu_id": 1,
"position": 0,
"name": "Red wines",
"description": "",
"created_at": "2016-09-26T20:30:08Z",
"updated_at": "2016-09-26T20:30:08Z"
},
{
"id": 2,
"custom_menu_id": 1,
"position": 1,
"name": "White wines",
"description": "",
"created_at": "2016-09-26T20:46:33Z",
"updated_at": "2016-09-26T20:46:33Z"
}
]
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_menu_id | Integer | true | The custom menu to lookup the custom sections for. |
Create a custom section
Creates a new custom section belonging to a custom menu.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_section": { "name": "Red Wine", "description": "Our red wine selection." } }'
Returns JSON structured like this:
{
"custom_section": {
"id": 2,
"custom_menu_id": 1,
"position": 1,
"name": "Red Wine",
"description": "Our red wine selection.",
"created_at": "2016-09-26T20:46:33Z",
"updated_at": "2016-09-26T20:46:33Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_menu_id | Integer | true | The id of the custom menu. |
head | true or false | true | Adds the new custom section to the head of the list of custom sections for this custom menu when head is true. Otherwise the new custom section will be appended to the end. |
name | String | false | A name for the new custom section. |
description | String | A description for the new custom section. |
Retrieve a custom section
Retrieve the details of an existing custom section. You need only supply the unique custom section identifier that was returned upon custom section creation.
Request:
curl "http://localhost:3000/api/v1/custom_sections/2" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns JSON structured like this:
{
"custom_section": {
"id": 2,
"custom_menu_id": 1,
"position": 1,
"name": "Other beers",
"description": "Our beers that are not dark or light.",
"created_at": "2016-09-26T20:46:33Z",
"updated_at": "2016-09-26T20:46:33Z"
}
}
HTTP Request
GET https://business.untappd.com/api/v1/custom_sections/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom section. |
Update a custom section
Updates the specified custom section by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Request:
curl "http://localhost:3000/api/v1/custom_sections/2" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_section": { "description": "All the rest..." } }'
Returns JSON structured like this:
{
"custom_section": {
"id": 2,
"custom_menu_id": 1,
"position": 1,
"name": "Other beers",
"description": "All the rest...",
"created_at": "2016-09-26T20:46:33Z",
"updated_at": "2016-09-27T13:34:27Z"
}
}
HTTP Request
PUT https://business.untappd.com/api/v1/custom_sections/:id
PATCH https://business.untappd.com/api/v1/custom_sections/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the section. |
name | String | false | The custom section name. |
description | String | false | The custom section description. |
Delete a custom section
Permanently deletes a custom section. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/custom_sections/2" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0="
Returns the deleted custom section as JSON structured like this:
{
"custom_section": {
"id": 2,
"custom_menu_id": 1,
"position": 1,
"name": "Other beers",
"description": "All the rest...",
"created_at": "2016-09-26T20:46:33Z",
"updated_at": "2016-09-27T13:34:27Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/custom_sections/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The id of the custom section. |
Update custom section positions
Set the positions of custom sections in a custom menu. Custom section positions are used to order the custom sections of a published custom menu on a page.
Important!: When updating custom section positions, all custom sections for the custom menu must be passed and the positions must start at zero. Use List all custom sections first to get all the custom sections for the custom menu.
Request:
curl "http://localhost:3000/api/v1/custom_menus/1/custom_sections/positions" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286OW5kTWZESEJGcWJKeTJXdDlCeC0=" \
-H "Content-Type: application/json" \
-d '{ "custom_sections": [{ "id": 1, "position": 1 }, { "id": 2, "position": 0 }] }'
Returns JSON structured like this:
{
"custom_sections": [
{
"id": 2,
"position": 0
},
{
"id": 1,
"position": 1
}
]
}
HTTP Request
PATCH https://business.untappd.com/api/v1/custom_menus/:custom_menu_id/custom_sections/positions
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
custom_menu_id | Integer | true | The custom menu to update custom section positions for. |
custom_sections | Array | true | An Array of Objects. All the custom sections for a custom menu must be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
id | Integer | true | The custom section id to update the position for. |
position | Integer | true | The position to set the custom section at. Custom section positions must start at zero. |
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_by
param 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.
List all items
Returns a list of items belonging to a section.
Request:
curl "http://localhost:3000/api/v1/sections/1/items" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"items": [
{
"id": 3,
"section_id": 1,
"position": 0,
"untappd_id": 4473,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
"label_image_hd": "https://labels.untappd.com/labels/4473?size=hd",
"brewery_location": "Dublin 8",
"abv": "4.3",
"ibu": "45.0",
"cask": false,
"nitro": false,
"tap_number": null,
"rating": "3.81587",
"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.\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",
"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.\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",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"custom_brewery": null,
"original_brewery": "Guinness",
"created_at": "2016-11-08T15:02:12Z",
"updated_at": "2016-11-08T15:02:12Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": 2,
"section_id": 1,
"position": 1,
"untappd_id": 19004,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
"label_image_hd": "https://labels.untappd.com/labels/19004?size=hd",
"brewery_location": "Boston, MA",
"abv": "27.0",
"ibu": "0.0",
"cask": false,
"nitro": false,
"tap_number": null,
"rating": "4.47778",
"in_production": true,
"untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
"untappd_brewery_id": 157,
"name": "Samuel Adams Utopias",
"original_name": "Samuel Adams Utopias",
"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.",
"custom_description": null,
"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.",
"style": "Strong Ale - American",
"custom_style": null,
"original_style": "Strong Ale - American",
"brewery": "Boston Beer Company",
"custom_brewery": null,
"original_brewery": "Boston Beer Company",
"created_at": "2016-11-08T15:01:54Z",
"updated_at": "2016-11-08T15:01:54Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
]
}
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. The data for the item is automatically populated from the beer database.
Note: This route will accept an array of integers for untappd_id
to batch add multiple items at once.
Request:
curl "http://localhost:3000/api/v1/sections/1/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": 4,
"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": false,
"nitro": false,
"tap_number": null,
"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 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.",
"custom_description": null,
"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-08T15:08:49Z",
"updated_at": "2016-11-08T15:08:49Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/sections/:section_id/items
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
section_id | Integer | true | The section to add the item to. |
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 |
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/4" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"item": {
"id": 4,
"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": false,
"nitro": false,
"tap_number": null,
"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 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.",
"custom_description": null,
"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-08T15:08:49Z",
"updated_at": "2016-11-08T15:08:49Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
}
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/4" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "item": { "cask": true, "description": "All the rest...", "tap_number": 1, "brewery": "Russian River Brewing Co." } }'
Returns JSON structured like this:
{
"item": {
"id": 4,
"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-08T15:08:49Z",
"updated_at": "2016-11-08T16:18:51Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
}
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/4" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns the deleted item as JSON structured like this:
{
"item": {
"id": 4,
"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-08T15:08:49Z",
"updated_at": "2016-11-08T16:18:51Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
}
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/1/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/2/move" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc=" \
-H "Content-Type: application/json" \
-d '{ "item": { "section_id": 3 } }'
Returns JSON structured like this:
{
"item": {
"id": 2,
"section_id": 3,
"position": 0,
"untappd_id": 19004,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
"brewery_location": "Boston, MA",
"abv": "27.0",
"ibu": "0.0",
"cask": false,
"nitro": false,
"tap_number": null,
"rating": "4.47778",
"in_production": true,
"untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
"untappd_brewery_id": 157,
"name": "Samuel Adams Utopias",
"original_name": "Samuel Adams Utopias",
"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.",
"custom_description": null,
"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.",
"style": "Strong Ale - American",
"custom_style": null,
"original_style": "Strong Ale - American",
"brewery": "Boston Beer Company",
"custom_brewery": null,
"original_brewery": "Boston Beer Company",
"created_at": "2016-11-08T15:01:54Z",
"updated_at": "2016-11-08T16:25:35Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
}
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": 0,
"untappd_id": 3883,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-3883_a0aa4_sm.jpeg",
"brewery_location": null,
"abv": "4.6",
"ibu": null,
"cask": false,
"nitro": false,
"tap_number": null,
"rating": null,
"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": null,
"custom_description": null,
"original_description": null,
"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": null,
"updated_at": null,
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": null,
"section_id": null,
"position": 0,
"untappd_id": 3884,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-PabstBlueRibbonLight_3884.jpeg",
"brewery_location": null,
"abv": "4.19",
"ibu": null,
"cask": false,
"nitro": false,
"tap_number": null,
"rating": null,
"in_production": true,
"untappd_beer_slug": "pabst-brewing-company-pabst-blue-ribbon-light",
"untappd_brewery_id": 963,
"name": "Pabst Blue Ribbon Light",
"original_name": "Pabst Blue Ribbon Light",
"custom_name": null,
"description": null,
"custom_description": null,
"original_description": null,
"style": "Lager - American Light",
"custom_style": null,
"original_style": "Lager - American Light",
"brewery": "Pabst Brewing Company",
"custom_brewery": null,
"original_brewery": "Pabst Brewing Company",
"created_at": null,
"updated_at": null,
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": null,
"section_id": null,
"position": 0,
"untappd_id": 407497,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_407497_sm_cc8e22fe9e89e8db21eef386d4800e.jpeg",
"brewery_location": null,
"abv": "5.4",
"ibu": null,
"cask": false,
"nitro": false,
"tap_number": null,
"rating": null,
"in_production": true,
"untappd_beer_slug": "barley-browns-beer-point-blank-red",
"untappd_brewery_id": 7046,
"name": "Point Blank Red",
"original_name": "Point Blank Red",
"custom_name": null,
"description": null,
"custom_description": null,
"original_description": null,
"style": "Red Ale - American Amber / Red",
"custom_style": null,
"original_style": "Red Ale - American Amber / Red",
"brewery": "Barley Brown's Beer",
"custom_brewery": null,
"original_brewery": "Barley Brown's Beer",
"created_at": null,
"updated_at": null,
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
]
}
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": 3,
"section_id": 1,
"position": 0,
"untappd_id": 4473,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-_4473_8122008947804818c90640a06d83.jpeg",
"brewery_location": "Dublin 8",
"abv": "4.3",
"ibu": "45.0",
"cask": false,
"nitro": false,
"tap_number": null,
"rating": "3.81587",
"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.\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",
"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.\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",
"style": "Stout - Irish Dry",
"custom_style": null,
"original_style": "Stout - Irish Dry",
"brewery": "Guinness",
"custom_brewery": null,
"original_brewery": "Guinness",
"created_at": "2016-11-08T15:02:12Z",
"updated_at": "2016-11-08T15:02:12Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
},
{
"id": 2,
"section_id": 1,
"position": 1,
"untappd_id": 19004,
"label_image": "https://untappd.akamaized.net/site/beer_logos/beer-bostonUtopias.jpg",
"brewery_location": "Boston, MA",
"abv": "27.0",
"ibu": "0.0",
"cask": false,
"nitro": false,
"tap_number": null,
"rating": "4.47778",
"in_production": true,
"untappd_beer_slug": "boston-beer-company-samuel-adams-utopias",
"untappd_brewery_id": 157,
"name": "Samuel Adams Utopias",
"original_name": "Samuel Adams Utopias",
"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.",
"custom_description": null,
"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.",
"style": "Strong Ale - American",
"custom_style": null,
"original_style": "Strong Ale - American",
"brewery": "Boston Beer Company",
"custom_brewery": null,
"original_brewery": "Boston Beer Company",
"created_at": "2016-11-08T15:01:54Z",
"updated_at": "2016-11-08T16:28:30Z",
"type": "beer",
"default_image": "https://untappd.akamaized.net/site/assets/images/temp/badge-beer-default.png"
}
]
}
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
canceled
is 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.
List all menus
Returns a list of menus belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/3/menus" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menus": [
{
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-16T19:57:33Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
]
}
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 location to update menu positions for. |
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/3/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": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Draft Beer List",
"description": null,
"footer": null,
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-16T19:57:33Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
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/1" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menu": {
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-16T19:57:33Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
Or...
To get the full menu use the full param with the request:
curl "http://localhost:3000/api/v1/menus/3?full=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this:
{
"menu": {
"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:02:49Z",
"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:02:49Z",
"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:02:49Z",
"containers": [
{
"id": 13,
"item_id": 10,
"container_size_id": 5,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T17:02:49Z",
"updated_at": "2016-11-08T17:02:49Z",
"container_size": {
"id": 5,
"name": "Crowler",
"position": 101,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 13
}
],
"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:02:49Z",
"containers": [
{
"id": 14,
"item_id": 11,
"container_size_id": 5,
"price": "3.99",
"currency": "USD",
"position": 0,
"created_at": "2016-11-08T17:02:49Z",
"updated_at": "2016-11-08T17:02:49Z",
"container_size": {
"id": 5,
"name": "Crowler",
"position": 101,
"created_at": "2016-03-01T15:36:26Z",
"updated_at": "2016-08-24T20:55:13Z"
},
"_track_by": 14
}
],
"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
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/1" \
-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": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-17T14:07:48Z",
"column_formatting": "column_formatting_single_column",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
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/1" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns the deleted menu as JSON structured like this:
{
"menu": {
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-17T14:07:48Z",
"column_formatting": "column_formatting_single_column",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
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/3/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 Objects. All the menus for a location must be passed as a batch to be update atomically. Unexpected behavior may result otherwise. |
id | Integer | true | The 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/3/menus/publish_all" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublished
is now set to:false
):
{
"menus": [
{
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": false,
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-17T14:34:11Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 1
},
{
"id": 3,
"location_id": 3,
"uuid": "1b11b983-d90d-40bf-afc6-a5d55ab3e5f9",
"unpublished": false,
"name": "Three Commas",
"description": null,
"footer": null,
"created_at": "2016-06-17T13:41:36Z",
"updated_at": "2016-06-17T14:34:11Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
]
}
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/1/publish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublished
is now set to:false
):
{
"menu": {
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": false,
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-17T14:39:29Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
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/1/unpublish" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286eUN3Q2l4YWdvdzFMbXctdE5jajc="
Returns JSON structured like this (notice
unpublished
is now set to:true
):
{
"menu": {
"id": 1,
"location_id": 3,
"uuid": "98e37027-3f8e-45c7-b9a0-4984128be836",
"unpublished": true,
"name": "Super Awesome Draft Beer List",
"description": "All the draft beers.",
"footer": "Heavy vs. Light or Good vs. Evil? You Decide.",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-17T15:00:42Z",
"published_at_embed": null,
"published_at_untappd": null,
"published_at_facebook": null,
"position": 0
}
}
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/1/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.
List all sections
List all the sections of a menu.
Request:
curl "http://localhost:3000/api/v1/menus/1/sections?include_on_deck_section=true" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns JSON structured like this:
{
"sections": [
{
"id": 1,
"menu_id": 1,
"position": 0,
"name": "Heavy",
"description": "All our heavy draft beers.",
"type": "Section",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-16T19:55:48Z"
},
{
"id": 2,
"menu_id": 1,
"position": 1,
"name": "Light",
"description": "All our light beers.",
"type": "Section",
"created_at": "2016-06-16T19:55:58Z",
"updated_at": "2016-06-16T19:56:40Z"
},
{
"id": 3,
"menu_id": 1,
"position": 0,
"name": "On Deck",
"description": "",
"type": "OnDeckSection",
"created_at": "2016-06-16T19:53:37Z",
"updated_at": "2016-06-16T19:55:48Z"
}
]
}
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/1/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": 6,
"menu_id": 1,
"position": 2,
"name": "Other beers",
"description": "Our beers that are not dark or light.",
"created_at": "2016-06-17T15:09:40Z",
"updated_at": "2016-06-17T15:09:40Z"
}
}
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 | 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/6" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns JSON structured like this:
{
"section": {
"id": 6,
"menu_id": 1,
"position": 2,
"name": "Other beers",
"description": "Our beers that are not dark or light.",
"created_at": "2016-06-17T15:09:40Z",
"updated_at": "2016-06-17T15:09:40Z"
}
}
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/6" \
-X PATCH \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8=" \
-H "Content-Type: application/json" \
-d '{ "section": { "description": "All the rest..." } }'
Returns JSON structured like this:
{
"section": {
"id": 6,
"menu_id": 1,
"position": 2,
"name": "Other beers",
"description": "All the rest...",
"type": "Section",
"created_at": "2016-06-17T15:09:40Z",
"updated_at": "2016-06-17T15:18:30Z"
}
}
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/6" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286S2t5cTE2dWtORHVtbzRUV3QzTF8="
Returns the deleted section as JSON structured like this:
{
"section": {
"id": 6,
"menu_id": 1,
"position": 2,
"name": "Other beers",
"description": "All the rest...",
"created_at": "2016-06-17T15:09:40Z",
"updated_at": "2016-06-17T15:18:30Z"
}
}
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/1/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. |
Social Announcements
- A location has many social announcements
List all social announcements
Returns a list of social announcements belonging to your location.
Request:
curl "http://localhost:3000/api/v1/locations/3/social_announcements" \
-X GET \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="
Returns JSON structured like this:
{
"social_announcements": {
"upcoming": [
{
"id": 7,
"location_id": 3,
"created_at": "2016-10-12T15:17:38Z",
"updated_at": "2016-10-12T15:17:38Z",
"content": "This is an announcement that goes out once per week.",
"period": "once",
"canceled": false,
"next_publish_at": "2016-11-15T18:21:51Z",
"last_published_at": null,
"type": "SocialAnnouncement",
"post_to_facebook": false,
"post_to_twitter": true,
"display_on_embed_menu": false,
"display_on_print_menu": false,
"display_on_digital_board": false,
"image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/65e518beb4fe8ecee7a3e6c2e078723e75cdf889.svg?1476285458",
"image_updated_at": "2016-10-12T15:17:38Z"
}
],
"weekly": [
{
"id": 6,
"location_id": 3,
"created_at": "2016-10-12T15:09:07Z",
"updated_at": "2016-10-12T15:09: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": "SocialAnnouncement",
"post_to_facebook": false,
"post_to_twitter": true,
"display_on_embed_menu": false,
"display_on_print_menu": false,
"display_on_digital_board": false,
"image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/240322ed5b0b074f4cbbd596c5080ef438f9d719.svg?1476284947",
"image_updated_at": "2016-10-12T15:09:07Z"
}
]
}
}
HTTP Request
GET https://business.untappd.com/api/v1/locations/:location_id/social_announcements
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
location_id | Integer | true | The id of the location. |
Create a social announcement
Creates a new social announcement.
Request:
curl "http://localhost:3000/api/v1/locations/3/social_announcements" \
-X POST \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko=" \
-H "Content-Type: application/json" \
-d '{ "social_announcement": { "content": "This is an announcement that goes out once per week.", "period": "weekly", "next_publish_at": "2016-11-15T13:21:51Z", "post_to_twitter": true, "image_remote_url": "https://d2q2v9tznh5hzu.cloudfront.net/assets/untappd-logo-a7618c61b0c901c636054446ebe4a19687b132cd98188bb8c33e20cf5294ec83.svg" } }'
Returns JSON structured like this:
{
"social_announcement": {
"id": 6,
"location_id": 3,
"created_at": "2016-10-12T15:09:07Z",
"updated_at": "2016-10-12T15:09: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": "SocialAnnouncement",
"post_to_facebook": false,
"post_to_twitter": true,
"display_on_embed_menu": false,
"display_on_print_menu": false,
"display_on_digital_board": false,
"image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/240322ed5b0b074f4cbbd596c5080ef438f9d719.svg?1476284947",
"image_updated_at": "2016-10-12T15:09:07Z"
}
}
HTTP Request
POST https://business.untappd.com/api/v1/locations/:location_id/social_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!" |
image_remote_url | String | false | A url to an image for the announcement. |
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. |
post_to_facebook | Boolean | false | Indicates that the announcement should be posted to Facebook. |
post_to_twitter | Boolean | false | Indicates that the announcement should be posted to Twitter. |
Cancel a social announcement
Permanently deletes a social announcement. It cannot be undone.
Request:
curl "http://localhost:3000/api/v1/social_announcements/4" \
-X DELETE \
-H "Authorization: Basic bmlja0BuZXh0Z2xhc3MuY286VUJnelJtUnpLZl9YUTZ5RHV0Qko="
Returns the canceled social announcement as JSON structured like this. Notice
canceled
is nowtrue
.):
{
"social_announcement": {
"id": 4,
"location_id": 3,
"created_at": "2016-10-12T15:03:29Z",
"updated_at": "2016-10-12T15:17:15Z",
"content": "This is an announcement that goes out once per week.",
"period": "weekly",
"canceled": true,
"next_publish_at": "2016-11-15T18:21:51Z",
"last_published_at": null,
"type": "SocialAnnouncement",
"post_to_facebook": false,
"post_to_twitter": true,
"display_on_embed_menu": false,
"display_on_print_menu": false,
"display_on_digital_board": false,
"image_url": "https://s3.amazonaws.com/woof-announcements.nextglass.co/7dcaf01a343b9f100417c791efcbfa25eea4d470.?1476284609",
"image_updated_at": "2016-10-12T15:03:29Z"
}
}
HTTP Request
DELETE https://business.untappd.com/api/v1/social_announcements/:id
Query Parameters
Parameter | Validations | Required | Description |
---|---|---|---|
id | Integer | true | The social announcement to be canceled. |
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.
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 Deck
section.
2017-10-12
Added:
- GraphQL section added to docs.
2016-11-22
Added:
- List Sections now has
include_on_deck_section
parameter to include the section withtype=OnDeckSection
in the results. - Update Sections now accepts the
name
parameter 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
position
properties.position
on every container in the item will automatically be updated when one containerposition
is set.
Changed:
- Containers are now by default sorted by their
position
property instead ofcreated_at
.
2016-11-08
Added:
- Item
custom_brewery
andoriginal_brewery
properties.
Changed:
- Item
brewery
behavior. Will now equalcustom_brewery
whencustom_brewery
is not null, otherwise defaults tooriginal_brewery
.