Punk APIV2

Root Endpoint

The root endpoint should prefix all resources and is only accessible over HTTPS. CORS is also enabled.

https://api.punkapi.com/v2/

Authentication

In V2 I decided to remove authentication and instead rely on rate limits from IP addresses, see section below for more details.

Rate Limits

To make sure everyone can access the API reliably, each IP that makes a request has a rate limit of 3600 requests per hour.

This works out at 1 req/sec. This is an initial figure, if the servers hold up I will definitely consider bumping this number.

You can see what the rate limit is and how many requests are remaining by looking at the rate limit headers sent in the response.

x-ratelimit-limit: 3600
x-ratelimit-remaining: 3587

Parameters

All parameters are optional and without them the API will just return the beers in ascending order from their ID. Parameters are passed in as a query string and can be chained together.

If a parameter is passed without a value it will return a 400 error.

$ curl https://api.punkapi.com/v2/beers?brewed_before=11-2012&abv_gt=6

Pagination

Requests that return multiple items will be limited to 25 results by default. You can access other pages using the ?page paramater, you can also increase the amount of beers returned in each request by changing the ?per_page paramater.

$ curl https://api.punkapi.com/v2/beers?page=2&per_page=80

Get Beers

Gets beers from the api, you can apply several filters using url paramaters, the available options are listed below.

$ curl https://api.punkapi.com/v2/beers
Param Type Details
abv_gt number Returns all beers with ABV greater than the supplied number
abv_lt number Returns all beers with ABV less than the supplied number
ibu_gt number Returns all beers with IBU greater than the supplied number
ibu_lt number Returns all beers with IBU less than the supplied number
ebc_gt number Returns all beers with EBC greater than the supplied number
ebc_lt number Returns all beers with EBC less than the supplied number
beer_name string Returns all beers matching the supplied name (this will match partial strings as well so e.g punk will return Punk IPA), if you need to add spaces just add an underscore (_).
yeast string Returns all beers matching the supplied yeast name, this performs a fuzzy match, if you need to add spaces just add an underscore (_).
brewed_before date Returns all beers brewed before this date, the date format is mm-yyyy e.g 10-2011
brewed_after date Returns all beers brewed after this date, the date format is mm-yyyy e.g 10-2011
hops string Returns all beers matching the supplied hops name, this performs a fuzzy match, if you need to add spaces just add an underscore (_).
malt string Returns all beers matching the supplied malt name, this performs a fuzzy match, if you need to add spaces just add an underscore (_).
food string Returns all beers matching the supplied food string, this performs a fuzzy match, if you need to add spaces just add an underscore (_).
ids string (id|id|...) Returns all beers matching the supplied ID's. You can pass in multiple ID's by separating them with a | symbol.

Get a Single Beer

Gets a beer from the api using the beers id.

$ curl https://api.punkapi.com/v2/beers/1

Get Random Beer

Gets a random beer from the API, this takes no paramaters.

$ curl https://api.punkapi.com/v2/beers/random

Example Response

All beer endpoints return a json array with a number of beer objects inside.

[
  {
    "id": 192,
    "name": "Punk IPA 2007 - 2010",
    "tagline": "Post Modern Classic. Spiky. Tropical. Hoppy.",
    "first_brewed": "04/2007",
    "description": "Our flagship beer that kick started the craft beer revolution. This is James and Martin's original take on an American IPA, subverted with punchy New Zealand hops. Layered with new world hops to create an all-out riot of grapefruit, pineapple and lychee before a spiky, mouth-puckering bitter finish.",
    "image_url": "https://images.punkapi.com/v2/192.png",
    "abv": 6.0,
    "ibu": 60.0,
    "target_fg": 1010.0,
    "target_og": 1056.0,
    "ebc": 17.0,
    "srm": 8.5,
    "ph": 4.4,
    "attenuation_level": 82.14,
    "volume": {
      "value": 20,
      "unit": "liters"
    },
    "boil_volume": {
      "value": 25,
      "unit": "liters"
    },
    "method": {
      "mash_temp": [
        {
          "temp": {
            "value": 65,
            "unit": "celsius"
          },
          "duration": 75
        }
      ],
      "fermentation": {
        "temp": {
          "value": 19.0,
          "unit": "celsius"
        }
      },
      "twist": null
    },
    "ingredients": {
      "malt": [
        {
          "name": "Extra Pale",
          "amount": {
            "value": 5.3,
            "unit": "kilograms"
          }
        }
      ],
      "hops": [
        {
          "name": "Ahtanum",
          "amount": {
            "value": 17.5,
            "unit": "grams"
           },
           "add": "start",
           "attribute": "bitter"
         },
         {
           "name": "Chinook",
           "amount": {
             "value": 15,
             "unit": "grams"
           },
           "add": "start",
           "attribute": "bitter"
         },
         ...
      ],
      "yeast": "Wyeast 1056 - American Aleā„¢"
    },
    "food_pairing": [
      "Spicy carne asada with a pico de gallo sauce",
      "Shredded chicken tacos with a mango chilli lime salsa",
      "Cheesecake with a passion fruit swirl sauce"
    ],
    "brewers_tips": "While it may surprise you, this version of Punk IPA isn't dry hopped but still packs a punch! To make the best of the aroma hops make sure they are fully submerged and add them just before knock out for an intense hop hit.",
    "contributed_by": "Sam Mason <samjbmason>"
  }
]