API Basics Authentication Errors Brewer > Brewer Object > Add a Brewer > Retrieve a Brewer > List all Brewers > Number of Brewers > List all Beers made by a Brewer > List all the Locations for a Brewer Beer > Beer Object > Add a Beer > Retrieve a Beer > List all Beer > Number of Beers Location > The Location Object > Add a Location > Add an Address to a Location > Retrieve a Location > Find Nearby Locations US Addresses > The US Address Object

API Reference

Last Updated: October 10, 2018

API Basics

The Catalog.beer API is organized around REST. We use HTTP response codes to indicate the success or failure of your request. We use also use basic HTTP features like HTTP authentication and HTTP verbs.

The Catalog.beer API can be accessed using the following root URL:

https://api.catalog.beer

When making an API request, be sure to include an accept: application/json header. All data returned by the API will be in JSON format.

Similarly, when making a PUT or POST request to the API, the body of your request must be in JSON as well. Be sure to include the content-type: application/json header in your request.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can find your API key on your Account page. Your API key carries many privileges, so be sure to keep it secret! Do not share your secret API key in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via the 'Basic' HTTP authentication scheme. Provide your API key as the username value. You do not need to provide a password.

When making a request using basic HTTP authentication, your request should contain a header field in the form of Authorization: Basic <credentials>, where <credentials> is the base64_encode('username:password') (Recall that your username in this case is your API Key and the password field should be left blank).

For example, if your API Key is: cadcbe6f-a80d-4e33-9f20-b53c2ed83845

base64_encode('cadcbe6f-a80d–4e33–9f20-b53c2ed83845:')

Returning: Y2FkY2JlNmYtYTgwZC00ZTMzLTlmMjAtYjUzYzJlZDgzODQ1Og==

Then your cURL request will look something like:

curl --location --request GET 'https://api.catalog.beer/brewer'
--header 'Accept: application/json'
--header 'Authorization: Basic Y2FkY2JlNmYtYTgwZC00ZTMzLTlmMjAtYjUzYzJlZDgzODQ1Og=='

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Catalog.beer uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Catalog.beer’s servers.

The following parameters are returned in JSON format when an error occurs

Parameter Type Description
error Boolean true or false. Indicates an error occurred in processing your request.
error_msg
(optional)		 string A message relaying additional information about the error.
valid_state
(optional)		 array An array containing the attribute names and their validation state. A field’s state is binary: either ‘valid’ or ‘invalid’. You can use this parameter to help target which attributes are invalid.
valid_msg
(optional)		 array An array containing the attribute names and the corresponding error message for that attribute. You can use this information to show help text next to the attributes that were invalid.

Sample error JSON returned for a POST request to /brewer:

{
  "error": true,
  "error_msg": "",
  "valid_state": {
    "name": "invalid",
    "url": "valid",
    "description": "valid",
    "short_description": "valid",
    "facebook_url": "valid",
    "twitter_url": "",
    "instagram_url": "valid"
  },
  "valid_msg": {
    "name": "Please give us the name of the brewery you'd like to add.",
    "url": "",
    "description": "",
    "short_description": "",
    "facebook_url": "",
    "twitter_url": "",
    "instagram_url": ""
  }
}

^ Return to top

Brewer

The brewer object is the central piece of the beer data puzzle. Brewers can have beers and locations associated with them. And in order to add a beer or location to the database, there must be a brewer to associated them with.

The Brewer Object

Whether you’re retrieving information on a specific brewer, adding a new brewer, or updating an existing brewer, successful requests will return the brewer object in JSON format. That object has the following parameters.

Parameter Type Description
id string The brewer_id; a unique identifier for the brewer.
object string The name of the object. In this case: “brewer”.
name string The name of the brewer.
description string A description of the brewer. Note that this field may contain markdown or new line characters.
short_description string A short, max 160 character, description of the brewer.
url string The URL of the brewer’s website.
cb_verified Boolean A true or false value denoting whether or not a Catalog.beer administrator has verified the brewer’s information.
brewer_verified Boolean A true or false value denoting whether or not the brewer themselves has contributed and verified their information.
facebook_url string The URL of the brewer’s Facebook page.
twitter_url string The URL of the brewer’s Twitter profile.
instagram_url string The URL of the brewer’s Instagram profile.

