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 Styles > The Style Object > List Styles > Retrieve a Style > List Families > List Classes 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 Usage > The Usage Object > Get My Usage US Addresses > The US Address Object Users > The User Object > Retrieve a User > Get API Key > Update a User (PATCH) > Delete a User > Request Password Reset > Reset Password

API Reference

Last Updated: June 25, 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 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 associate 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": "ce7d83f5-0c3d-42f4-9162-ca97019e89d1",
  "object": "brewer",
  "name": "HopSaint Brewing Company",
  "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": 1783639445
}

^ 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 Brewing Company","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\u0027t be confined to the pub. You should choose when, where, how, and with whom you enjoy a fresh, crafted beer. That\u0027s 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/ce7d83f5-0c3d-42f4-9162-ca97019e89d1 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"name":"HopSaint Brewing Company","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\u0027t be confined to the pub. You should choose when, where, how, and with whom you enjoy a fresh, crafted beer. That\u0027s 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 (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/ce7d83f5-0c3d-42f4-9162-ca97019e89d1 \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"short_description":"A 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/ce7d83f5-0c3d-42f4-9162-ca97019e89d1 \
  -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/ce7d83f5-0c3d-42f4-9162-ca97019e89d1 \
  -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 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 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?count=2' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer",
  "has_more": true,
  "next_cursor": "Mg==",
  "data": [
    {
      "id": "19555c52-ade8-43fe-a7a8-5888af0842e9",
      "name": "'t Hofbrouwerijke",
      "last_modified": 1588448205
    },
    {
      "id": "d150fff4-ff71-4171-bd36-fb6dc8a83377",
      "name": "(512) Brewing Company",
      "last_modified": 1588448205
    }
  ]
}

^ 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": 6760
}

^ 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&count=1' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer/search",
  "query": "stone",
  "has_more": true,
  "next_cursor": "MQ==",
  "data": [
    {
      "id": "a751e1bb-e738-4a3a-906b-6a707e082908",
      "object": "brewer",
      "name": "Stone Coast Brewing",
      "description": null,
      "short_description": null,
      "url": "http://www.stonecoast.com/",
      "cb_verified": false,
      "brewer_verified": false,
      "last_modified": 1588448205
    }
  ]
}

^ 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, style, style_id, parent, class, and beverage_type described below.
id string The beer_id.
name string The name of the beer.
style string The style of the beer (human-readable label).
style_id string The canonical style id, or null if filed at the family/class level.
parent string The canonical family id (e.g. porter).
class string The super-class (ale/lager), or null.
beverage_type string beer, cider, perry, or mead.

Sample Request

curl -X GET \
  https://api.catalog.beer/brewer/ab94abb7-a3e8-4cce-8945-4758cac66a53/beer \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer/ab94abb7-a3e8-4cce-8945-4758cac66a53/beer",
  "has_more": false,
  "brewer": {
    "id": "ab94abb7-a3e8-4cce-8945-4758cac66a53",
    "object": "brewer",
    "name": "Ballast Point Brewing Company",
    "description": null,
    "short_description": null,
    "url": "https://www.ballastpoint.com/",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1541544607
  },
  "data": [
    {
      "id": "650f8973-7c09-4cbf-99cd-857e095d84b0",
      "name": "Abandon Ship With Chipotle",
      "style": "Smoke Beer (Lager or Ale)",
      "style_id": "smoke-beer",
      "parent": "smoked-beer",
      "class": null,
      "beverage_type": "beer"
    },
    {
      "id": "36ebef31-f05b-4c78-b7c1-731ed136fe11",
      "name": "Ballast Point Belgian-Style Tripel",
      "style": "Belgian-Style Tripel",
      "style_id": "belgian-tripel",
      "parent": "belgian-strong-ale",
      "class": "ale",
      "beverage_type": "beer"
    },
    {
      "id": "e778b401-0c2b-4bc0-8b53-ccb59860c1bf",
      "name": "Ballast Point Red Velvet Cake",
      "style": "Chocolate / Cocoa-Flavored Beer",
      "style_id": "chocolate-beer",
      "parent": "flavored-beer",
      "class": null,
      "beverage_type": "beer"
    }
  ]
}

