Get alcohol products offered by local alcohol merchants. Endpoint supports search and advanced filtering and sort.

Request

HTTP Request

GET /data/search/?search_type=alcohol

Resource Information

Parameter Value
Response Format JSON
Authentication pass in client_id only
Rate Limited Yes

Authentication

Unauthenticated API request. Simply pass in the client_id. You can receive a client_id after signing up for a developer account.

Full Example URL

https://api.delivery.com/data/search?search_type=alcohol&address=1006+Avenue+of+the+Americas,10018&order_time=ASAP&order_type=delivery&client_id=brewhacks2016

Parameters

All parameter keys should be lowercase; parameter values should all be UTF-8 and URL-encoded.

Parameter Name Type Description
Required Parameters
address String The address where the user is. Acceptable formats include ‘Address, City, State’ and ‘Address, Zip’. We’ll validate the address for you.
latitude String The latitude of the search location. Only required if not sending an address.
longitude String The longitude of the search location. Only required if not sending an address.
order_type string Set the order type to either delivery or pickup.
order_time string Time of order. Set to ASAP for as soon as possible on demand delivery. Or, set it for a future order time. Make sure to include the timezone information otherwise it will to default UTC. We recommend ISO8601 2016-04-07T23:45:00-0400.
Optional Parameters
keyword string Search by product name. Supports fuzzy search and advanced prefix search. String must be UTF-8, URL-encoded, and less than 500 characters in length.
section string Alcohol type searching on. Valid values include beer, liquor, wine. Defaults to all.
subsection string Comma delimited list of subcategories to search on.”
filter_size string Filter based on size.
filter_country string Filter based on country.
filter_price integer Filter based on price groups. This filter does not take in dynamic values.
limit integer Limit the number of X items to return per deepest category level.
limit_if_segmented integer Variation to the regular limit parameter. Results will only be limited if 2 or more categories are returned.
sort string Define the sort style for the products. Currently support name and price. Prefix the sort by a minus to denote descending sort. ?sort=-name searches Z to A.
merchant_ids string Comma separated list of all merchant ids (or merchant slugs) to search against. This will only override the default merchants ids selected by geolocation if the passed in merchants are in delivery range.
inexact boolean Include inexact=true to perform to search approximate addresses, such as finding all products that are available in a particular zip code, neighborhood, or point of interest.

section

optionalstring
Pass in alcohol type to restrict search. Only pass in one value at a time.

Type Identifier
All Types all
Beer beer
Liquor liquor
Wine wine
?section=wine

subsection

optional – string
Comma delimited list of subcategories to search on. The section (wine, liquor, beer) should also be passed in. The filtering system may return unexpected results without specified section (but should still work).

?section=wine&subsection=kosher
?section=wine&subsection=red,white,kosher
?section=wine&subsection=red.pinot-grigio,red.merlot,white.rice

filter_size

optional – string
Filter based on country. Put multiple values in a comma separated list.

?filter_size=750mL,1L

filter_price

optional – string
Filter based on price. Currently this filter does not take in dynamic values. Simply pass in 1, 2, 3, or 4. As the response for filters payload shows.

Price Group Identifier
null no filter
Under $10 1
$10 to $20 2
$20 to $30 3
$30 to $50 4
$50 and above 5

Defaults to no price filter being applied.

Request Body

Do not supply a request body with this method.

Response

Response Structure