Sample

{
  "id": "65911cdd-52e6-6305-3420-b9bbf6ea958d",
  "object": "brewer",
  "name": "HopSaint",
  "description": "HopSaint was born after one too many late nights navigating a crowded bar just to have a great beer unceremoniously poured into a dirty pint glass. We believe fresh draft beer shouldn’t be confined to the pub. You should choose when, where, how, and with whom you enjoy a fresh, crafted beer. That’s at the heart of HopSaint - a community that fosters lasting relationships & enriches our hometown through the production of honest, real beer. A community built on craft beer.",
  "short_description": "A brewery in Torrance, CA.",
  "url": "https://www.hopsaint.com/",
  "cb_verified": true,
  "brewer_verified": false,
  "facebook_url": "https://www.facebook.com/hopsaintbrewingco",
  "twitter_url": "",
  "instagram_url": "https://www.instagram.com/hopsaintbrewco/"
}

^ Return to top

Add a Brewer

To add a brewer, send a POST request to the /brewer endpoint with the following parameters encoded in the body of the request as JSON. Successful requests will return a brewer object.

POST https://api.catalog.beer/brewer
Parameter Type Description
name string The name of the brewer.
description
(optional)		 string A description of the brewer. This should be like the “About” page posted by the brewer. A brief origin story coupled with who they are. This field supports markdown.
short_description
(optional)		 string A short description of the brewer; max 160 characters. TDescribe the brewer as you might in a tweet. Short and sweet.
url
(optional)		 string The URL of the brewer’s website.
facebook_url
(optional)		 string The URL of the brewer’s Facebook page.
twitter_url
(optional)		 string The URL of the brewer’s Twitter profile.
instagram_url
(optional)		 string The URL of the brewer’s Instagram profile.

Sample Request

curl -X POST \
  https://api.catalog.beer/brewer \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"name":"","description":"HopSaint was born after one too many late nights navigating a crowded bar just to have a great beer unceremoniously poured into a dirty pint glass. We believe fresh draft beer shouldn\u2019t be confined to the pub. You should choose when, where, how, and with whom you enjoy a fresh, crafted beer. That\u2019s at the heart of HopSaint - a community that fosters lasting relationships & enriches our hometown through the production of honest, real beer. A community built on craft beer.","short_description":"A brewery in Torrance, CA.","url":"https:\/\/www.hopsaint.com\/","facebook_url":"http:\/\/www.facebook.com\/hopsaintbrewingco","twitter_url":"","instagram_url":"http:\/\/instagram.com\/hopsaintbrewco"}'

^ Return to top

Retrieve a Brewer

To retrieve a brewer, send a GET request to the /brewer endpoint with the {brewer_id} parameter appended to the path.

GET https://api.catalog.beer/brewer/{brewer_id}

A brewer object will be returned for successful requests.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer/65911cdd-52e6-6305-3420-b9bbf6ea958d \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

List all Brewers

If you want a list of all the brewers in the database, send a GET request to the /brewer endpoint.

GET https://api.catalog.beer/brewer

Query Parameters

Name Type Description
cursor
(optional)		 string A opaque string value that indicates where the results should start from. This value is returned as next_cursor after an initial query to the endpoint.
count
(optional)		 integer The number of results you would like returned from your request. The default value is 500.

A sample request with query parameters. Be sure to encode all non-alphanumeric characters except -_.

GET https://api.catalog.beer/brewer?count=5&cursor=NQ%3D%3D

Reponse

This request returns a list object with the following parameters.