Response truncated for documentation — this brewer has 81 beers in its data array.

^ 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/ab94abb7-a3e8-4cce-8945-4758cac66a53/locations \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/brewer/ab94abb7-a3e8-4cce-8945-4758cac66a53/locations",
  "has_more": false,
  "brewer": {
    "id": "ab94abb7-a3e8-4cce-8945-4758cac66a53",
    "object": "brewer",
    "name": "Ballast Point Brewing Company",
    "description": null,
    "short_description": null,
    "url": "https://www.ballastpoint.com/",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1541544607
  },
  "data": [
    {
      "id": "76b558cd-a5f7-4fbe-820a-7a9dc9a924fe",
      "name": "Chicago"
    },
    {
      "id": "e6c0250b-f179-48ac-8eab-a97c5159c733",
      "name": "Daleville"
    },
    {
      "id": "4ece62c7-38c2-41a2-a4db-02048e46fe55",
      "name": "Home Brew Mart"
    },
    {
      "id": "972dc9a3-4462-48b5-9a0f-eb0ab6f94738",
      "name": "Little Italy"
    },
    {
      "id": "275047c9-72f4-4bec-a61e-26bf2b9d3f3e",
      "name": "Long Beach"
    },
    {
      "id": "baa6cb7d-391b-4755-8881-b4a123ed821a",
      "name": "Miramar"
    },
    {
      "id": "132eece9-6d63-42a4-81b1-0177a0050414",
      "name": "Scripps Ranch"
    },
    {
      "id": "2cc26eda-0028-4821-8e8f-df48c7688f77",
      "name": "Temecula"
    },
    {
      "id": "795b4249-04ed-4061-beda-9273a5feeabd",
      "name": "The Kettle Room"
    }
  ]
}

^ 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 as a human-readable label — the brewer’s own wording, preserved exactly (e.g. “West Coast IPA”).
style_id string The canonical style the label resolved to (e.g. american-ipa), or null when the beer is filed at the family or class level rather than a specific style.
parent string The canonical family (e.g. ipa) the beer belongs to. Derived from style_id, or set directly when filed at the family level.
class string The super-class the beer rolls up to: ale or lager, or null for families that do not roll up to one (wheat, sour, cider, mead, etc.).
beverage_type string One of beer, cider, perry, or mead. Derived from the resolved style; never trusted from client input.
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": "6a7119c6-92a2-40d2-b87a-2e4529c8577a",
  "object": "beer",
  "name": "Sculpin IPA",
  "style": "American-Style India Pale Ale",
  "style_id": "american-ipa",
  "parent": "ipa",
  "class": "ale",
  "beverage_type": "beer",
  "description": "Our Sculpin IPA is a great example of what got us into brewing in the first place. After years of experimenting, we knew hopping an ale at five separate stages would produce something special. The result ended up being this gold-medal winning IPA, whose inspired use of hops creates hints of apricot, peach, mango and lemon flavors.",
  "abv": 7,
  "ibu": 70,
  "cb_verified": true,
  "brewer_verified": false,
  "last_modified": 1783642824,
  "brewer": {
    "id": "ab94abb7-a3e8-4cce-8945-4758cac66a53",
    "object": "brewer",
    "name": "Ballast Point Brewing Company",
    "description": null,
    "short_description": null,
    "url": "https://www.ballastpoint.com/",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1541544607
  }
}

^ 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

