API Basics Authentication Errors HTTP Methods Brewer > Brewer Object > Add a Brewer > Update a Brewer (PUT) > Update a Brewer (PATCH) > Delete a Brewer > Retrieve a Brewer > List all Brewers > Number of Brewers > Search Brewers > List all Beers made by a Brewer > List all the Locations for a Brewer Beer > Beer Object > Add a Beer > Update a Beer (PUT) > Update a Beer (PATCH) > Delete a Beer > Retrieve a Beer > List all Beer > Number of Beers > Search Beer Location > The Location Object > Add a Location > Update a Location (PUT) > Update a Location (PATCH) > Delete a Location > Add an Address to a Location > Replace an Address (PUT) > Retrieve a Location > Find Nearby Locations > Find Locations by ZIP Code > Find Locations by City Users > The User Object > Retrieve a User > Get API Key > Update a User (PATCH) > Delete a User > Request Password Reset > Reset Password US Addresses > The US Address Object

API Reference

Last Updated: February 19, 2026

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"
  },
  "valid_msg": {
    "name": "Please give us the name of the brewery you'd like to add.",
    "url": "",
    "description": "",
    "short_description": ""
  }
}

^ Return to top

HTTP Methods

The Catalog.beer API supports the following HTTP methods for creating, reading, updating, and deleting resources.

Method Description
GET Retrieve a resource or list of resources.
POST Create a new resource.
PUT Full replacement of a resource. All required fields must be present. Omitted optional fields are cleared to null. If the resource does not exist, it will be created (returns 201 Created). If the resource already exists, it will be replaced (returns 200 OK).
PATCH Partial update of a resource. Only the fields you provide will be modified; all other fields remain unchanged. The resource must already exist (returns 404 Not Found otherwise).
DELETE Remove a resource. Returns 204 No Content with no response body on success.

If you send a request using an HTTP method that is not supported by the endpoint, the API will return a 405 Method Not Allowed response. The Allow header on the response will list the methods that the endpoint does support.

^ 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.
last_modified integer A Unix timestamp indicating when the brewer was last modified.

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,
  "last_modified": 1736966600
}

^ 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. Describe the brewer as you might in a tweet. Short and sweet.
url
(optional)		 string The URL of the brewer’s website.

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":"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\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\/"}'

^ Return to top

Update a Brewer (PUT)

To replace a brewer’s data, send a PUT request to the /brewer endpoint with the brewer_id appended to the path. All required fields must be present. Omitted optional fields will be cleared to null. If the brewer does not exist, it will be created and a 201 Created response will be returned. Successful requests return a brewer object.

PUT https://api.catalog.beer/brewer/{brewer_id}
Parameter Type Description
name string The name of the brewer.
description
(optional)		 string A description of the brewer. Cleared if omitted.
short_description
(optional)		 string A short description of the brewer; max 160 characters. Cleared if omitted.
url
(optional)		 string The URL of the brewer’s website. Cleared if omitted.

Sample Request

curl -X PUT \
  https://api.catalog.beer/brewer/65911cdd-52e6-6305-3420-b9bbf6ea958d \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"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.","short_description":"A brewery in Torrance, CA.","url":"https:\/\/www.hopsaint.com\/"}'

^ Return to top

Update a Brewer (PATCH)

To partially update a brewer, send a PATCH request to the /brewer endpoint with the brewer_id appended to the path. Only the fields you include will be updated; all other fields remain unchanged. Successful requests return a brewer object.

PATCH https://api.catalog.beer/brewer/{brewer_id}
Parameter Type Description
name
(optional)		 string The name of the brewer.
description
(optional)		 string A description of the brewer.
short_description
(optional)		 string A short description of the brewer; max 160 characters.
url
(optional)		 string The URL of the brewer’s website.

Sample Request

curl -X PATCH \
  https://api.catalog.beer/brewer/65911cdd-52e6-6305-3420-b9bbf6ea958d \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"short_description":"A craft brewery in Torrance, CA."}'

^ Return to top

Delete a Brewer

To delete a brewer, send a DELETE request to the /brewer endpoint with the brewer_id appended to the path. No request body is required. Successful requests return a 204 No Content response with no body.

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

Sample Request

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

^ 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

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: /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, name, and last_modified, described below.
id string The brewer_id.
name string The name of the brewer.
last_modified integer A Unix timestamp representing the date and time the brewer was last modified.

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",
      "last_modified": 1708905600
    },
    {
      "id": "65911cdd-52e6-6305-3420-b9bbf6ea958d",
      "name": "HopSaint",
      "last_modified": 1706313600
    }
  ]
}