Parameter Type Description
object string The name of the object. In this case: “list”.
url string The API endpoint accessed to retrieve this object. In this case: /brewer.
has_more Boolean Whether or not there is more data available after this set. If false, you have reached the last items on the list.
next_cursor
(optional)		 string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request.
data array An array containing all the brewers in the database sorted alphabetically by name. Each array object has the following attributes: id and name, described below.
id string The brewer_id.
name string The name of the brewer.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer",
  "has_more": false,
  "data": [
    {
      "id": "e7fa4e64-a39e-fd06-f82a-37de2a7dfbda",
      "name": "Ballast Point"
    },
    {
      "id": "65911cdd-52e6-6305-3420-b9bbf6ea958d",
      "name": "HopSaint"
    }
  ]
}

^ Return to top

Number of Brewers

You can retrieve the total number of brewers that are in the database by sending a GET request the endpoint /brewer/count. A JSON object with the following parameters will be returned.

GET https://api.catalog.beer/brewer/count
Parameter Type Description
object string The name of the object. In this case: “count”.
url string The API endpoint accessed to retrieve this object. In this case: /brewer/count.
value integer The number of brewers in the database.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer/count \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "count",
  "url": "/brewer/count",
  "value": 3
}

^ Return to top

List all Beers made by a Brewer

If you would like a list of all the beers made by a brewer, send a request to the /brewer/{brewer_id}/beer endpoint.

This request returns a list object with the following parameters.

Parameter Type Description
object string The name of the object. In this case: “list”.
url string The API endpoint accessed to retrieve this object. In this case: /brewer/{brewer_id}/beer.
has_more Boolean As of this writing, this will always return false. In the future, if pagination of results is required, this value may become true.
brewer object A brewer object containing information for the requested {brewer_id}.
data array An array containing all the beers associated with this brewer in the database sorted alphabetically by name. Each array object has the following attributes: id, name, and style described below.
id string The beer_id.
name string The name of the beer.
style string The style of the beer.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer/e7fa4e64-a39e-fd06-f82a-37de2a7dfbda/beer \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer/e7fa4e64-a39e-fd06-f82a-37de2a7dfbda/beer",
  "has_more": false,
  "brewer": {
    "id": "e7fa4e64-a39e-fd06-f82a-37de2a7dfbda",
    "object": "brewer",
    "name": "Ballast Point",
    "description": "## It Begins with the Search for Flavor\r\n\r\nThe perfect balance of taste and aroma. An obsession with ingredients. An exploration of techniques. And while we savor the result, we’re just as fascinated by the process to get there. What started as a small group of home brewers, who simply wanted to make a better beer, evolved into the adventurers known today as Ballast Point.\r\n\r\n## Where Science Meets Art\r\n\r\nWe live to add our own touch and ask if there’s a better way. As we tinkered, tested and tasted, we discovered that making beer was more art than science. And while we respect and honor tradition, we relish the opportunity to take it further. That freedom has allowed us to reinterpret brewing. And along the way help to reinvigorate the industry. From bringing a hoppy twist to a porter, or developing a proprietary yeast for our amber ale, to creating a breakthrough gold medal-winning IPA.\r\n\r\n## To Share Our Journey\r\nBut all of this would be wasted if we couldn’t share it. Whether serving up new flavors, collaborating with seasoned brewmasters, or training the next generation at Home Brew Mart, we not only want to challenge our own tastes, but expand yours.\r\nBallast Point. Dedicated to the craft.",
    "short_description": "Award wining brewery built in San Diego, California. Dedicated to the craft.",
    "url": "https://www.ballastpoint.com/",
    "cb_verified": true,
    "brewer_verified": false,
    "facebook_url": "https://www.facebook.com/BallastPoint",
    "twitter_url": "https://twitter.com/BallastPoint",
    "instagram_url": "https://www.instagram.com/ballastpointbrewing/"
  },
  "data": [
    {
      "id": "01fd323a-5984-a1c5-51a1-9b8abde3afb4",
      "name": "12 Year Old Elijah Craig Ballast Point Victory at Sea",
      "style": "Imperial Porter"
    },
    {
      "id": "e9a9936e-332c-aa6c-8dcf-70309b483db7",
      "name": "Abandon Ship",
      "style": "Smoked Lager"
    },
    {
      "id": "b4d1c9f3-cb4a-c364-f1f0-a71a94295ead",
      "name": "Abandon Ship with Chipotle",
      "style": "Smoked Lager"
    }
  ]
}