The style you submit is kept exactly as you wrote it and matched to the catalog’s standard list of styles — for example, “West Coast IPA” resolves to the west-coast-ipa style, “IPA” to the ipa family, and “Lager” to the lager class. To name the classification yourself, send style_id, parent, or class; if you send more than one, the most specific wins. If the label doesn’t match and no classification is given, the request returns a 400 Bad Request error. See Styles.

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 brewer’s style label, resolved to a canonical style/family/class (see note above). Required unless you supply style_id, parent, or class.
style_id
(optional)		 string File at a specific canonical style (e.g. american-ipa). Takes precedence over style.
parent
(optional)		 string File at a family (e.g. ipa) without choosing a specific style.
class
(optional)		 string File at a super-class: ale or lager.
description
(optional)		 string A description of the beer. This may be a basic description, or it can be detailed, containing 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": "ab94abb7-a3e8-4cce-8945-4758cac66a53", "name": "Sculpin IPA", "style": "American-Style India Pale Ale", "description": "Our Sculpin IPA is a great example of what got us into brewing in the first place. After years of experimenting, we knew hopping an ale at five separate stages would produce something special. The result ended up being this gold-medal winning IPA, whose inspired use of hops creates hints of apricot, peach, mango and lemon flavors.", "abv": 7, "ibu": 70}'

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

The style fields work the same as when adding a beer: send the label as style, or name the classification with style_id, parent, or class. If the label doesn’t match and no classification is given, the request returns a 400 Bad Request error — unless the label is unchanged from the beer’s current style, in which case the update succeeds and the beer keeps its current classification. See Styles.

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 brewer’s style label, resolved to a canonical style/family/class. Required unless you supply style_id, parent, or class.
style_id
(optional)		 string File at a specific canonical style (e.g. american-ipa). Takes precedence over style.
parent
(optional)		 string File at a family (e.g. ipa) without choosing a specific style.
class
(optional)		 string File at a super-class: ale or lager.
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/6a7119c6-92a2-40d2-b87a-2e4529c8577a \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"brewer_id": "ab94abb7-a3e8-4cce-8945-4758cac66a53", "name": "Sculpin IPA", "style": "American-Style India Pale Ale", "description": "Our Sculpin IPA is a great example of what got us into brewing in the first place. After years of experimenting, we knew hopping an ale at five separate stages would produce something special. The result ended up being this gold-medal winning IPA, whose inspired use of hops creates hints of apricot, peach, mango and lemon flavors.", "abv": 7, "ibu": 70}'

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

To change a beer’s style, send any of style, style_id, parent, or class. The style is re-resolved and all of the beer’s classification fields are updated together. Resending the beer’s current style unchanged never fails — the beer keeps its current classification. See Styles.

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 brewer’s style label, re-resolved to a canonical style/family/class.
style_id
(optional)		 string File at a specific canonical style (e.g. american-ipa).
parent
(optional)		 string File at a family (e.g. ipa).
class
(optional)		 string File at a super-class: ale or lager.
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/6a7119c6-92a2-40d2-b87a-2e4529c8577a \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"abv":7,"ibu":70}'

^ 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/6a7119c6-92a2-40d2-b87a-2e4529c8577a \
  -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/6a7119c6-92a2-40d2-b87a-2e4529c8577a \
  -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 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 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?count=3' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/beer",
  "has_more": true,
  "next_cursor": "Mw==",
  "data": [
    {
      "id": "ed8d5bcd-9016-4954-9f4c-81855dbad55a",
      "name": "¡Ándale! Pale Ale",
      "last_modified": 1588448205
    },
    {
      "id": "64cd7a20-ebf3-4358-bacf-180d1b7d9b96",
      "name": "¡Guava Libre!",
      "last_modified": 1588448205
    },
    {
      "id": "5e4bf0c1-c743-4438-9289-6e77c17ad467",
      "name": "¡Magnifico!",
      "last_modified": 1588448205
    }
  ]
}

^ 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": 60605
}

^ 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=sculpin&count=1' \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \

Sample Response