^ 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

Search for brewers by name or description using full-text search. To search, send a GET request to the /brewer/search endpoint with a q query parameter.

GET https://api.catalog.beer/brewer/search?q={query}

Query Parameters

Name Type Description
q string The search query string. Maximum 255 characters.
count
(optional)		 integer The number of results you would like returned. The default value is 25. Maximum is 100.
cursor
(optional)		 string An 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.

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

GET https://api.catalog.beer/brewer/search?q=stone+brewing&count=5

Response

This request returns a list object with the following parameters. Results are sorted by relevance to the search query.

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/search.
query string The search query that was submitted.
has_more Boolean Whether or not there are more results available. If false, you have reached the last items in the result set.
next_cursor
(optional)		 string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request. Only present when has_more is true.
data array An array of brewer objects matching the search query, sorted by relevance.

Sample Request

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

Sample Response

{
  "object": "list",
  "url": "/brewer/search",
  "query": "stone",
  "has_more": false,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "object": "brewer",
      "name": "Stone Brewing",
      "description": "Stone Brewing, founded in 1996 in San Diego...",
      "short_description": "San Diego craft brewery",
      "url": "https://www.stonebrewing.com/",
      "cb_verified": true,
      "brewer_verified": false,
      "last_modified": 1737234000
    }
  ]
}

^ 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,
    "last_modified": 1736356500
  },
  "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.
brewer object A brewer object for the requested brewer.
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,
  "brewer": {
    "id": "e7fa4e64-a39e-fd06-f82a-37de2a7dfbda",
    "object": "brewer",
    "name": "Ballast Point",
    "description": null,
    "short_description": null,
    "url": "https://www.ballastpoint.com/",
    "cb_verified": true,
    "brewer_verified": false,
    "last_modified": 1737234000
  },
  "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.
last_modified integer A Unix timestamp indicating when the beer was last modified.
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,
    "last_modified": 1736547720,
    "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,
        "last_modified": 1736356500
    }
}

^ 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/beer \
  -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.","abv":"5.5","ibu":"25"}'

^ Return to top

Update a Beer (PUT)

To replace a beer’s data, send a PUT request to the /beer endpoint with the beer_id appended to the path. All required fields must be present. Omitted optional fields will be cleared to null. If the beer does not exist, it will be created and a 201 Created response will be returned. Successful requests return a beer object.

PUT https://api.catalog.beer/beer/{beer_id}
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.
abv float The Alcohol by Volume (ABV) percentage of the beer.
description
(optional)		 string A description of the beer. Cleared if omitted.
ibu
(optional)		 integer The International Bitterness/Bittering Units (IBU) value of the beer. Cleared if omitted.

Sample Request

curl -X PUT \
  https://api.catalog.beer/beer/bc2170df-eef7-8f6b-205b-63cbfeb4a901 \
  -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","abv":5.5,"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.","ibu":25}'

^ Return to top

Update a Beer (PATCH)

To partially update a beer, send a PATCH request to the /beer endpoint with the beer_id appended to the path. Only the fields you include will be updated; all other fields remain unchanged. Successful requests return a beer object.

PATCH https://api.catalog.beer/beer/{beer_id}
Parameter Type Description
brewer_id
(optional)		 string The brewer_id for the brewer who makes the beer.
name
(optional)		 string The name of the beer.
style
(optional)		 string The style of the beer.
description
(optional)		 string A description of the beer.
abv
(optional)		 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 PATCH \
  https://api.catalog.beer/beer/bc2170df-eef7-8f6b-205b-63cbfeb4a901 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"abv":5.8,"ibu":30}'

^ Return to top

Delete a Beer

To delete a beer, send a DELETE request to the /beer endpoint with the beer_id appended to the path. No request body is required. Successful requests return a 204 No Content response with no body.

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

Sample Request

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

^ 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, name, and last_modified, described below.
id string The beer_id.
name string The name of the beer.
last_modified integer A Unix timestamp representing the date and time the beer was last modified.

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",
      "last_modified": 1708905600
     },
     {
      "id": "e9a9936e-332c-aa6c-8dcf-70309b483db7",
      "name": "Abandon Ship",
      "last_modified": 1706313600
    },
    {
      "id": "b4d1c9f3-cb4a-c364-f1f0-a71a94295ead",
      "name": "Abandon Ship with Chipotle",
      "last_modified": 1706313600
    }
  ]
}

^ 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

Search for beer by name, style, or description using full-text search. To search, send a GET request to the /beer/search endpoint with a q query parameter.

GET https://api.catalog.beer/beer/search?q={query}

Query Parameters