^ Return to top

List all the Locations for a Brewer

If you would like to know all the locations associated with a brewer, send a request to the /brewer/{brewer_id}/locations endpoint.

This request returns a list object with the following parameters.

Parameter Type Description
object string The name of the object. In this case: “list”.
url string The API endpoint accessed to retrieve this object. In this case: /brewer/{brewer_id}/locations.
has_more Boolean As of this writing, this will always return false. In the future, if pagination of results is required, this value may become true.
data array An array containing all the locations associated with this brewer in the database sorted alphabetically by name. Each array object has the following attributes: id and name described below.
id string The location_id.
name string The name of the location.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer/e7fa4e64-a39e-fd06-f82a-37de2a7dfbda/locations \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer/e7fa4e64-a39e-fd06-f82a-37de2a7dfbda/locations",
  "has_more": false,
  "data": [
    {
      "id": "d94cdece-0b9f-cab6-9d6e-5fb3ba41d37c",
      "name": "Daleville, Virginia"
    },
    {
      "id": "618df467-d2a3-5fdd-9d9e-f2b338d3485e",
      "name": "Home Brew Mart"
    }
  ]
}

^ Return to top

Beer

Beer is at the heart of it all. From an API perspective, beers are associated with brewers via a brewer_id.

The Beer Object

When you add a new beer, are looking for information on a specific beer, or are updating a beer in the database, successful requests will return the beer object in JSON format. That object has the following parameters.

Parameter Type Description
id string The beer_id; a unique identifier for the beer.
object string The name of the object; in this case: “beer”.
name string The name of the beer.
style string The style of the beer.
description string A description of the beer. This field may contain a basic description, may contain tasting notes and/or brewer’s notes. This field may contain markdown or new line characters.
abv float The Alcohol by Volume (ABV) percentage of the beer.
ibu integer The International Bitterness/Bittering Units (IBU) value of the beer.
cb_verified Boolean A true or false value denoting whether or not a Catalog.beer administrator has verified the brewer’s information.
brewer_verified Boolean A true or false value denoting whether or not the brewer themselves has contributed and verified their information.
brewer object A brewer object containing information on the brewer.

Sample

{
    "id": "bc2170df-eef7-8f6b-205b-63cbfeb4a901",
    "object": "beer",
    "name": "Schooner Wet Hop",
    "style": "Ale with Wet Hops",
    "description": "Wet Hops (fresh hops) are hops that are picked off the vine and used in the brewing process before they are dried and packaged like normal. To brew this beer we get Cascade Hops from Yakima, Washington. They are picked, shipped and put into the brew within 36 hours. The Wet Hops have a grassy, vegetal, chlorophyll flavor that is reminiscent of fresh cut Greens. We showcase this 100% Cascade Hop Beer with a very light and crisp grain bill including a small portion of rice. This allows the aroma and flavor from such a rare, very seasonal ingredient, to shine.",
    "abv": 5.5,
    "ibu": 25,
    "cb_verified": true,
    "brewer_verified": false,
    "brewer": {
        "id": "e7fa4e64-a39e-fd06-f82a-37de2a7dfbda",
        "object": "brewer",
        "name": "Ballast Point",
        "description": "## It Begins with the Search for Flavor\r\n\r\nThe perfect balance of taste and aroma. An obsession with ingredients. An exploration of techniques. And while we savor the result, we’re just as fascinated by the process to get there. What started as a small group of home brewers, who simply wanted to make a better beer, evolved into the adventurers known today as Ballast Point.\r\n\r\n## Where Science Meets Art\r\n\r\nWe live to add our own touch and ask if there’s a better way. As we tinkered, tested and tasted, we discovered that making beer was more art than science. And while we respect and honor tradition, we relish the opportunity to take it further. That freedom has allowed us to reinterpret brewing. And along the way help to reinvigorate the industry. From bringing a hoppy twist to a porter, or developing a proprietary yeast for our amber ale, to creating a breakthrough gold medal-winning IPA.\r\n\r\n## To Share Our Journey\r\nBut all of this would be wasted if we couldn’t share it. Whether serving up new flavors, collaborating with seasoned brewmasters, or training the next generation at Home Brew Mart, we not only want to challenge our own tastes, but expand yours.\r\nBallast Point. Dedicated to the craft.",
        "short_description": "Award wining brewery built in San Diego, California. Dedicated to the craft.",
        "url": "https://www.ballastpoint.com/",
        "cb_verified": true,
        "brewer_verified": false,
        "facebook_url": "https://www.facebook.com/BallastPoint",
        "twitter_url": "https://twitter.com/BallastPoint",
        "instagram_url": "https://www.instagram.com/ballastpointbrewing/"
    }
}