{
  "object": "list",
  "url": "/beer/search",
  "query": "sculpin",
  "has_more": true,
  "next_cursor": "MQ==",
  "data": [
    {
      "id": "6a7119c6-92a2-40d2-b87a-2e4529c8577a",
      "object": "beer",
      "name": "Sculpin IPA",
      "style": "American-Style India Pale Ale",
      "style_id": "american-ipa",
      "parent": "ipa",
      "class": "ale",
      "beverage_type": "beer",
      "description": "Our Sculpin IPA is a great example of what got us into brewing in the first place. After years of experimenting, we knew hopping an ale at five separate stages would produce something special. The result ended up being this gold-medal winning IPA, whose inspired use of hops creates hints of apricot, peach, mango and lemon flavors.",
      "abv": 7,
      "ibu": 70,
      "cb_verified": true,
      "brewer_verified": false,
      "last_modified": 1783642824,
      "brewer": {
        "id": "ab94abb7-a3e8-4cce-8945-4758cac66a53",
        "object": "brewer",
        "name": "Ballast Point Brewing Company",
        "description": null,
        "short_description": null,
        "url": "https://www.ballastpoint.com/",
        "cb_verified": false,
        "brewer_verified": false,
        "last_modified": 1541544607
      }
    }
  ]
}

^ Return to top

Styles

Catalog.beer records a beer’s style in two parts: the brewer’s own label and a canonical classification. The label (beer.style) is plain text, stored and returned exactly as submitted. The classification files the beer against a standard vocabulary of styles, which is what allows the catalog to be sorted, filtered, and counted by style. The vocabulary is drawn from the Brewers Association (BA) and Beer Judge Certification Program (BJCP) style guidelines.

The vocabulary has three tiers, from broadest to most specific. Each tier corresponds to a field on the beer object.

Tier Beer Field Description
Class class The broadest grouping: ale or lager. Some families (e.g. wheat beers, sours, ciders, meads) do not roll up to a class; for those, class is null.
Family parent A group of related styles, such as ipa, stout, or pilsner.
Style style_id One specific style, such as american-ipa or west-coast-ipa.

A beer may be filed at any tier. The API derives the broader tiers from the one you provide — file a beer as west-coast-ipa and its parent is set to ipa and its class to ale. The API never fills in a more specific tier than the one you gave it.

When adding or updating a beer, there are two ways to set the classification:

  1. Send the label as style and let the API match it. The label is checked against every canonical name and alias in the vocabulary — first as an exact style name, then as a class alias, a family alias, and a style alias. For example, “NEIPA,” “New England IPA,” and “Juicy IPA” all resolve to the same style.
  2. Name the classification directly with style_id, parent, or class. These take precedence over style; if you send more than one, the most specific wins. Your label is still kept verbatim.

If the label doesn’t match anything in the vocabulary and no classification is given, the request returns a 400 Bad Request error. The vocabulary includes catch-all styles (catch_all: true — e.g. specialty-beer) for beers that don’t fit a more specific style. One exception: when updating an existing beer, resending its current label unchanged never fails — the beer keeps its current classification, even if that label wouldn’t resolve on its own.

The beer’s beverage_type (beer, cider, perry, or mead) is set from the resolved classification. It cannot be set directly.

The /style endpoints are read-only. Use them to browse the vocabulary, build a style picker, or check a label before submitting a beer.

The Style Object

The /style endpoints return style objects. List Styles returns a compact form of each; Retrieve a Style returns the full object, adding parent_name, source, and specs.