Name Type Description
q string The search query string. Maximum 255 characters.
count
(optional)		 integer The number of results you would like returned. The default value is 25. Maximum is 100.
cursor
(optional)		 string An 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.

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

GET https://api.catalog.beer/beer/search?q=ipa&count=5

Response

This request returns a list object with the following parameters. Results are sorted by relevance to the search query. Each result is a full beer object including the nested brewer object, so you can display results without making additional API calls.

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/search.
query string The search query that was submitted.
has_more Boolean Whether or not there are more results available. If false, you have reached the last items in the result set.
next_cursor
(optional)		 string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request. Only present when has_more is true.
data array An array of beer objects matching the search query, sorted by relevance. Each beer object includes a nested brewer object.

Sample Request

curl -X GET \
  'https://api.catalog.beer/beer/search?q=ipa&count=2' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/beer/search",
  "query": "ipa",
  "has_more": true,
  "next_cursor": "Mg==",
  "data": [
    {
      "id": "e9a9936e-332c-aa6c-8dcf-70309b483db7",
      "object": "beer",
      "name": "Stone IPA",
      "style": "India Pale Ale",
      "description": "A well-hopped West Coast IPA...",
      "abv": 6.9,
      "ibu": 77,
      "cb_verified": true,
      "brewer_verified": false,
      "last_modified": 1737234000,
      "brewer": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "object": "brewer",
        "name": "Stone Brewing",
        "description": "Stone Brewing, founded in 1996...",
        "short_description": "San Diego craft brewery",
        "url": "https://www.stonebrewing.com/",
        "cb_verified": true,
        "brewer_verified": false,
        "last_modified": 1737234000
      }
    }
  ]
}

^ 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.
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.
cb_verified Boolean A true or false value denoting whether or not a Catalog.beer administrator has verified the location’s information.
brewer_verified Boolean A true or false value denoting whether or not the brewer themselves has contributed and verified the location’s information.
last_modified integer A Unix timestamp indicating when the location was last modified.
address
(optional)		 object At this time, the database supports addresses for locations in the United States. See the US Addresses object. The telephone field is included within this object.
brewer object A brewer object containing information on the brewer associated with this location.

Sample

Sample location object with a US address.

{
    "id": "4920c879-76a6-4bb7-dccf-5f2642e28c08",
    "object": "location",
    "name": "San Diego",
    "url": "",
    "country_code": "US",
    "country_short_name": "United States of America",
    "latitude": 32.8882179,
    "longitude": -117.1498184,
    "cb_verified": true,
    "brewer_verified": false,
    "last_modified": 1736729100,
    "address": {
        "address1": "",
        "address2": "9990 Alesmith Ct",
        "city": "San Diego",
        "sub_code": "US-CA",
        "state_short": "CA",
        "state_long": "California",
        "zip5": 92126,
        "zip4": 4200,
        "telephone": 8585499888
    },
    "brewer": {
        "id": "634996c1-5ffb-9099-b015-11cbfe8bb53f",
        "object": "brewer",
        "name": "AleSmith Brewing Company",
        "description": "",
        "short_description": "",
        "url": "https://alesmith.com/",
        "cb_verified": true,
        "brewer_verified": false,
        "last_modified": 1736103600
    }
}

^ 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",
  "url": "",
  "country_code": "US",
  "country_short_name": "United States of America",
  "latitude": null,
  "longitude": null,
  "cb_verified": false,
  "brewer_verified": false,
  "last_modified": 1738429200,
  "brewer": {
    "id": "050a11d3-0364-1eef-442f-82909ecadb1b",
    "object": "brewer",
    "name": "Brouwerij West",
    "description": "",
    "short_description": "",
    "url": "",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1738103400
  }
}

^ Return to top

Update a Location (PUT)

To replace a location’s data, send a PUT request to the /location endpoint with the location_id appended to the path. All required fields must be present. Omitted optional fields will be cleared to null. If the location does not exist, it will be created and a 201 Created response will be returned. Successful requests return a location object.

PUT https://api.catalog.beer/location/{location_id}
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.
country_code string The ISO 3166–1 Alpha–2 Code for the country in which the location is located.
url
(optional)		 string A URL specific to the location. Cleared if omitted.

Sample Request

curl -X PUT \
  https://api.catalog.beer/location/e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"brewer_id":"050a11d3-0364-1eef-442f-82909ecadb1b","name":"Wrigley","country_code":"US","url":"https://www.brouwerijwest.com/wrigley"}'

^ Return to top

Update a Location (PATCH)