^ Return to top

Add a Beer

To add a beer to the database, send a POST request to the /beer endpoint with the following parameters encoded in the body of the request as JSON. Successful requests will return a beer object.

POST https://api.catalog.beer/beer
Parameter Type Description
brewer_id string The brewer_id for the brewer who makes the beer.
name string The name of the beer.
style string The style of the beer.
description
(optional)		 string A description of the beer. This may be a basic description, or it can be detailed contain tasting notes and brewer’s notes. This field may contain markdown and new line characters.
abv float The Alcohol by Volume (ABV) percentage of the beer.
ibu
(optional)		 integer The International Bitterness/Bittering Units (IBU) value of the beer.

Sample Request

curl -X POST
 https://api.catalog.beer/brewer
 -H ‘accept: application/json’
 -H ‘authorization: Basic {secret_key}’
 -H ‘content-type: application/json’
 -d ‘{“brewer_id”:“e7fa4e64-a39e-fd06-f82a–37de2a7dfbda”,“name”:“Schooner Wet Hop”,“style”:“Ale with Wet Hops”,“description”:“Wet Hops (fresh hops) are hops that are picked off the vine and used in the brewing process before they are dried and packaged like normal. To brew this beer we get Cascade Hops from Yakima, Washington. They are picked, shipped and put into the brew within 36 hours. The Wet Hops have a grassy, vegetal, chlorophyll flavor that is reminiscent of fresh cut Greens. We showcase this 100% Cascade Hop Beer with a very light and crisp grain bill including a small portion of rice. This allows the aroma and flavor from such a rare, very seasonal ingredient, to shine.”,“abv”:“5.5”,“ibu”:“25”}’

^ Return to top

Retrieve a Beer

To retrieve a beer, send a GET request to the /beer endpoint with the {beer_id} parameter appended to the path.

GET https://api.catalog.beer/beer/{beer_id}

A beer object will be returned for successful requests.

Sample Request

curl -X GET \
  https://api.catalog.beer/beer/bc2170df-eef7-8f6b-205b-63cbfeb4a901 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

List all Beer

Retrieves a list of all the beer in the database. To access this data, send a GET request to the /beer endpoint.

GET https://api.catalog.beer/beer

Query Parameters

Name Type Description
cursor
(optional)		 string A opaque string value that indicates where the results should start from. This value is returned as next_cursor after an initial query to the endpoint.
count
(optional)		 integer The number of results you would like returned from your request. The default value is 500.

A sample request with query parameters. Be sure to encode all non-alphanumeric characters except -_.

GET https://api.catalog.beer/beer?count=5&cursor=NQ%3D%3D

Response

This request returns a list object with the following parameters.