Field Type Description
idstringThe style’s slug (e.g. american-ipa) — the value used as style_id on a beer.
objectstringAlways style.
namestringThe canonical style name (e.g. “American-Style India Pale Ale”).
beverage_typestringOne of beer, cider, perry, or mead.
parentstringThe slug of the family this style belongs to (e.g. ipa) — the canonical family tier you can file a beer at.
classstringThe slug of the class the style rolls up to (ale or lager), or null for families that do not roll up to one.
parent_name
(detail only)		stringThe display name of the parent family (e.g. “India Pale Ale”).
source
(detail only)		stringThe primary guideline the style is drawn from: BA-2026, BJCP-2021, OCB-2012, or NABA-2024.
catch_allBooleantrue for non-standard “catch-all” styles (e.g. specialty-beer) used when nothing more specific fits. Use it to separate fallback buckets from standard styles — for example, keeping catch-alls out of a picker’s ranked matches.
aliasesarrayOther names and spellings that resolve to this style, excluding the canonical name. Use these to match user-entered labels client-side — for example, in a typeahead — without an API request per keystroke.
specs
(detail only)		objectThe style’s guideline ranges — abv, ibu, srm, og, and fg. See the specs field below.

The specs Field

The specs field (detail only) holds the style’s guideline ranges, drawn from the same source as the style. Each field is a { "min": …, "max": … } object, or null when the guideline doesn’t specify that measurement. An individual min or max may also be null when the guideline gives only one bound.

Field Type Description
abvobjectAlcohol by Volume range, as a percentage (e.g. 6.3 means 6.3%).
min and max are floats.
ibuobjectInternational Bitterness Units range — the measure of hop bitterness.
min and max are integers.
srmobjectStandard Reference Method range — beer color, from pale straw (low) to black (high).
min and max are floats.
ogobjectOriginal Gravity range — the wort’s specific gravity before fermentation.
min and max are floats.
fgobjectFinal Gravity range — the beer’s specific gravity after fermentation.
min and max are floats.

Sample

{
  "id": "american-ipa",
  "object": "style",
  "name": "American-Style India Pale Ale",
  "beverage_type": "beer",
  "parent": "ipa",
  "class": "ale",
  "parent_name": "India Pale Ale",
  "source": "BA-2026",
  "catch_all": false,
  "aliases": ["American India Pale Ale", "American IPA"],
  "specs": {
    "abv": { "min": 6.3, "max": 7.5 },
    "ibu": { "min": 50, "max": 70 },
    "srm": { "min": 4, "max": 12 },
    "og":  { "min": 1.06, "max": 1.07 },
    "fg":  { "min": 1.01, "max": 1.016 }
  }
}

^ Return to top

List Styles

To list every style in the vocabulary, send a GET request to the /style endpoint. Styles are returned alphabetically by name as compact style objects. The response also includes a version field identifying the current version of the vocabulary; when it changes, refresh any cached copy.

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

Sample Request

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

Sample Response

{
  "object": "list",
  "url": "/style",
  "version": "2.3.0",
  "has_more": false,
  "data": [
    {
      "id": "american-ipa",
      "object": "style",
      "name": "American-Style India Pale Ale",
      "beverage_type": "beer",
      "parent": "ipa",
      "class": "ale",
      "catch_all": false,
      "aliases": ["American India Pale Ale", "American IPA"]
    }
  ]
}

Response truncated for documentation — the full response contains every style in the vocabulary.

^ Return to top

Retrieve a Style

To retrieve a single style, send a GET request to the /style endpoint with the {style_id} parameter appended to the path. The style_id is the style’s slug (e.g. american-ipa), not a UUID. Successful requests return a full style object, including its specs.

GET https://api.catalog.beer/style/{style_id}

Sample Request

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

Sample Response

{
  "id": "american-ipa",
  "object": "style",
  "name": "American-Style India Pale Ale",
  "beverage_type": "beer",
  "parent": "ipa",
  "class": "ale",
  "parent_name": "India Pale Ale",
  "source": "BA-2026",
  "catch_all": false,
  "aliases": ["American India Pale Ale", "American IPA"],
  "specs": {
    "abv": { "min": 6.3, "max": 7.5 },
    "ibu": { "min": 50, "max": 70 },
    "srm": { "min": 4, "max": 12 },
    "og":  { "min": 1.06, "max": 1.07 },
    "fg":  { "min": 1.01, "max": 1.016 }
  }
}