To partially update a location, send a PATCH request to the /location endpoint with the location_id appended to the path. Only the fields you include will be updated; all other fields remain unchanged. Successful requests return a location object.

PATCH https://api.catalog.beer/location/{location_id}
Parameter Type Description
brewer_id
(optional)		 string The brewer_id for the brewer you would like to associate the location with.
name
(optional)		 string The name of the location.
country_code
(optional)		 string The ISO 3166–1 Alpha–2 Code for the country in which the location is located.
url
(optional)		 string A URL specific to the location.

Sample Request

curl -X PATCH \
  https://api.catalog.beer/location/e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"name":"Wrigley Taproom"}'

^ Return to top

Delete a Location

To delete a location, send a DELETE request to the /location endpoint with the location_id appended to the path. No request body is required. Successful requests return a 204 No Content response with no body.

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

Sample Request

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

^ 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 /address endpoint with the location_id appended to the path and the 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/address/{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/address/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",
  "url": "",
  "country_code": "US",
  "country_short_name": "United States of America",
  "latitude": 33.7946519,
  "longitude": -118.1891897,
  "cb_verified": false,
  "brewer_verified": false,
  "last_modified": 1738429500,
  "address": {
    "address1": "",
    "address2": "518 W Willow St",
    "city": "Long Beach",
    "sub_code": "US-CA",
    "state_short": "CA",
    "state_long": "California",
    "zip5": 90806,
    "zip4": null,
    "telephone": null
  },
  "brewer": {
    "id": "050a11d3-0364-1eef-442f-82909ecadb1b",
    "object": "brewer",
    "name": "Brouwerij West",
    "description": "",
    "short_description": "",
    "url": "",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1738103400
  }
}

^ Return to top

Replace an Address

To create or replace an address for a location, send a PUT request to the /address endpoint with the location_id appended to the path. This will completely replace any existing address data for the location. Omitted optional fields will be cleared to null. Successful requests will return a location object.

PUT https://api.catalog.beer/address/{location_id}
Parameter Type Description
address1
(optional)		 string The suite or unit number of the location (if applicable - e.g. Suite 101). Cleared if omitted.
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. Cleared if omitted.
telephone
(optional)		 string The 10-digit telephone number for the location. Cleared if omitted.

Sample Request

curl -X PUT \
  https://api.catalog.beer/address/e00c24d6-de81-2ea4-dfd8-cd6f2cb5f1e7 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"address2":"518 W Willow St","city":"Long Beach","sub_code":"US-CA"}'

^ 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 search 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
(optional)		 string To retrieve the next set of results, provide this value as the cursor parameter on your subsequent API request. Only present when has_more is true.
data array

An array containing all the locations that match your query parameters. Each result contains three objects:

  • A location object containing: id, object, name, brewer_id, url, country_code, country_short_name, latitude, longitude, telephone, and a nested address object
  • A distance object described below
  • A brewer object containing: id, object, name, description, short_description, url, cb_verified, brewer_verified
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.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.12854,
        "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": null,
        "short_description": null,
        "url": "https://www.mikehessbrewing.com/",
        "cb_verified": true,
        "brewer_verified": false
      }
    }
  ]
}

^ Return to top

Find Locations by ZIP Code

Find nearby brewery locations by providing a US ZIP code. This endpoint geocodes the ZIP code and returns locations within the search radius, just like the Find Nearby Locations endpoint.

Send a GET request to the /location/zip endpoint with the zip_code query parameter.

Query Parameters

Name Type Description
zip_code string A 5-digit US ZIP code (e.g., 92104).
search_radius
(optional)		 integer The radius of the search circle, centered at the provided ZIP code. 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 search radius and results measured in miles.
cursor
(optional)		 string An 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.

Response

The response format is identical to the Find Nearby Locations endpoint, returning a list object with location, distance, and brewer objects for each result. The url field will be /location/zip.

Sample Request

curl -X GET \
  'https://api.catalog.beer/location/zip?zip_code=92104&search_radius=10&count=1' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/location/zip",
  "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.12854,
        "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": null,
        "short_description": null,
        "url": "https://www.mikehessbrewing.com/",
        "cb_verified": true,
        "brewer_verified": false
      }
    }
  ]
}

^ Return to top

Find Locations by City

Find nearby brewery locations by providing a city and state. This endpoint geocodes the city and returns locations within the search radius, just like the Find Nearby Locations endpoint.

Send a GET request to the /location/city endpoint with the city and state query parameters.

Query Parameters

Name Type Description
city string The name of the city to search around (e.g., San Diego).
state string The state name or abbreviation (e.g., California or CA).
search_radius
(optional)		 integer The radius of the search circle, centered at the provided city. 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 search radius and results measured in miles.
cursor
(optional)		 string An 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.