Parameter Type Description
object string The name of the object. In this case: “list”.
url string The API endpoint accessed to retrieve this object. In this case: /beer.
has_more Boolean Whether or not there is more data available after this set. If false, you have reached the last items on the list.
next_cursor string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request.
data array An array containing all the beers in the database sorted alphabetically by name. Each array object has the following attributes: id and name, described below.
id string The beer_id.
name string The name of the beer.

Sample Request

curl -X GET \
  https://api.catalog.beer/beer \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/beer",
  "has_more": false,
  "data": [
    {
      "id": "01fd323a-5984-a1c5-51a1-9b8abde3afb4",
      "name": "12 Year Old Elijah Craig Ballast Point Victory at Sea"
     },
     {
      "id": "e9a9936e-332c-aa6c-8dcf-70309b483db7",
      "name": "Abandon Ship"
    },
    {
      "id": "b4d1c9f3-cb4a-c364-f1f0-a71a94295ead",
      "name": "Abandon Ship with Chipotle"
    }
  ]
}

^ Return to top

Number of Beers

To retrieve the total number of beers that are in the database, send a GET request to the /beer/count endpoint. A JSON object with the following parameters will be returned.

GET https://api.catalog.beer/beer/count

Sample Request

curl -X GET \
  https://api.catalog.beer/beer/count \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "count",
  "url": "/beer/count",
  "value": 87
}

^ Return to top

Location

Brewers can have multiple locations associated with them. These should be public locations at which beer is served as opposed to a production or office space that does not offer beer tasting.

The Location Object

When you add an address to a location, are looking for information on a specific location, or are updating a location in the database, successful requests will return the location object in JSON format. That object has the following parameters.

Parameter Type Description
id string The location_id; a unique identifier for the location.
object string The name of the object; in this case: “location”.
name string The name of the location.
brewer_id string The unique identifier for the brewer the location is associated with.
url string A URL that is specific to the location.
country_code string The ISO 3166–1 Alpha–2 Code for the country in which the location is located. Reference the ISO 3166 standard.
country_short_name string The ISO 3166–1 short name for the country, in title case. Reference the ISO 3166 standard.
latitude
(optional)		 float The latitude of the location.
longitude
(optional)		 float The longitude of the location.
telephone
(optional)		 integer An unformatted integer string representing the telephone number of the location. Does not include the country code. For example, a US telephone number written in the international format as +1 (555) 444–3333 is stored as 5554443333 in our database. Country codes, if required, can be mapped from the country_code field.
address
(optional)		 object At this time, the database supports addresses for locations in the United States. See the US Addresses object.

Sample

Sample location object with a US address.

{
    "id": "4920c879-76a6-4bb7-dccf-5f2642e28c08",
    "object": "location",
    "name": "San Diego",
    "brewer_id": "634996c1-5ffb-9099-b015-11cbfe8bb53f",
    "url": "",
    "country_code": "US",
    "country_short_name": "United States of America",
    "latitude": 32.8882179,
    "longitude": -117.1498184,
    "telephone": 8585499888,
    "address": {
        "address1": "",
        "address2": "9990 Alesmith Ct",
        "city": "San Diego",
        "sub_code": "US-CA",
        "state_short": "CA",
        "state_long": "California",
        "zip5": 92126,
        "zip4": 4200
    }
}

^ Return to top

Add a Location

To add a location for a brewer, send a POST request to the /location endpoint with the following parameters encoded in the body of the request as JSON. Successful requests will return a location object.

POST https://api.catalog.beer/location
Parameter Type Description
brewer_id string The brewer_id for the brewer you would like to associate the location with.
name string The name of the location. This can be generic and mirror the name of the city in which it is located or can be specific.
url
(optional)		 string A URL specific to the location. This URL should provide visitors additional information on the beer tasting location (e.g. address, hours, or more information). It should not be the same as the brewer’s URL.
country_code string The ISO 3166–1 Alpha–2 Code for the country in which the location is located. Reference the ISO 3166 standard.