^ Return to top

List Families

To list the families in the vocabulary (the parent tier), send a GET request to the /style/parent endpoint. Families are returned in display order. Each family object has the following parameters.

GET https://api.catalog.beer/style/parent
Parameter Type Description
slug string The family’s slug (e.g. ipa) — the value used as parent on a beer.
object string The name of the object; in this case: “style_parent”.
name string The name of the family (e.g. “India Pale Ale”).
beverage_type string One of beer, cider, perry, or mead.
class string The slug of the class this family rolls up to (ale or lager), or null if it does not roll up to one.
description string A brief description of the family.
sort_order integer The family’s position in display order.
aliases array Names and spellings that resolve to this family when sent as a beer’s style.

Sample Request

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

Sample Response

{
  "object": "list",
  "url": "/style/parent",
  "has_more": false,
  "data": [
    {
      "slug": "ipa",
      "object": "style_parent",
      "name": "India Pale Ale",
      "beverage_type": "beer",
      "class": "ale",
      "description": "The hop showcase of brewing: pale, bitter, and intensely aromatic ales ranging from crisp, resinous West Coast versions to soft, juicy hazy ones, plus session, double, Belgian, and black variations. Hops drive the aroma, flavor, and bitterness, with malt kept in a supporting role.",
      "sort_order": 2,
      "aliases": ["India Pale Ale", "IPA", "IPAs"]
    }
  ]
}

Response truncated for documentation — the full response contains every family.

^ Return to top

List Classes

To list the classes in the vocabulary — currently ale and lager — send a GET request to the /style/class endpoint. Classes are returned in display order. Each class object has the following parameters.

GET https://api.catalog.beer/style/class
Parameter Type Description
slug string The class’s slug (e.g. ale) — the value used as class on a beer.
object string The name of the object; in this case: “style_class”.
name string The name of the class (e.g. “Ale”).
beverage_type string One of beer, cider, perry, or mead.
sort_order integer The class’s position in display order.
aliases array Names and spellings that resolve to this class when sent as a beer’s style.

Sample Request

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

Sample Response

{
  "object": "list",
  "url": "/style/class",
  "has_more": false,
  "data": [
    {
      "slug": "ale",
      "object": "style_class",
      "name": "Ale",
      "beverage_type": "beer",
      "sort_order": 1,
      "aliases": ["Ale", "Ales"]
    },
    {
      "slug": "lager",
      "object": "style_class",
      "name": "Lager",
      "beverage_type": "beer",
      "sort_order": 2,
      "aliases": ["Lager", "Lagers"]
    }
  ]
}

^ 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": "972dc9a3-4462-48b5-9a0f-eb0ab6f94738",
  "object": "location",
  "name": "Little Italy",
  "url": "https://www.ballastpoint.com/location/ballast-point-little-italy/",
  "country_code": "US",
  "country_short_name": "United States of America",
  "latitude": 32.7276344,
  "longitude": -117.1697159,
  "cb_verified": false,
  "brewer_verified": false,
  "last_modified": 1589147029,
  "address": {
    "address1": null,
    "address2": "2215 India St",
    "city": "San Diego",
    "sub_code": "US-CA",
    "state_short": "CA",
    "state_long": "California",
    "zip5": 92101,
    "zip4": 1725,
    "telephone": 6192557213
  },
  "brewer": {
    "id": "ab94abb7-a3e8-4cce-8945-4758cac66a53",
    "object": "brewer",
    "name": "Ballast Point Brewing Company",
    "description": null,
    "short_description": null,
    "url": "https://www.ballastpoint.com/",
    "cb_verified": false,
    "brewer_verified": false,
    "last_modified": 1541544607
  }
}

^ 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 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"brewer_id":"9f96b99b-9865-4cf0-8950-bdc0d675be9f","name":"San Pedro","country_code":"US"}'

Sample Response