Response

The response format is identical to the Find Nearby Locations endpoint, returning a list object with location, distance, and brewer objects for each result. The url field will be /location/city.

Sample Request

curl -X GET \
  'https://api.catalog.beer/location/city?city=San%20Diego&state=CA&search_radius=10&count=1' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/location/city",
  "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.12854,
        "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": 2.3,
        "units": "miles"
      },
      "brewer": {
        "id": "008fdcf3-b59d-9d7e-6b14-540a88bb36fa",
        "object": "brewer",
        "name": "Mike Hess Brewing Co.",
        "description": null,
        "short_description": null,
        "url": "https://www.mikehessbrewing.com/",
        "cb_verified": true,
        "brewer_verified": false
      }
    }
  ]
}

^ 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.
telephone
(optional)		 integer An unformatted integer 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.

^ Return to top

Users

The users endpoints allow you to manage your own account. User accounts are created through the Catalog.beer website, not directly via the API.

The User Object

Successful requests to user endpoints will return the user object in JSON format. That object has the following parameters.

Parameter Type Description
id string The user_id; a unique identifier for the user.
object string The name of the object. In this case: “users”.
name string The user’s name.
email string The user’s email address.
email_verified Boolean A true or false value denoting whether the user’s email address has been verified.
email_auth string/null The email verification code, or null if the email has already been verified.
email_auth_sent integer/null A Unix timestamp indicating when the email verification was sent, or null.
admin Boolean A true or false value denoting whether the user has administrator privileges.

Sample

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "users",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "email_verified": true,
  "email_auth": null,
  "email_auth_sent": null,
  "admin": false
}

^ Return to top

Retrieve a User

To retrieve your user information, send a GET request to the /users endpoint with your {user_id} appended to the path. You can only retrieve your own user information.

GET https://api.catalog.beer/users/{user_id}

A user object will be returned for successful requests.

Sample Request

curl -X GET \
  https://api.catalog.beer/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

Get API Key

To retrieve your API key, send a GET request to the /users/{user_id}/api-key endpoint. You can only retrieve your own API key. The API key will be null if your email address has not yet been verified.

GET https://api.catalog.beer/users/{user_id}/api-key

Response

Parameter Type Description
object string The name of the object. In this case: “api_key”.
user_id string The user_id associated with the API key.
api_key string/null The API key, or null if the user’s email has not been verified.

Sample Request

curl -X GET \
  https://api.catalog.beer/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-key \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "api_key",
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "cadcbe6f-a80d-4e33-9f20-b53c2ed83845"
}

^ Return to top

Update a User (PATCH)

To update your account, send a PATCH request to the /users endpoint with your user_id appended to the path. Only the fields you include will be updated; all other fields remain unchanged. Successful requests return a user object.

PATCH https://api.catalog.beer/users/{user_id}
Parameter Type Description
name
(optional)		 string The user’s name. Max 255 characters.
email
(optional)		 string The user’s email address. Changing your email to a different domain will reset your email verification status and any brewery staff privileges associated with the previous domain.
password
(optional)		 string A new password for the account. Must be at least 8 characters.

Sample Request

curl -X PATCH \
  https://api.catalog.beer/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"name":"Jane Smith"}'

^ Return to top

Delete a User

To delete your account, send a DELETE request to the /users endpoint with your user_id appended to the path. No request body is required. Successful requests return a 204 No Content response with no body. This action permanently deletes your account and associated data.

DELETE https://api.catalog.beer/users/{user_id}

Sample Request

curl -X DELETE \
  https://api.catalog.beer/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

Request Password Reset

To request a password reset, send a POST request to the /users/{user_id}/reset-password endpoint. The user’s email must be verified. A password reset email will be sent to the email address on file. This endpoint is rate limited to one request per 15 minutes. Successful requests return a 204 No Content response.

POST https://api.catalog.beer/users/{user_id}/reset-password

Sample Request

curl -X POST \
  https://api.catalog.beer/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reset-password \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

^ Return to top

Reset Password

To reset your password using a password reset key (received via email), send a POST request to the /users/password-reset/{password_reset_key} endpoint with your new password in the request body. Successful requests return a 204 No Content response.

POST https://api.catalog.beer/users/password-reset/{password_reset_key}
Parameter Type Description
password string The new password. Must be at least 8 characters.

Sample Request

curl -X POST \
  https://api.catalog.beer/users/password-reset/e5f67890-abcd-1234-5678-90abcdef1234 \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{"password":"mynewpassword123"}'

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