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.

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 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.

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.

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.

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. 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.

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 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 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

A location has many 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.

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.

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 now true.):

{
  "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, 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.

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 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.

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.

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.

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. 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.

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.

A location has many 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.

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.

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 now true.):

{
  "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 with type=OnDeckSection in the results.
Update Sections now accepts the name parameter for sections with type=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 container position is set.

Changed:

Containers are now by default sorted by their position property instead of created_at.

2016-11-08

Added:

Item custom_brewery and original_brewery properties.

Changed:

Item brewery behavior. Will now equal custom_brewery when custom_brewery is not null, otherwise defaults to original_brewery.

Introduction

Version - /api/v1

TLS Versions

Authentication

You can find your tokens under the section titled "API Access Tokens" at: https://business.untappd.com/account.

API Token Types

POST /sessions

Reset session

HTTP Request

Analytics

Track an event

HTTP Request

Query Parameters

Container Sizes

List all container sizes

HTTP Request

Containers

List all containers

HTTP Request

Query Parameters

Create a container

HTTP Request

Query Parameters

Retrieve a container

HTTP Request

Query Parameters

Update a container

HTTP Request

Query Parameters

Delete a container

HTTP Request

Query Parameters

Current User

HTTP Request

Custom Containers [Deprecated]

List all custom containers

HTTP Request

Query Parameters

Create a custom container

HTTP Request

Query Parameters

Retrieve a custom container

HTTP Request

Query Parameters

Update a custom container

HTTP Request

Query Parameters

Delete a custom container

HTTP Request

Query Parameters

Custom Item Types [Deprecated]

List all custom item types

HTTP Request

Custom Items [Deprecated]

List all custom items

HTTP Request

Query Parameters

Create a custom item

HTTP Request

Query Parameters

Retrieve a custom item

HTTP Request

Query Parameters

Update a custom item

HTTP Request

Query Parameters

Delete a custom item

HTTP Request

Query Parameters

Update custom item positions

HTTP Request

Query Parameters

Move a custom item to another custom section

HTTP Request

Query Parameters

Custom Menus [Deprecated]

List all custom menus

HTTP Request

Query Parameters

Create a custom menu