{
  "id": "9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b",
  "object": "location",
  "name": "San Pedro",
  "url": null,
  "country_code": "US",
  "country_short_name": "United States of America",
  "latitude": null,
  "longitude": null,
  "cb_verified": false,
  "brewer_verified": false,
  "last_modified": 1589147029,
  "brewer": {
    "id": "9f96b99b-9865-4cf0-8950-bdc0d675be9f",
    "object": "brewer",
    "name": "Brouwerij West",
    "description": null,
    "short_description": null,
    "url": "https://www.brouwerijwest.com/",
    "cb_verified": true,
    "brewer_verified": false,
    "last_modified": 1517001234
  }
}

^ 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/9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"brewer_id":"9f96b99b-9865-4cf0-8950-bdc0d675be9f","name":"San Pedro","country_code":"US"}'

^ 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/9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"name":"San Pedro"}'

^ 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/9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b \
  -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/9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"address1":"Warehouse No 9","address2":"110 E 22nd St","city":"San Pedro","sub_code":"US-CA","telephone":"3108339330"}'

Sample Response

{
  "id": "9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b",
  "object": "location",
  "name": "San Pedro",
  "url": null,
  "country_code": "US",
  "country_short_name": "United States of America",
  "latitude": 33.7273445,
  "longitude": -118.2799377,
  "cb_verified": false,
  "brewer_verified": false,
  "last_modified": 1589147029,
  "address": {
    "address1": "Warehouse No 9",
    "address2": "110 E 22nd St",
    "city": "San Pedro",
    "sub_code": "US-CA",
    "state_short": "CA",
    "state_long": "California",
    "zip5": 90731,
    "zip4": 7202,
    "telephone": 3108339330
  },
  "brewer": {
    "id": "9f96b99b-9865-4cf0-8950-bdc0d675be9f",
    "object": "brewer",
    "name": "Brouwerij West",
    "description": null,
    "short_description": null,
    "url": "https://www.brouwerijwest.com/",
    "cb_verified": true,
    "brewer_verified": false,
    "last_modified": 1517001234
  }
}

^ 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/9c6a2a29-6c1d-4fdc-ba34-b9c7e2c1e14b \
  -H 'accept: application/json' \
  -H 'authorization: Basic {secret_key}' \
  -H 'content-type: application/json' \
  -d '{"address1":"Warehouse No 9","address2":"110 E 22nd St","city":"San Pedro","sub_code":"US-CA","zip5":"90731","zip4":"7202","telephone":"3108339330"}'

