API Documentation

Connecting to the API

The base URL for the version 2 of our API is http://api.brewerydb.com/v2/. Version 1 of the API is still available at the old URL of http://www.brewerydb.com/api however this API is no longer supported.


API Apps/Keys

Every request to the BreweryDB API requires an API key to be passed along with the request. An API key is generated automatically for you when you create a new app. Once your app is approved by our staff (typically takes at most a few hours), you will have access to the API. You can register a new app via the My Apps link above. Please keep your API key private!

Our API expects your key to be passed via the URL with the key parameter. So if your key was abcdef, you would send a request to http://api.brewerydb.com/v2/?key=abcdef.


Return Types

Our API offers 3 return types: JSON, XML and serialized PHP. Just like your API key, you can specify the return type by passing the format parameter in the query string of the request. The options you can pass are json, xml, or php. If you do not pass any format parameter, JSON will be returned.

You may also pass the format parameter by passing an option via the HTTP_ACCEPT header. You can pass application/json, application/xml, or text/php.


Sending Endpoint Arguments

When sending data to BreweryDB, either for filtering on listing endpoints or for submitting new data, you should pass all your data using application/x-www-form-urlencoded strings. For GET methods, these are passed via the query string (after the "?" in the request URL). For POST and PUT methods, these should be passed in the POST body.


Request Limit

Each key for users with standard access has a request limit of 400 requests per day on the read methods. Premium users have unlimited read requests. Write methods have no daily limit, meaning that you can write to our API as much as you want and it will not go against your request limit. If you need more requests than the 400 provided, consider upgrading to our Premium tier which has unlimited requests. The request counter resets every night at midnight Eastern Standard Time.


Status Values

All of the main attributes in BreweryDB (beers, breweries, guilds, events and locations) have status fields associated with them. Because BreweryDB is a curated service, these status fields give API users hints as to what state a given entity is in. The possible status values are:

Status Description
verified Our staff has looked at the entity and has verified (to our best ability) the accuracy.
new_unverified When a new entity comes in, it gets the "new_unverified" status code until our moderation staff approves it, turning it to "verified".
update_pending If an update for the attribute or any of it's relationships comes in, it is set to "update_pending" until our staff verifies the change and integrates the changes. It's important to note that the actual change that was made is not updated on the entity until our staff verifies it. For example, if you renamed beer AAAAAA from "Budweiser" to "Bud", and then queried the API for beer AAAAAA, the name would still be "Budweiser" until our staff integrated the change. The status would be set as update_pending, but no actual change to the data would be made yet. Once our staff would verify the change, it would go back to "verified". These are also queued up, so multiple changes can be made and integrated by our staff.
delete_pending If we received a DELETE request for an entity, it would be set as "delete_pending" until our staff verified the entity should be deleted. Once we verify the deletion, the status is set to "deleted" and it is removed from all the search data.
deleted The entity is only able to be found by specifically requesting it by ID. It will not show up in any of the list or search endpoints at all.