{
"data" : {
    "categories" : [ ... ],
    "filters" : [ ... ],
    "products" : { ... }
    "breadcrumbs" : [],
    "sort": { ... }
    "merchants" : [ ... ]
}
Key Explanation
Categories Category tree of all alcohol categories starting.
Filters List all the available filters for the currently selected products.
products Lists all the product information including the picture thumbnail. The id value links to the product ids listed in the category tree and is used for internal matching only. The unique product_id is product_id (alphanumeric string).
breadcrumbs Shows the current location of the search. Breadcrumbs will not work properly if multiple subsection values are listed.
sort Available sort options
merchants Fully hydrated merchant object
search_address This is the geocoded address of your search. You might want to store it for later use in the location API. If passing inexact=true, be sure to check whether is_exact_match is true or false. This will indicate whether the address points to a real location or is just approximate. When dealing with approximate addresses, you’ll need to prompt users for their actual addresses later in the process to add items to their carts.

Categories

   "categories" : [
      {
        "name" : "Wine",
        "value" : "wine",
        "key" : "section",
        "is_selected" : true,
        "children" : [
          {
            "name" : "Red",
            "value" : "red",
            "key" : "subsection",
            "is_selected" : false,
            "children" : [
              {
                "name" : "Cabernet Sauvignon",
                "value" : "red.cabernet-sauvignon",
                "key" : "subsection",
                "is_selected" : false,
                "count" : 47,
                "children" : [],
                "product_ids" : [4, 10, 21, 39, 195]
              }
              {
                "name" : "Sangiovese",
                "value" : "red.sangiovese",
                "key" : "subsection",
                "is_selected" : false,
                "count" : 11,
                "children" : [],
                "product_ids" : [5, 42, 74, 80, 499]
              }
            ]
          }
        ]
      }
    ],

The results come back as a nested tree of categories starting from the top most beer / liquor / wine category.

  • name – title of category
  • value / key – used for category filtering
  • is_selected – boolean denoting whether category is currently selected (filtered)
  • count – number of products matching the filter selection. Parent categories will count all matched children products.
  • children – category children of the parent category.
  • product_ids – internal product ids only valid for this request. Match the product id to the key of the products object. The product object will include a unique id product_id.

Use the key and value of a child to properly filter categories. For “cabernet Sauvignon”, pass in:

?subsection=red.cabernet-sauvignon

The dot notation denotes that the category is a parent of “red” (wine).

Filters

    "filters" : [
      {
        "name" : "Country",
        "key" : "filter_country",
        "multi_selectable" : true,
        "children" : [
          {
            "name" : "France",
            "value" : "france",
            "is_selected" : false,
            "count" : 32
          }
          {
            "name" : "United States",
            "value" : "united-states",
            "is_selected" : false,
            "count" : 93
          }
        ]
      }
      {
        "name" : "Price",
        "key" : "filter_price",
        "multi_selectable" : true,
        "children" : [
          {
            "name" : "$30 to $50",
            "value" : 4,
            "is_selected" : false,
            "count" : 19
          }
          {
            "name" : "$20 to $30",
            "value" : 3,
            "is_selected" : false,
            "count" : 19
          }
        ]
      }
      {
        "name" : "Size",
        "key" : "filter_size",
        "multi_selectable" : true,
        "children" : [
          {
            "name" : "750ml",
            "value" : "750ml",
            "is_selected" : false,
            "count" : 262
          }
          {
            "name" : "500ml",
            "value" : "500ml",
            "is_selected" : false,
            "count" : 125
          }
        ]
      }
    ],
  • key / value – Used for filtering
  • multi_selectable – all filters are multi-selectable but this may change in the future.
  • count – number of products matching the current filter if not selected; or, the number of products that will match the filter once it is selected.

Use the key and value of the child to filter:

?filter_country=france
?filter_price=3,4
?filter_size=750ml,500ml

Products

"products" : {
      "4" : {
        "id" : 4,
        "product_id" : "39773",
        "merchant_ids" : [72167],
        "name" : "Caymus Vineyards Cabernet Sauvignon Napa Valley",
        "type" : "wine",
        "size" : "750ml",
        "price" : 71.99,
        "size_price" : [
          {
             "size": "750ml",
             "price": 71.99,
             "quantity": 1
          }
          {
             "size": "1L",
             "price": 120.99,
             "quantity": 1
          }
        ],
        "categories" : ["red.cabernet-sauvignon"],
        "tags" : [
          {
            "key" : "grape",
            "value" : ["red", "cabernet-sauvignon"]
          },
          {
            "key" : "brand",
            "value" : "Caymus Vineyards"
          },
          {
            "key" : "origin",
            "value" : "Sacremento, California",
          },
          {
            "key": "info",
            "value": ["sparkling"]
          }
        ],
        "image" : "https://dcom-standardized-data-dev.s3.amazonaws.com/master_list/images/55e879328f3b0b88478b5e71/55e879328f3b0b88478b5e71_0.jpg",
        "description": "....."
      }
    },
  • id – internal id used to link the product to the ids listed in the categories tree.
  • product_id – “liquid id” of the product. This id cannot be used for checkout as it does not specify the quantity / volume / container type. Please first do a call to products/{id} endpoint. This will return all permutations of the alcohol item.
  • name – product name.
  • type – primary alcohol type: beer, wine, or liquor.
  • size – default volume or pack information
  • price – price of the item for the default volume
  • size_price – all price/size options
  • categories – all categories that the item currently matches in the request. This will not show all categories the item is categorized under.
  • tags – alcohol tags
  • image – url of item image
  • description – item description

Breadcrumbs

Lists the path to the current filtering location. Useful for navigational purposes.

Sort

"sort": {
      "key": "sort",
      "options" : [
        {
          "title" : "Name A to Z",
          "value" : "name",
          "is_selected" : true
        },
        {
          "title" : "Name Z to A",
          "value" : "-name",
          "is_selected" : false
        },
        {
          "title" : "Lowest Price",
          "value" : "price",
          "is_selected" : false
        },
        {
          "title" : "Highest Price",
          "value" : "-price",
          "is_selected" : false
        },
      ]
    },

Lists all the sort options. Use the key and value to set the sort.

?sort=-name  // sorts Z to A
?sort=price  // sorts low to high price

Merchants

Lists the merchant information including the name, address, distance from inputted address, and order availability.

Alcohol: GET Merchants provides more information about the merchant object.