Sample Request

curl -X POST \
  https://api.catalog.beer/location \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{"brewer_id":"050a11d3-0364-1eef-442f-82909ecadb1b","name":"Wrigley","url":"","country_code":"US"}'

Sample Response

 {
 “id”: “e00c24d6-de81–2ea4-dfd8-cd6f2cb5f1e7”,
 “object”: “location”,
 “name”: “Wrigley”,
 “brewer_id”: “050a11d3–0364–1eef–442f–82909ecadb1b”,
 “url”: “”,
 “country_code”: “US”,
 “country_short_name”: “United States of America”
}

^ Return to top

Add an Address to a Location

Addresses and telephone numbers are stored separately from locations to allow for country specific addressing schemes and telephone numbers. Hence the need to make a second request to add an address to a location.

To add an address or telephone number for a location, send a POST request to the /location endpoint with the location_id appended to the path and following parameters encoded in the body of the request as JSON. Successful requests will return a location object.

Currently, only US addresses are supported. This documentation will be updated once support for other countries has been added.

POST https://api.catalog.beer/location/{location_id}
Parameter Type Description
address1
(optional)		 string The suite or unit number of the location (if applicable - e.g. Suite 101).
address2 string The street address of the location.
city
(optional) Either the city and sub_code must be provided OR the zip5 must be provided.		 string The name of the city.
sub_code
(optional) Either the city and sub_code must be provided OR the zip5 must be provided.		 string The ISO 3166–2 Code for the subdivision in which the location is located. Reference the ISO 3166 standard. (e.g. “US-CA” for California)
zip5
(optional) Either the city and sub_code must be provided OR the zip5 must be provided.		 string The traditional 5-digit ZIP Code for the location.
zip4
(optional)		 string The additional ZIP+4 Code used by the US Postal Service. More on the ZIP+4 Code.
telephone
(optional)		 string The 10-digit telephone number for the location. You may submit the number with formatting (e.g. (555) 444–3333) or as an integer. Formatting will be stripped when the data is processed and an integer will be returned.

Sample Request

curl -X POST \
  https://api.catalog.beer/location/e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7 \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{"address1":"","address2":"518 W Willow St","city":"Long Beach","sub_code":"US-CA","zip5":"","zip4":"","telephone":""}'

Sample Response

{
  "id": "e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7",
  "object": "location",
  "name": "Wrigley",
  "brewer_id": "050a11d3-0364-1eef-442f-82909ecadb1b",
  "url": "",
  "country_code": "US",
  "country_short_name": "United States of America",
  "telephone": 0,
  "address": {
    "address1": "",
    "address2": "518 W Willow St",
    "city": "Long Beach",
    "sub_code": "US-CA",
    "state_short": "CA",
    "state_long": "California",
    "zip5": 90806,
    "zip4": 0
  }
}

^ Return to top

Retrieve a Location

To retrieve a location, send a GET request to the /location endpoint with the {location_id} parameter appended to the path.

GET https://api.catalog.beer/location/{location_id}

A location object will be returned for successful requests.

Sample Request

curl -X GET \
  https://api.catalog.beer/location/e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

Find Nearby Locations

One of the questions that gets asked most is “where is the nearest brewery?” or “I’m heading to Acme town, what breweries are local?”. To answer those questions or questions like them, use this endpoint.

To retrieve a location, send a GET request to the /location/nearby endpoint with the {latitude} and {longitude} query parameters appended to the path.

Query Parameters

Name Type Description
latitude float The latitude of the location where you would like to search around. Combined with longitude, this pair describes the center of your search radius.
longitude float The longitude of the location where you would like to search around. Combined with latitude, this pair describes the center of your search radius.
search_radius
(optional)		 integer The radius of the search circle, centered at the provided latitude and longitude. If left empty, the default value of 25 will be used. The default units are miles. Use the metric flag to search in kilometers.
metric
(optional)		 boolean Set this value to true if you would like your search radius and results to be measured in kilometers. The default value for this variable is false, yielding a searh radius and results measured in miles, though you can state it explicitly.
cursor
(optional)		 string A opaque string value that indicates where the results should start from. This value is returned as next_cursor after an initial query to the endpoint.
count
(optional)		 integer The number of results you would like returned from your request. The default value is 100.