^ 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/972dc9a3-4462-48b5-9a0f-eb0ab6f94738 \
  -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 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.

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": "0b4ee673-8db0-4952-bbd6-cc0b69994c10",
        "object": "location",
        "name": "North Park",
        "brewer_id": "7205f9f1-6bf0-4241-9f0f-35a2351d8450",
        "url": null,
        "country_code": "US",
        "country_short_name": "United States of America",
        "latitude": 32.7476883,
        "longitude": -117.12854,
        "telephone": 6192557136,
        "address": {
          "address1": null,
          "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": "7205f9f1-6bf0-4241-9f0f-35a2351d8450",
        "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": "95a881ef-794a-4f2a-bd5a-ed88cfd1988d",
        "object": "location",
        "name": "North Park Flavordome",
        "brewer_id": "69e7ae7d-9a37-46b3-aa5d-7bf5d092b976",
        "url": "https://www.moderntimesbeer.com/locations/north-park-flavordome/",
        "country_code": "US",
        "country_short_name": "United States of America",
        "latitude": 32.7414894,
        "longitude": -117.129921,
        "telephone": 6192695222,
        "address": {
          "address1": null,
          "address2": "3000 Upas St",
          "city": "San Diego",
          "sub_code": "US-CA",
          "state_short": "CA",
          "state_long": "California",
          "zip5": 92104,
          "zip4": 4221
        }
      },
      "distance": {
        "distance": 0.6,
        "units": "miles"
      },
      "brewer": {
        "id": "69e7ae7d-9a37-46b3-aa5d-7bf5d092b976",
        "object": "brewer",
        "name": "Modern Times Beer",
        "description": null,
        "short_description": null,
        "url": "http://www.moderntimesbeer.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": "7abe715f-0ddf-405e-b730-e2ab1abaef13",
        "object": "location",
        "name": "East Village",
        "brewer_id": "880a8e73-ae38-4466-b6af-f84141ae6996",
        "url": "https://baycitybrewingco.com/visit/tasting-room/",
        "country_code": "US",
        "country_short_name": "United States of America",
        "latitude": 32.7119141,
        "longitude": -117.1571503,
        "telephone": 6197701844,
        "address": {
          "address1": null,
          "address2": "627 8th Ave",
          "city": "San Diego",
          "sub_code": "US-CA",
          "state_short": "CA",
          "state_long": "California",
          "zip5": 92101,
          "zip4": 6453
        }
      },
      "distance": {
        "distance": 0.3,
        "units": "miles"
      },
      "brewer": {
        "id": "880a8e73-ae38-4466-b6af-f84141ae6996",
        "object": "brewer",
        "name": "Bay City Brewing",
        "description": "Our brewing facility is located in the heart of San Diego between Mission Bay and San Diego Bay. From craft beer and cocktails to delicious food and wine, we strive to make every experience memorable.\r\n\r\nThe Bay City Brewing Company was established in San Diego, California in 1912 (incorporated in 1911). It was initially controlled by F.C. and August Lang, J.H. Zitt’s father-in-law and brother-in-law. Today, the Bay City Brewing Company is owned and operated by its partners Chad Robley, Ben Dubois, and Greg Anderson – all local San Diegans.",
        "short_description": null,
        "url": "http://baycitybrewingco.com/",
        "cb_verified": true,
        "brewer_verified": false
      }
    }
  ]
}

^ Return to top

Usage

The usage endpoints allow you to check your API usage for the current billing period. Each API key has a monthly request limit (default: 1,000 requests). Requests to the /usage endpoints are not counted against your limit.

The Usage Object

Parameter Type Description
object string The name of the object. In this case: “usage”.
api_key string The API key associated with this usage record.
year integer The year of the current billing period (e.g. 2026).
month integer The month of the current billing period (1–12).
count integer The number of API requests made during the current billing period.
request_limit integer The maximum number of requests allowed per month for this API key.
request_buffer integer A grace zone beyond the request limit. Requests will not be blocked until count exceeds request_limit + request_buffer.
resets_on string The date your usage count resets, formatted as YYYY-MM-DD (always the first of the next month).
last_updated integer Unix timestamp of the last time the usage counter was updated. Returns 0 if no requests have been made this month.

^ Return to top

Get My Usage

To retrieve your current API usage and limits, send a GET request to the /usage/my-usage endpoint. This returns your usage for the current billing period. No special permissions are required—the endpoint returns data for the authenticated API key.

GET https://api.catalog.beer/usage/my-usage

A usage object will be returned for successful requests.

Sample Request

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

Sample Response

{
  "object": "usage",
  "api_key": "cadcbe6f-a80d-4e33-9f20-b53c2ed83845",
  "year": 2026,
  "month": 3,
  "count": 142,
  "request_limit": 1000,
  "request_buffer": 50,
  "resets_on": "2026-04-01",
  "last_updated": 1741723456
}

Rate Limiting

When your usage exceeds your request_limit + request_buffer, the API will return a 429 Too Many Requests response for all non-usage endpoints. Your count resets on the first of each month. To request a higher limit, contact us.

^ Return to top

US Addresses

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

Project

Legal

Free to use, free to build on.

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 license does not apply to any brewery’s name, brand(s), or trademarks, which remain the property of their respective owners.

Catalog.beer The Internet’s Beer Database