A sample request with query parameters.

GET https://api.catalog.beer/location/nearby?latitude={latitude}&longitude={longitude}

Response

This request returns a list object with the following parameters.

Parameter Type Description
object string The name of the object. In this case: “list”.
url string The API endpoint accessed to retrieve this object. In this case: /location/nearby.
has_more Boolean Whether or not there is more data available after this set. If false, you have reached the last items on the list.
next_cursor string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request.
data array

An array containing all the locations that match your query parameters. The array contains the following for each result:
distance float The straight line distance from the query latitude and longitude to the brewery, rounded to the tenths place (a single decimal place).
units string The unit of distance. The value of this field will be either “miles” (the default value) or “kilometers” if the metric query parameter is set to true.

Sample Request

curl -X GET \
  'https://api-staging.catalog.beer/location/nearby?latitude=32.748482&longitude=-117.130094&search_radius=10&count=1 \
  -H 'Accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
    "object": "list",
    "url": "/location/nearby",
    "has_more": true,
    "next_cursor": "MQ==",
    "data": [
        {
            "location": {
                "id": "d23d1ef7-4659-23e9-9ddb-405ece1223e9",
                "object": "location",
                "name": "North Park",
                "brewer_id": "008fdcf3-b59d-9d7e-6b14-540a88bb36fa",
                "url": "",
                "country_code": "US",
                "country_short_name": "United States of America",
                "latitude": "32.7476883",
                "longitude": "-117.1285400",
                "telephone": 6192557136,
                "address": {
                    "address1": "",
                    "address2": "3812 Grim Ave",
                    "city": "San Diego",
                    "sub_code": "US-CA",
                    "state_short": "CA",
                    "state_long": "California",
                    "zip5": 92104,
                    "zip4": 3602
                }
            },
            "distance": {
                "distance": 0.1,
                "units": "miles"
            },
            "brewer": {
                "id": "008fdcf3-b59d-9d7e-6b14-540a88bb36fa",
                "object": "brewer",
                "name": "Mike Hess Brewing Co.",
                "description": "",
                "short_description": "",
                "url": "https://www.mikehessbrewing.com/",
                "cb_verified": true,
                "brewer_verified": false,
                "facebook_url": "https://www.facebook.com/MikeHessBrewingCoNorthPark/",
                "twitter_url": "https://twitter.com/mikehessbrewing",
                "instagram_url": "https://www.instagram.com/mikehessbrewing/?hl=en"
            }
        }
    ]
}

^ Return to top

US Address

For locations in the United States, data is stored and captured using the US Addresses data structure.

The US Address Object

Addresses for the United States are stored in an object with the following parameters.

Parameter Type Description
address1
(optional)		 string The apartment, suite, or unit number of the location (if applicable).
address2 string The street address of the location.
city string The name of the city
sub_code string The ISO 3166–2 Code for the subdivision in which the location is located. Reference the ISO 3166 standard. (e.g. US-CA)
state_short string The two character all-caps notation for the state (e.g. CA).
state_long string The full name of the state or district (e.g. California)
zip5 integer The traditional 5-digit ZIP Code for the location.
zip4
(optional)		 integer The additional ZIP+4 Code used by the US Postal Service. More on the ZIP+4 Code.

^ Return to top

Resources

API Documentation
Contact
GitHub

Legal

Privacy Policy
Terms of Use

Except where otherwise noted, the content on this website is licensed under a Creative Commons Attribution 4.0 International license (CC BY 4.0). This also excludes a Brewery’s rights in its name, brand(s), and trademarks.